nispace.workflows.colocalization

nispace.workflows.colocalization(y, x='PET', z=None, x_collection=None, standardize='xz', space='MNI152NLin6Asym', data_space=None, parcellation_space=None, parcellation='Yan200', parcellation_labels=None, parcellation_hemi=['L', 'R'], y_covariates=None, colocalization_method=None, mc_method='meff', normalize_colocalizations=True, pooled_p=False, p_from_average_y=None, plot=True, combat=False, binary_y=False, n_perm=10000, seed=None, n_proc=1, verbose=True, nispace_object=None, fetch_x_kwargs=None, init_kwargs=None, fit_kwargs=None, clean_y_kwargs=None, colocalize_kwargs=None, permute_kwargs=None, correct_p_kwargs=None, plot_kwargs=None, return_nispace_only=False)[source]

Colocalization workflow.

Parameters:

  • y (array-like or pandas DataFrame or list) – Input Y data to colocalize with X. Can be a numpy array, pandas DataFrame, (list of) path(s) to a file(s) or list of image objects.

  • x (str or array-like, default="PET") – Input X data. Can be a string indicating a reference dataset (“PET”, “mRNA”, …), or input types as listed for y.

  • z (array-like or None, default=None) – Optional confound data to regress out. Can be “gm”, or input types as listed for y.

  • x_collection (str or None, default=None) – If x is a string reference dataset, specifies which collection to use.

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

  • space (str, default=_SPACE_DEFAULT_VOL ("MNI152NLin6Asym")) – Default template space for both the data images and the parcellation. Used to resolve data_space/parcellation_space when those are not given.

  • data_space (str or None, default=None) – Template space of the input data images. Falls back to space if falsy.

  • parcellation_space (str or None, default=None) – Template space of the parcellation. Falls back to space if falsy.

  • parcellation (str or int, default=_PARC_DEFAULT) – Brain parcellation to use. Can be a string name or integer ID.

  • parcellation_labels (array-like or None, default=None) – Optional labels for the parcellation regions.

  • parcellation_hemi (list of str, default=["L", "R"]) – Hemispheres to include. Forwarded to NiSpace initialization and, if x is a reference dataset string, to fetch_reference().

  • y_covariates (array-like or None, default=None) – Optional covariates to regress from Y data. If given, NiSpace.clean_y() is run with how="between" before colocalization.

  • colocalization_method (str or list, default=None) – Method(s) to use for colocalization. When None, defaults to "pearson" if binary_y=True, otherwise "spearman". See NiSpace.colocalize() for the full list of supported methods.

  • mc_method (str or list, default="meff") – Multiple-comparisons correction method(s), forwarded to NiSpace.correct_p(). If a list, each method is applied and stored separately. An explicit "mc_method" key inside correct_p_kwargs overrides this entirely.

  • normalize_colocalizations (bool, default=True) – Whether to call NiSpace.normalize_colocalizations() after correction (z-scores observed colocalizations against their null distribution). Failures are caught and logged as a warning rather than raised.

  • pooled_p (str or bool, default=False) – How to aggregate across Y maps before computing p-values. False (default) computes one p-value per Y×X pair. "mean" or "median" averages colocalizations across Y maps first and returns one p-value per X map. "auto" uses False for a single Y map and "mean" otherwise.

  • p_from_average_y (str or bool, optional) – Deprecated. Use pooled_p instead.

  • plot (bool, default=True) – Whether to generate visualization plots.

  • combat (bool, default=False) – Whether to apply ComBat harmonization. Only relevant if y_covariates is given.

  • binary_y (bool, default=False) – Set if Y is binary (e.g. binary lesion/cluster masks). Forces NiSpace(binary_y=True), which prevents Y from being z-scored regardless of standardize and drives the colocalization_method=None dynamic default toward "pearson". Not relevant to permutation here, since this function always permutes what="maps" (the binary_y restriction on permute(what="groups") only applies to group_colocalization()).

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

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

  • n_proc (int, default=1) – Number of processes for parallel computation.

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

  • nispace_object (NiSpace or None, default=None) – Optional pre-initialized NiSpace object to use.

  • fetch_x_kwargs (dict, optional) – Additional arguments for fetching X data.

  • init_kwargs (dict, optional) – Additional arguments for NiSpace initialization.

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

  • clean_y_kwargs (dict, optional) – Additional arguments for Y data cleaning.

  • colocalize_kwargs (dict, optional) – Additional arguments for colocalization.

  • permute_kwargs (dict, optional) – Additional arguments for permutation testing.

  • correct_p_kwargs (dict, optional) – Additional arguments for p-value correction.

  • plot_kwargs (dict, optional) – Additional arguments for plotting.

  • return_nispace_only (bool, default=False) – If True, return only the NiSpace object. Use nsp.get_colocalizations() and nsp.get_p_values() to access results. Setting False is deprecated and will be removed in the first non-dev release.

Returns:

  • nsp (NiSpace) – The NiSpace object containing all results (when return_nispace_only=True).

  • colocs, p_values, pc_values, nsp (tuple) – Deprecated. Returned when return_nispace_only=False (current default).