nispace.workflows.xsea

nispace.workflows.xsea(y, x='mRNA', z=None, x_collection=None, x_background=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, xsea_aggregation_method='mean', permute_sets=False, 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]

Set enrichment analysis (XSEA) workflow for group-level map(s).

Equivalent to colocalization() with X treated as sets (e.g. gene sets) rather than individual maps: colocalizations are computed per set (aggregated via xsea_aggregation_method) and Y is permuted to build the null distribution, unless permute_sets=True (see below). All parameters not listed below behave exactly as in colocalization().

Parameters:

  • y (array-like or pandas DataFrame or list) – Input Y data to test for set enrichment. 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="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.

  • x_background (array-like or None, default=None) – Pool of “background” X maps used as the null when permute_sets=True (X-set-membership permutation). If None and x is a reference dataset string, an attempt is made to auto-fetch the full reference collection as the background (silently falls back to None with a warning on failure). Ignored if permute_sets=False.

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

  • mc_method (str or list, default="meff") – Multiple-comparisons correction method(s), forwarded to NiSpace.correct_p(). 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.

  • 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" (weighted variants require a "weight" MultiIndex level on X). See NiSpace.colocalize().

  • permute_sets (bool, default=False) – If True, switches the permutation null from what="maps" (permuting Y, the default) to what="sets" (X-set-membership permutation using x_background as the pool of maps to reassign to sets).

  • pooled_p (str or bool, default=False) – How to aggregate across Y maps before computing p-values. Same semantics as in colocalization() (fully relevant here).

  • 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. Forces NiSpace(binary_y=True) and drives the colocalization_method=None dynamic default toward "pearson". See colocalization() for the full behavior.

  • 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. Pre-seeded with xsea=True/xsea_aggregation_method; explicit caller keys override.

  • permute_kwargs (dict, optional) – Additional arguments for permutation testing. Pre-seeded with what, maps_which="Y", sets_X_background; explicit caller keys override.

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