nispace.nulls.generate_null_maps

nispace.nulls.generate_null_maps(method, data, parcellation, dist_mat=None, spin_mat=None, parc_space=None, parc_hemi=None, parc_symmetric=False, n_nulls=1000, parc_resample=2, centroids=False, parc_idc_lh=None, parc_idc_rh=None, parc_idc_sc=None, lr_mirror_dist_mat=False, split_hemi=None, parc_name=None, dist_mat_sc=None, parc_space_sc=None, dist_mat_cx=None, parc_space_cx=None, dtype=<class 'float'>, n_proc=1, seed=None, verbose=True, return_dict=False, **kwargs)[source]

Generate spatially-constrained (or fully random) null maps for one or more parcellated inputs.

This is the low-level engine behind permute()’s spatial null models (called internally via core.permute._get_null_maps) — most users will not call it directly. It dispatches to a distance-based surrogate method (nulls_moran(), nulls_burt2018(), nulls_burt2020(), or plain permutation via nulls_random()) or, for cortex-only surface methods, a spin-test method (via generate_spins(), generate_baum_spins, or generate_cornblath_mat + apply_spins()/apply_cornblath_mat), based on method.

Parameters:

  • method (str or tuple of str) – Null method to use. One of the distance-based methods "random", "moran" (aliases "msr", "brainspace"), "variomoran" (alias "variomsr"), "burt2020" (aliases "brainsmash", "variogram"), "burt2018"; or one of the spin-test methods (cortex/surface only) "alexander_bloch", "spin" (alias of "cornblath"), "vasa", "hungarian", "baum", "cornblath". See Citation for the citation of each method. Aliases are canonicalized internally for stable cache keys. For combined cortex+subcortex parcellations, pass a (cx_method, sc_method) tuple or a "cx_method+sc_method" shorthand string (e.g. "spin+moran") to use a spin test for cortex and a distance-based method for subcortex (subcortex cannot itself be spun — sc_method must not be a spin method). There is no implicit default here: this function always requires method to be given explicitly; the “moran” default seen elsewhere in NiSpace is resolved one level up, in Parcellation.get_null_space() / core.permute._get_null_maps.

  • data (array-like, pandas Series, or pandas DataFrame) – One or more parcellated maps to generate nulls for, shape (n_parcels,) or (n_maps, n_parcels). A DataFrame’s index (or a Series’ name) becomes the label(s) attached to the returned NullMaps.

  • parcellation (Parcellation, NIfTI image, GIfTI image, tuple of two GIfTI images, str, or None) – The parcellation the data is defined on. Passing a Parcellation object is preferred — it lets this function reuse already-cached distance/spin matrices and metadata instead of recomputing them. Can be None if a usable dist_mat is already supplied, or for method="random", which needs no spatial information at all.

  • dist_mat (array-like or tuple of two array-likes, optional) – Precomputed parcel-by-parcel distance matrix — a single 2D array (e.g. volumetric/MNI) or a (dist_lh, dist_rh) tuple (surface, one matrix per hemisphere). If given, distance computation is skipped. Ignored for spin methods and for "random". If omitted for a distance-based method, it is computed from parcellation via get_distance_matrix().

  • spin_mat (tuple, optional) – Precomputed spin/rotation data for a spin-test method. Expected shape depends on the method: a (spins_lh, spins_rh) pair of 2D int arrays (as returned by generate_spins()/generate_baum_spins) for "alexander_bloch"/"baum", or a (T_lh, T_rh) pair of 3D arrays (as returned by generate_cornblath_mat) for "cornblath"/"spin". Regenerated (with a warning) if shape/type don’t match; for "vasa"/"hungarian" any provided spin_mat is always discarded and regenerated, since these methods can’t reuse a precomputed rotation set.

  • parc_space (str, optional) – Reference space of the parcellation (e.g. "mni152", "fsaverage", "fsLR"). Required unless it can be inferred from dist_mat’s type (array → assumed "mni152", tuple → assumed "fsaverage", both with a warning) or a Parcellation object.

  • parc_hemi (list of str, optional) – Hemispheres present, e.g. ["L", "R"] or ["L"]. Required for spin methods.

  • parc_symmetric (bool, default=False) – Whether the parcellation is left-right symmetric. Only relevant to lr_mirror_dist_mat (forced off with a warning if this is False).

  • n_nulls (int, default=1000) – Number of null maps/permutations to generate per input map.

  • parc_resample (int or str, default=2) – Forwarded to get_distance_matrix() when a distance matrix must be computed: target voxel size (mm) for volumetric resampling, or a target density string for surface resampling.

  • centroids (bool, default=False) – Forwarded to get_distance_matrix(): use parcel centroid-to-centroid distances (faster) instead of mean voxel/vertex-to-voxel/vertex distances (more precise).

  • parc_idc_lh (array-like of int, optional) – Column positions in data belonging to the left/right hemisphere. Required for spin methods. For distance-based methods, used to determine per-hemisphere null generation and lr_mirror_dist_mat. If only one is given, the other is inferred as its complement (with a warning).

  • parc_idc_rh (array-like of int, optional) – Column positions in data belonging to the left/right hemisphere. Required for spin methods. For distance-based methods, used to determine per-hemisphere null generation and lr_mirror_dist_mat. If only one is given, the other is inferred as its complement (with a warning).

  • parc_idc_sc (array-like of int, optional) – Column positions in data belonging to subcortex. Required when method is a (cx_method, sc_method) tuple (raises ValueError if missing); the complement becomes the cortex index set.

  • lr_mirror_dist_mat (bool, default=False) – If True, average the LH and RH (or cortex/subcortex) distance-matrix blocks together before generating nulls, so the same spatial null structure is imposed symmetrically on both, and symmetrize NaNs in data across hemispheres accordingly. Requires parc_symmetric=True (else disabled with a warning); raises ValueError if the averaged blocks aren’t numerically close afterward (a sanity check on parc_idc_lh/parc_idc_rh).

  • split_hemi (bool, optional) – Whether to generate nulls separately per hemisphere block. Defaults to whether dist_mat is a tuple (surface) or not (volumetric).

  • parc_name (str, optional) – Informational label, forwarded through recursive split-path calls; not otherwise used.

  • dist_mat_sc (optional) – Precomputed subcortex-only distance matrix and its space, used in the split (sc_method is not None) path to avoid ever computing a full combined distance matrix. Preferred over slicing a full dist_mat.

  • parc_space_sc (optional) – Precomputed subcortex-only distance matrix and its space, used in the split (sc_method is not None) path to avoid ever computing a full combined distance matrix. Preferred over slicing a full dist_mat.

  • dist_mat_cx (optional) – Same as above, for the cortex-only sub-call in the split path (only relevant when cx_method is not itself a spin method).

  • parc_space_cx (optional) – Same as above, for the cortex-only sub-call in the split path (only relevant when cx_method is not itself a spin method).

  • dtype (data-type, default=float) – Output dtype for the returned null maps (and for internal distance-matrix arrays).

  • n_proc (int, default=1) – Parallel workers: used both inside get_distance_matrix() and to parallelize null generation across the rows (maps) of data via joblib.Parallel.

  • seed (int, optional) – Base random seed. If given, row i of data is seeded with seed + i — this keeps results reproducible under parallelism, but means rows are not independently drawn in the strict i.i.d. sense. If omitted, a random base seed is drawn once.

  • verbose (bool, default=True) – Whether to print progress messages and progress bars.

  • return_dict (bool, default=False) – Deprecated. If True, returns a plain {label: null_array} dict instead of a NullMaps object. The returned NullMaps already supports dict-like access, so there is no remaining reason to use this.

  • **kwargs – Forwarded to the underlying null-generating function for distance-based methods — e.g. fit_variogram, procedure, joint, n_components for nulls_moran(); resample, batch_size for nulls_burt2020(). NiSpace’s higher-level API (permute()) exposes these via maps_*-prefixed keyword arguments that get stripped and forwarded here.

Returns:

  • null_maps (NullMaps) – The generated null maps, shape (n_maps, n_nulls, n_parcels), labeled by data’s index/name (or a positional range if unlabeled). A plain dict instead if return_dict=True (deprecated).

  • result_mat (array-like or tuple) – The distance matrix or spin matrix actually used — identical to what was passed in via dist_mat/spin_mat if provided, or the freshly computed/generated one otherwise. Returned so callers can cache and reuse it across repeated calls.

Raises:

  • ValueError – For an unrecognized method; a missing parc_idc_sc when a split method is requested; a spin method requested for sc_method; a non-surface or incomplete parcellation for spin methods; inconsistent/empty/duplicate hemisphere or subcortex index sets; a non-square or missing distance-matrix block; a failed lr_mirror_dist_mat symmetry check; or non-array-like data.

  • TypeError – For an unrecognized parcellation object type.

  • ImportError – If method resolves to nulls_burt2020() and the optional brainsmash package is not installed.

Notes

See Citation for the citation of each null method.