nispace.workflows.group_colocalization

nispace.workflows.group_colocalization(y, design, 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'], colocalization_method='spearman', comparison_method=None, mc_method='meff', normalize_colocalizations=True, pooled_p=False, p_from_average_y=None, paired=False, plot_design_between=True, combat=False, plot=True, 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, transform_y_kwargs=None, colocalize_kwargs=None, permute_kwargs=None, correct_p_kwargs=None, plot_kwargs=None, return_nispace_only=False)[source]

Group-comparison colocalization workflow.

Compares Y maps between two groups of individual subjects/observations (e.g. patients vs. controls), reduces the comparison to a single effect-size map via NiSpace.transform_y(), and colocalizes that map with X while testing significance via group-label permutation.

Parameters:

  • y (array-like or pandas DataFrame or list) – Input Y data: one map per individual subject/observation (not group-level summary maps). Passed straight through to NiSpace.fit.

  • design (list, array-like, or pandas DataFrame) –

    Group (and, if paired=True, subject) labels, one row per row of y (row count must match len(y), else raises ValueError). Accepted forms:

    • 1-D list/array/Series: dummy-coded group labels. Raises ValueError if paired=True (a 1-D input cannot carry subject IDs).

    • 2-D ndarray: columns ["groups"(, "subjects"), V0, V1, ...] (subjects column only if paired=True).

    • DataFrame: must have a "groups" column (and a "subjects" column if paired=True).

    Any columns beyond the mandatory group(+subject) column(s) are treated as Y covariates and automatically regressed out via NiSpace.clean_y() (see clean_y_kwargs below).

  • 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().

  • colocalization_method (str or list, default="spearman") – Method(s) to use for colocalization. Unlike colocalization(), this is a static default (no binary_y-driven dynamic default) — this function does not support binary Y, since NiSpace.transform_y() (always run here) and group-label permutation are both incompatible with binary_y=True. See NiSpace.colocalize() for the full list of supported methods.

  • comparison_method (str or None, default=None) – Formula passed to NiSpace.transform_y() to reduce Y to a single group-comparison effect-size map. When None, defaults to "hedges(a,b)" if paired=False, otherwise "pairedcohen(a,b)". This transform is then reused as Y_transform for colocalization, permutation, plotting, and result retrieval.

  • 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. Failures are caught and logged as a warning rather than raised.

  • pooled_p (str or bool, default=False) – Present for signature symmetry with colocalization(), but not a free choice here: for group-label permutation (what="groups"), NiSpace.permute() always answers a group-level question and forces pooled_p="mean" regardless of what is passed (with a warning on conflict).

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

  • paired (bool, default=False) – Whether groups are paired/matched by subject (e.g. pre/post, or matched case-control pairs). Governs design parsing rules, the dynamic default of comparison_method, and is passed to NiSpace.permute() as groups_paired.

  • plot_design_between (bool, default=True) – Whether to plot the between-subject design matrix (diagnostic only). Only takes effect when design has covariate columns that trigger NiSpace.clean_y().

  • combat (bool, default=False) – Whether to apply ComBat harmonization. Only relevant when design has covariate columns that trigger NiSpace.clean_y().

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

  • 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. Auto-triggered based on design having covariate columns beyond "groups"``(+”subjects”) — unlike :func:`colocalization`, there is no separate ``y_covariates flag here.

  • transform_y_kwargs (dict, optional) – Additional arguments for NiSpace.transform_y(). Always runs (no conditional gate other than a pre-fitted nispace_object).

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

  • permute_kwargs (dict, optional) – Additional arguments for permutation testing. Note what="groups" is forced last in the internal merge and cannot be overridden here.

  • 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).