nispace.workflows.paired_colocalization

nispace.workflows.paired_colocalization(y, x, z=None, standardize='xz', space='MNI152NLin6Asym', data_space=None, parcellation_space=None, parcellation='Yan200', parcellation_labels=None, parcellation_hemi=['L', 'R'], colocalization_method='spearman', pooled_p='mean', plot=True, n_perm=10000, seed=None, n_proc=1, verbose=True, nispace_object=None, init_kwargs=None, fit_kwargs=None, colocalize_kwargs=None, permute_kwargs=None, plot_kwargs=None)[source]

Within-pair colocalization workflow (SPICE test).

Tests whether within-pair correspondence between two brain map modalities (correlation across parcels per pair, averaged over pairs) is significantly greater than between-pair correspondence. The null distribution is built by permuting pair labels on the precomputed N×N colocalization matrix.

“Pairs” can be subjects (structure vs. function per person), studies (one map per study in a meta-analytic context), neurochemical targets (tracers grouped by target), or any other unit for which matched maps exist in both modalities.

Reference: [35].

Parameters:

  • y (array-like, DataFrame, or list) – Modality A — N brain maps, one per pair. Same ordering as x is required; matching is done positionally.

  • x (array-like, DataFrame, or list) – Modality B — N brain maps in the same pair order as y. Unlike other workflow functions, x is expected to be individual-level data, not a reference dataset string — this is a usage contract (there is no x_collection parameter here and no dedicated runtime check forbidding a string), not an enforced validation.

  • z (array-like, DataFrame, or list, optional) – Covariate maps to partial out. Required for partial correlation methods ("partialspearman", "partialpearson"); ignored otherwise.

  • standardize (str, default="xz") – Which data to z-standardize (parcels). Can contain “x”, “y”, “z”.

  • space (str) – Image space for parcellation and data loading.

  • data_space (str or None) – Override for the data image space.

  • parcellation_space (str or None) – Override for the parcellation space.

  • parcellation (str or int, default=_PARC_DEFAULT) – Brain parcellation to use.

  • parcellation_labels (array-like or None) – Optional subset of parcellation region labels.

  • parcellation_hemi (list, default=["L", "R"]) – Hemispheres to include.

  • colocalization_method (str, default="spearman") – Colocalization method. Produces an N×N correlation matrix.

  • pooled_p (str, default="mean") – Aggregation used for the within-pair statistic: "mean" or "median" of the N diagonal entries. "auto" resolves to "mean". False is not supported and falls back to "mean".

  • plot (bool, default=True) – Whether to generate a plot after permutation, via nsp.plot(permute_what="pairs") (relies on NiSpace.plot()’s own kind="categorical" default — not passed explicitly here).

  • n_perm (int, default=10000) – Number of subject-label permutations for the null distribution.

  • seed (int or None) – Random seed for reproducibility.

  • n_proc (int, default=1) – Parallel workers (passed to NiSpace init; not used by the fast vectorised pair permutation itself).

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

  • nispace_object (NiSpace or None) – Pre-fitted NiSpace object to reuse; skips init/fit when provided.

  • init_kwargs (dict, optional) – Extra keyword arguments for NiSpace initialisation.

  • fit_kwargs (dict, optional) – Extra keyword arguments for NiSpace.fit().

  • colocalize_kwargs (dict, optional) – Extra keyword arguments for NiSpace.colocalize().

  • permute_kwargs (dict, optional) – Extra keyword arguments for NiSpace.permute().

  • plot_kwargs (dict, optional) – Extra keyword arguments for NiSpace.plot().

Returns:

nsp – Fitted NiSpace object. Use get_colocalizations() to retrieve the N×N pairwise matrix, get_p_values() for the within-pair vs. between-pair p-value (shape 1×1), and plot() to re-draw the visualization.

Return type:

NiSpace