nispace.workflows.group_xsea

nispace.workflows.group_xsea(y, design, x='mRNA', 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, xsea_aggregation_method='mean', pooled_p=False, 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 set enrichment analysis (XSEA) workflow.

Equivalent to group_colocalization() with X treated as sets (e.g. gene sets): Y is reduced to a single group-comparison effect-size map via NiSpace.transform_y(), then colocalized with X sets (aggregated via xsea_aggregation_method), with group-label permutation for p-values. All parameters not listed below behave exactly as in group_colocalization() (this function is a thin wrapper that injects xsea=True into colocalize_kwargs and forwards everything else unchanged).

Parameters:

  • y (array-like or pandas DataFrame or list) – Input Y data: one map per individual subject/observation.

  • design (list, array-like, or pandas DataFrame) – Group (and, if paired=True, subject) labels. See group_colocalization() for the full accepted forms and validation rules.

  • x (str or array-like, default="mRNA") – Input X data, expected to carry set membership (e.g. a “set”/gene-set MultiIndex level). Can be a string reference dataset name 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.

  • colocalization_method (str or list, default="spearman") – Method(s) to use for colocalization. Static default — no binary_y support here, same reasoning as group_colocalization().

  • comparison_method (str or None, default=None) – Formula passed to NiSpace.transform_y() to reduce Y to a single group-comparison effect-size map. Defaults to "hedges(a,b)" (unpaired) or "pairedcohen(a,b)" (paired).

  • mc_method (str or list, default="meff") – Multiple-comparisons correction method(s), forwarded to NiSpace.correct_p().

  • normalize_colocalizations (bool, default=True) – Whether to call NiSpace.normalize_colocalizations() after correction.

  • xsea_aggregation_method (str, default="mean") – How to aggregate individual X maps within each set before colocalization. One of "mean", "median", "absmean", "absmedian", "weightedmean", "weightedabsmean". This is the only parameter this function adds beyond group_colocalization()’s own signature, injected into colocalize_kwargs together with xsea=True.

  • pooled_p (str or bool, default=False) – Present for signature symmetry, but not a free choice: group-label permutation always forces pooled_p="mean", same as group_colocalization(). Unlike xsea(), this function does not inject anything into permute_kwargs — XSEA-ness is inherited automatically inside NiSpace.permute() from colocalize_kwargs["xsea"], since there is no maps/sets axis to choose for group-label permutation.

  • paired (bool, default=False) – Whether groups are paired/matched by subject.

  • plot_design_between (bool, default=True) – Whether to plot the between-subject design matrix (diagnostic only).

  • combat (bool, default=False) – Whether to apply ComBat harmonization.

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

  • transform_y_kwargs (dict, optional) – Additional arguments for NiSpace.transform_y().

  • colocalize_kwargs (dict, optional) – Additional arguments for colocalization. Pre-seeded with xsea=True/xsea_aggregation_method; explicit caller keys override.

  • permute_kwargs (dict, optional) – Additional arguments for permutation testing (unmodified by this function; what="groups" is forced by group_colocalization()).

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

Notes

There is no binary_y parameter here, consistent with group_colocalization(): NiSpace.transform_y() (always run internally) is incompatible with binary Y, and group-label permutation raises for binary_y=True.