X-Set Enrichment Analysis (XSEA; c.f. ABAnnotate)
So far, we’ve been computing colocalization values between a brain map and individual reference maps — one correlation per receptor or gene. But sometimes we don’t care about individual maps; we want to know whether the brain pattern of interest is broadly associated with a group of maps — say, all serotonin receptors, or all genes expressed in excitatory neurons.
This is the idea behind X-Set Enrichment Analysis (XSEA). The concept is closely related to Gene Set Enrichment Analysis (GSEA) in transcriptomics, adapted for brain maps.
The concept of XSEA used here was first implemented in the MATLAB toolbox ABAnnotate, a predecessor of NiSpace. If you’ve used ABAnnotate, you’ll find the concepts familiar.
The idea
Given a brain map and a set of reference maps (e.g., all receptor maps for serotonin), XSEA computes:
The mean colocalization between the brain map and all maps in the set.
A p-value asking: is this mean colocalization higher than expected when the brain map is replaced by a spatially-constrained random map?
The result is one statistic per set, not per individual map.
A note on null models
There are two natural null hypotheses for XSEA:
Permute the input map (default): generate surrogate maps of the brain map and recompute mean colocalizations. This tests whether the observed mean is higher than expected under spatial randomness.
Permute the sets: randomly sample sets from a larger background population of maps and ask whether the observed set mean is higher than random sets.
Ben Fulcher et al. (2021, Nature Communications) showed that random set sampling can inflate false positives when maps within a set are highly co-expressed (correlated). NiSpace therefore defaults to map permutation, following the approach of ABAnnotate. Pass permute_sets=True to switch to set permutation if needed. However, this is currently not recommended. In the future, we will implement within-set correlation-matched set resampling, which can address this issue.
[1]:
import tqdm.notebook
tqdm.notebook.tqdm = tqdm.tqdm
import numpy as np
import pandas as pd
[2]:
from nispace.datasets import fetch_reference, fetch_example
from nispace.io import load_img
from nispace.api import NiSpace
Dataset setup
We’ll run XSEA on the pain map against mRNA gene expression data, testing whether pain-related brain activation broadly aligns with the expression of particular cell types.
The mRNA reference dataset is derived from the Allen Human Brain Atlas (AHBA) and provides mean gene expression per brain region for thousands of genes, organized into sets such as cell type markers.
[3]:
# pain map (NeuroQuery meta-analytic z-map)
pain_map = load_img("neuroquery/pain.nii.gz")
# mRNA reference: cell type marker sets (Lake et al 2016)
# parcellation: Schaefer100+TianS1 (low resolution to match coarse ABA data sampling)
mrna = fetch_reference(
"mrna",
parcellation="Schaefer100TianS1",
collection="CellTypesPsychEncodeTPM",
print_references=False
)
print(f"mRNA data: {mrna.shape[0]} genes across {mrna.index.get_level_values('set').nunique()} sets x {mrna.shape[1]} parcels")
print(f"Set names: {list(mrna.index.get_level_values('set').unique())}")
mrna.head(3)
INFO | 01/06/26 15:06:43 | nispace.datasets: Loading mrna maps.
INFO | 01/06/26 15:06:43 | nispace.datasets: Loading integrated collection 'CellTypesPsychEncodeTPM' for dataset 'mrna'.
INFO | 01/06/26 15:06:43 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:43 | nispace.datasets: Loading and inner-merging data parcellated with 'Schaefer100Parcels7Networks' and 'TianS1'
mRNA data: 465 genes across 24 sets x 116 parcels
Set names: ['Ex1 CortProject (L2/3)', 'Ex2 Granule (L3/4)', 'Ex3 Granule (L4)', 'Ex4 SubcortProject (L4)', 'Ex5 SubcortProject (L4-6)', 'Ex6 SubcortProject (L5-6)', 'Ex7 Corticothalamic', 'Ex8 Corticothalamic (L6)', 'In1 VIP+RELN+NDNF+ (L1/2)', 'In2 VIP+RELN-NDNF- (L6)', 'In3 VIP+RELN+NDNF- (L6)', 'In4 VIP-RELN+NDNF+ (L1-3)', 'In5 CCK+NOS1+CALB2+ (L2/3)', 'In6 PVALB+CRHBP+ (L4/5)', 'In7 SST+CALB1+NPY+ (L5/6)', 'In8 SST+NOS1+ (L6)', 'Astrocyte', 'Endothelial', 'Developing-quiescent', 'Developing-replicating', 'Microglia', 'Other Neurons', 'OPC', 'Oligodendrocyte']
[3]:
| hemi-L_div-Vis_lab-1 | hemi-L_div-Vis_lab-2 | hemi-L_div-Vis_lab-3 | hemi-L_div-Vis_lab-4 | hemi-L_div-Vis_lab-5 | hemi-L_div-Vis_lab-6 | hemi-L_div-Vis_lab-7 | hemi-L_div-Vis_lab-8 | hemi-L_div-Vis_lab-9 | hemi-L_div-SomMot_lab-1 | ... | hemi-L_lab-PUT | hemi-L_lab-CAU | hemi-R_lab-HIP | hemi-R_lab-AMY | hemi-R_lab-pTHA | hemi-R_lab-aTHA | hemi-R_lab-NAc | hemi-R_lab-GP | hemi-R_lab-PUT | hemi-R_lab-CAU | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| set | map | |||||||||||||||||||||
| Ex1 CortProject (L2/3) | CAMK2A | 0.842136 | 0.826765 | 0.826967 | 0.827184 | 0.817241 | 0.822723 | 0.815382 | 0.818394 | 0.815004 | 0.819051 | ... | 0.452723 | 0.571612 | 0.792884 | 0.710187 | 0.414296 | 0.366631 | 0.485376 | 0.288345 | 0.537562 | 0.596598 |
| CCDC88C | 0.490978 | 0.415965 | 0.401705 | 0.323039 | 0.311288 | 0.341007 | 0.394077 | 0.361664 | 0.407064 | 0.432452 | ... | 0.784354 | 0.905244 | 0.417680 | 0.772467 | 0.433421 | 0.556930 | 0.916510 | 0.728213 | 0.748571 | 0.981271 | |
| CDH9 | 0.742186 | 0.618615 | 0.623595 | 0.567650 | 0.546706 | 0.577347 | 0.681953 | 0.648653 | 0.656170 | 0.708508 | ... | 0.483765 | 0.509307 | 0.638481 | 0.786927 | 0.225884 | 0.266731 | 0.684596 | 0.402965 | 0.512751 | 0.539964 |
3 rows × 116 columns
Notice the two-level MultiIndex: the first level is the cell type group (“set”), the second is the individual gene. The set structure is what XSEA operates on.
Running XSEA step by step
XSEA is triggered by passing xsea=True (or a specific aggregation method) to colocalize(). This computes colocalization with each individual map first, then averages within sets.
[4]:
nsp = NiSpace(
x=mrna,
y=pain_map,
y_labels="Pain",
parcellation="Schaefer100TianS1",
seed=42,
n_proc=4
)
nsp.fit()
# colocalize with XSEA aggregation
# xsea=True computes the mean colocalization within each set
nsp.colocalize("spearman", xsea=True)
# the result has one column per set (not per individual gene)
colocs = nsp.get_colocalizations()
print(f"XSEA colocalizations: {colocs.shape[1]} sets")
print(colocs.T.sort_values(by="Pain", ascending=False))
INFO | 01/06/26 15:06:43 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 01/06/26 15:06:43 | nispace.core.parcellation: Building combined Parcellation 'Schaefer100Parcels7Networks+TianS1' from library.
INFO | 01/06/26 15:06:43 | nispace.core.parcellation: Common MNI space(s) for combined: ['MNI152NLin2009cAsym', 'MNI152NLin6Asym'].
INFO | 01/06/26 15:06:43 | nispace.core.parcellation: Merging 'Schaefer100Parcels7Networks' and 'TianS1' for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:06:43 | nispace.core.parcellation: Merging 'Schaefer100Parcels7Networks' and 'TianS1' for space 'MNI152NLin6Asym'.
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer100Parcels7Networks' in 'fsaverage' (for spin tests).
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer100Parcels7Networks' in 'fsLR' (for spin tests).
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Combined parcellation 'Schaefer100Parcels7NetworksTianS1' ready. MNI space(s): ['MNI152NLin2009cAsym', 'MNI152NLin6Asym']. Cx surface space(s) for spins: ['fsaverage', 'fsLR'].
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Parcellation 'Schaefer100Parcels7NetworksTianS1': validation passed.
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Parcellation 'Schaefer100Parcels7NetworksTianS1': active space set to 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:06:44 | nispace.core.parcellation: Combined parcellation: cx-LH parcels = 58, cx-RH parcels = 58.
INFO | 01/06/26 15:06:44 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 01/06/26 15:06:44 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:06:44 | nispace.api: Got 'x' data for 465 x 116 parcels.
INFO | 01/06/26 15:06:44 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 01/06/26 15:06:44 | nispace.io: Input type: list, assuming imaging data.
INFO | 01/06/26 15:06:44 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:06:44 | nispace.io: Parcellating imaging data.
Parcellating (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 118.66it/s]
INFO | 01/06/26 15:06:48 | nispace.api: Got 'y' data for 1 x 116 parcels.
INFO | 01/06/26 15:06:48 | nispace.api: Z-standardizing 'X' data.
INFO | 01/06/26 15:06:48 | nispace.api: *** NiSpace.colocalize() - Estimating X & Y colocalizations. ***
INFO | 01/06/26 15:06:48 | nispace.api: Running 'spearman' colocalization.
INFO | 01/06/26 15:06:48 | nispace.api: Will perform X-set enrichment analysis (XSEA).
INFO | 01/06/26 15:06:48 | nispace.api: Using 24 sets with between 2 and 68 samples. Aggregating within-set colocalizations with: mean.
INFO | 01/06/26 15:06:48 | nispace.api: Pre-ranking X and Y data.
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2053.01it/s]
INFO | 01/06/26 15:06:50 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
XSEA colocalizations: 24 sets
Pain
Microglia 0.250146
Astrocyte 0.175766
OPC 0.168996
In1 VIP+RELN+NDNF+ (L1/2) 0.142336
Endothelial 0.141804
Ex6 SubcortProject (L5-6) 0.131066
Ex8 Corticothalamic (L6) 0.127390
Oligodendrocyte 0.118138
Developing-replicating 0.105683
Ex7 Corticothalamic 0.087049
Developing-quiescent 0.059943
In2 VIP+RELN-NDNF- (L6) 0.042509
Other Neurons 0.017340
Ex1 CortProject (L2/3) 0.017241
In3 VIP+RELN+NDNF- (L6) 0.011462
In8 SST+NOS1+ (L6) -0.009339
Ex5 SubcortProject (L4-6) -0.018907
In6 PVALB+CRHBP+ (L4/5) -0.019250
Ex2 Granule (L3/4) -0.024170
In7 SST+CALB1+NPY+ (L5/6) -0.024495
In5 CCK+NOS1+CALB2+ (L2/3) -0.031559
Ex4 SubcortProject (L4) -0.033283
In4 VIP-RELN+NDNF+ (L1-3) -0.036649
Ex3 Granule (L4) -0.215634
Permutation testing for XSEA
Permutation testing works the same way as for individual maps: we call permute("maps"), but now the null maps are used to compute null set-level colocalizations (after within-set averaging). The resulting p-value answers: is the observed set mean higher than expected under spatial randomness?
[5]:
# permute the input map (default for XSEA)
nsp.permute(
"maps",
maps_which="Y", # that's the input map
n_perm=1000,
p_tails="two" # two-tailed: no directional hypothesis for cell types
)
# correct p values
nsp.correct_p()
# get results
p_values = nsp.get_p_values()
pc_values = nsp.get_corrected_p_values()
# show results sorted by p-value
xsea_results = pd.DataFrame({
"mean_rho": colocs.T["Pain"],
"p": p_values.T["Pain"],
"p_corrected": pc_values.T["Pain"]
}).sort_values("p")
xsea_results
INFO | 01/06/26 15:06:50 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 01/06/26 15:06:50 | nispace.api: Permutation of: Y maps.
INFO | 01/06/26 15:06:50 | nispace.api: Using default null method 'moran' (parcellation null space: 'MNI152NLin2009cAsym').
INFO | 01/06/26 15:06:50 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 01/06/26 15:06:50 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:06:50 | nispace.api: Generating permuted Y maps.
INFO | 01/06/26 15:06:50 | nispace.nulls: Resampling volumetric parcellation from 1mm to 2mm for distance matrix generation.
INFO | 01/06/26 15:06:51 | nispace.nulls: Estimating euclidean distance matrix: 116 volumetric parcels, voxel-to-voxel mode, 4 proc.
Distance matrix (4 proc): 45%|█████████████████████████████████████████████████████▎ | 52/116 [00:04<00:06, 10.45it/s]/Applications/miniforge3/envs/nsp309/lib/python3.9/site-packages/joblib/externals/loky/process_executor.py:752: UserWarning: A worker stopped while some jobs were given to the executor. This can be caused by a too short worker timeout or by a memory leak.
warnings.warn(
Distance matrix (4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 116/116 [00:08<00:00, 14.33it/s]
INFO | 01/06/26 15:06:59 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:06:59 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 01/06/26 15:06:59 | nispace.nulls: Null map generation: Assuming n = 1 data vector(s) for n = 116 parcels.
INFO | 01/06/26 15:06:59 | nispace.nulls: Using provided distance matrix/matrices.
Moran null maps (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1579.78it/s]
INFO | 01/06/26 15:07:01 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:07:01 | nispace.api: Running X Set Enrichment Analysis (XSEA) without set permutation.
INFO | 01/06/26 15:07:01 | nispace.api: Pre-ranking X and Y (null) data.
Processing null arrays (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:03<00:00, 256.19it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 1295.59it/s]
INFO | 01/06/26 15:07:08 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:07:08 | nispace.api: *** NiSpace.correct_p() - Correct p values for multiple comparisons. ***
INFO | 01/06/26 15:07:08 | nispace.api: Correction method: 'meff_galwey', alpha: 0.05, dimension: 'array'.
INFO | 01/06/26 15:07:08 | nispace.api: Returning X dataframe:
| X_REDUCTION |
| False |
INFO | 01/06/26 15:07:08 | nispace.api: Meff_X (galwey) = 10.55 (from 24 maps).
INFO | 01/06/26 15:07:08 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:08 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
[5]:
| mean_rho | p | p_corrected | |
|---|---|---|---|
| Ex7 Corticothalamic | 0.087049 | 0.001 | 0.010495 |
| Ex8 Corticothalamic (L6) | 0.127390 | 0.001 | 0.010495 |
| OPC | 0.168996 | 0.002 | 0.020890 |
| Microglia | 0.250146 | 0.002 | 0.020890 |
| Developing-replicating | 0.105683 | 0.014 | 0.138153 |
| Ex6 SubcortProject (L5-6) | 0.131066 | 0.060 | 0.479255 |
| Ex3 Granule (L4) | -0.215634 | 0.068 | 0.524137 |
| Oligodendrocyte | 0.118138 | 0.112 | 0.714241 |
| Endothelial | 0.141804 | 0.162 | 0.844909 |
| Developing-quiescent | 0.059943 | 0.170 | 0.859830 |
| In2 VIP+RELN-NDNF- (L6) | 0.042509 | 0.194 | 0.897133 |
| In1 VIP+RELN+NDNF+ (L1/2) | 0.142336 | 0.202 | 0.907404 |
| Astrocyte | 0.175766 | 0.242 | 0.946164 |
| In7 SST+CALB1+NPY+ (L5/6) | -0.024495 | 0.458 | 0.998433 |
| Ex2 Granule (L3/4) | -0.024170 | 0.672 | 0.999992 |
| Other Neurons | 0.017340 | 0.684 | 0.999995 |
| In3 VIP+RELN+NDNF- (L6) | 0.011462 | 0.688 | 0.999995 |
| In5 CCK+NOS1+CALB2+ (L2/3) | -0.031559 | 0.750 | 1.000000 |
| In4 VIP-RELN+NDNF+ (L1-3) | -0.036649 | 0.808 | 1.000000 |
| Ex4 SubcortProject (L4) | -0.033283 | 0.830 | 1.000000 |
| Ex1 CortProject (L2/3) | 0.017241 | 0.844 | 1.000000 |
| In8 SST+NOS1+ (L6) | -0.009339 | 0.878 | 1.000000 |
| In6 PVALB+CRHBP+ (L4/5) | -0.019250 | 0.882 | 1.000000 |
| Ex5 SubcortProject (L4-6) | -0.018907 | 0.916 | 1.000000 |
[6]:
nsp.plot(sort_by="coloc")
INFO | 01/06/26 15:07:08 | nispace.api: *** NiSpace.plot() - Plot colocalization results. ***
INFO | 01/06/26 15:07:08 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:08 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:08 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:08 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
INFO | 01/06/26 15:07:08 | nispace.api: Creating categorical plot for method spearman, colocalization stat rho.
INFO | 01/06/26 15:07:08 | nispace.plotting: Significance annotation: 5/24 p_uncorrected < 0.05, 4/24 p_meffgalwey < 0.05
[6]:
(<Figure size 500x630 with 1 Axes>,
<Axes: title={'center': "$Spearman's\\ Rho$ colocalization\n(permutation of $X\\ maps$)"}, xlabel='$Rho$'>,
<seaborn._core.plot.Plotter at 0x3154a61f0>)
XSEA with PET receptor sets
XSEA isn’t limited to gene expression — you can use any reference dataset with a set structure. The PET dataset, for example, has neurotransmitter systems as sets. Running XSEA on it asks: does the pain map align more with the overall serotonin system than with the overall dopamine system, beyond what spatial autocorrelation can explain?
[7]:
# For XSEA with PET, we need a collection with the set structure (neurotransmitter
# systems as sets). UniqueTracers is a JSON-format collection that gives a two-level
# ['set', 'map'] MultiIndex — exactly what XSEA needs to aggregate by system.
pet_unique = fetch_reference(
"pet", parcellation="Schaefer200TianS1", collection="UniqueTracers", print_references=False,
set_size_range=(3, None) # when fetching set-based collections, some more parameters can be adjusted
)
nsp_pet = NiSpace(
x=pet_unique,
y=pain_map,
y_labels="Pain",
parcellation="Schaefer200TianS1",
seed=42,
n_proc=4
)
nsp_pet.fit()
nsp_pet.colocalize("spearman", xsea=True)
nsp_pet.permute("maps", maps_which="Y", n_perm=1000, p_tails="upper")
nsp_pet.correct_p()
nsp_pet.plot()
INFO | 01/06/26 15:07:09 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:07:09 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:07:09 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:07:09 | nispace.datasets: Filtered to 5 collection sets with between 3 and inf maps.
INFO | 01/06/26 15:07:09 | nispace.datasets: Loading and inner-merging data parcellated with 'Schaefer200Parcels7Networks' and 'TianS1'
INFO | 01/06/26 15:07:09 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Building combined Parcellation 'Schaefer200Parcels7Networks+TianS1' from library.
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Common MNI space(s) for combined: ['MNI152NLin2009cAsym', 'MNI152NLin6Asym'].
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Merging 'Schaefer200Parcels7Networks' and 'TianS1' for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Merging 'Schaefer200Parcels7Networks' and 'TianS1' for space 'MNI152NLin6Asym'.
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer200Parcels7Networks' in 'fsaverage' (for spin tests).
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer200Parcels7Networks' in 'fsLR' (for spin tests).
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Combined parcellation 'Schaefer200Parcels7NetworksTianS1' ready. MNI space(s): ['MNI152NLin2009cAsym', 'MNI152NLin6Asym']. Cx surface space(s) for spins: ['fsaverage', 'fsLR'].
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7NetworksTianS1': validation passed.
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7NetworksTianS1': active space set to 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:07:09 | nispace.core.parcellation: Combined parcellation: cx-LH parcels = 108, cx-RH parcels = 108.
INFO | 01/06/26 15:07:09 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 01/06/26 15:07:09 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:07:09 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:07:09 | nispace.api: Got 'x' data for 22 x 216 parcels.
INFO | 01/06/26 15:07:09 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 01/06/26 15:07:09 | nispace.io: Input type: list, assuming imaging data.
INFO | 01/06/26 15:07:09 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:07:09 | nispace.io: Parcellating imaging data.
Parcellating (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1784.81it/s]
/Applications/miniforge3/envs/nsp309/lib/python3.9/site-packages/neuromaps/transforms.py:254: FutureWarning: 'force_resample' will be set to 'True' by default in Nilearn 0.13.0.
Use 'force_resample=True' to suppress this warning.
out = nimage.resample_to_img(load_nifti(img), load_nifti(target),
/Applications/miniforge3/envs/nsp309/lib/python3.9/site-packages/neuromaps/transforms.py:254: FutureWarning: From release 0.13.0 onwards, this function will, by default, copy the header of the input image to the output. Currently, the header is reset to the default Nifti1Header. To suppress this warning and use the new behavior, set `copy_header=True`.
out = nimage.resample_to_img(load_nifti(img), load_nifti(target),
INFO | 01/06/26 15:07:10 | nispace.api: Got 'y' data for 1 x 216 parcels.
INFO | 01/06/26 15:07:10 | nispace.api: Z-standardizing 'X' data.
INFO | 01/06/26 15:07:10 | nispace.api: *** NiSpace.colocalize() - Estimating X & Y colocalizations. ***
INFO | 01/06/26 15:07:10 | nispace.api: Running 'spearman' colocalization.
INFO | 01/06/26 15:07:10 | nispace.api: Will perform X-set enrichment analysis (XSEA).
INFO | 01/06/26 15:07:10 | nispace.api: Using 5 sets with between 3 and 6 samples. Aggregating within-set colocalizations with: mean.
INFO | 01/06/26 15:07:10 | nispace.api: Pre-ranking X and Y data.
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1805.55it/s]
INFO | 01/06/26 15:07:10 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 01/06/26 15:07:10 | nispace.api: Permutation of: Y maps.
INFO | 01/06/26 15:07:10 | nispace.api: Using default null method 'moran' (parcellation null space: 'MNI152NLin2009cAsym').
INFO | 01/06/26 15:07:10 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 01/06/26 15:07:10 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:10 | nispace.api: Generating permuted Y maps.
INFO | 01/06/26 15:07:10 | nispace.nulls: Resampling volumetric parcellation from 1mm to 2mm for distance matrix generation.
INFO | 01/06/26 15:07:11 | nispace.nulls: Estimating euclidean distance matrix: 216 volumetric parcels, voxel-to-voxel mode, 4 proc.
Distance matrix (4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 216/216 [00:07<00:00, 30.40it/s]
INFO | 01/06/26 15:07:18 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:07:18 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 01/06/26 15:07:18 | nispace.nulls: Null map generation: Assuming n = 1 data vector(s) for n = 216 parcels.
INFO | 01/06/26 15:07:18 | nispace.nulls: Using provided distance matrix/matrices.
Moran null maps (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2193.67it/s]
INFO | 01/06/26 15:07:18 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:07:18 | nispace.api: Running X Set Enrichment Analysis (XSEA) without set permutation.
INFO | 01/06/26 15:07:18 | nispace.api: Pre-ranking X and Y (null) data.
Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 8452.87it/s]
Null colocalizations (spearman, 4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 10490.85it/s]
INFO | 01/06/26 15:07:19 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'upper'}).
INFO | 01/06/26 15:07:19 | nispace.api: *** NiSpace.correct_p() - Correct p values for multiple comparisons. ***
INFO | 01/06/26 15:07:19 | nispace.api: Correction method: 'meff_galwey', alpha: 0.05, dimension: 'array'.
INFO | 01/06/26 15:07:19 | nispace.api: Returning X dataframe:
| X_REDUCTION |
| False |
INFO | 01/06/26 15:07:19 | nispace.api: Meff_X (galwey) = 3.97 (from 5 maps).
INFO | 01/06/26 15:07:19 | nispace.api: *** NiSpace.plot() - Plot colocalization results. ***
INFO | 01/06/26 15:07:19 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:19 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:19 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:19 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
INFO | 01/06/26 15:07:19 | nispace.api: Creating categorical plot for method spearman, colocalization stat rho.
INFO | 01/06/26 15:07:19 | nispace.plotting: Significance annotation: 0/5 p_uncorrected < 0.05, 0/5 p_meffgalwey < 0.05
[7]:
(<Figure size 500x250 with 1 Axes>,
<Axes: title={'center': "$Spearman's\\ Rho$ colocalization\n(permutation of $X\\ maps$)"}, xlabel='$Rho$'>,
<seaborn._core.plot.Plotter at 0x328c775b0>)
The xsea_aggregation_method parameter
By default, XSEA aggregates individual map correlations by taking the mean. Alternatively, you can use "median" or "absmean"/"absmedian", or even "weightedmean". The latter only works when the input dataset does have a 3-level index with set, map, and weight as levels.
In practice, "mean" is the most common and interpretable choice, but "absmean" (absolute mean) can be reasonable based on the context.
[8]:
# absmean aggregation
nsp_pet.colocalize("spearman", xsea=True, xsea_aggregation_method="absmean")
nsp_pet.permute("maps", maps_which="Y", n_perm=1000, p_tails="upper") # one-tailed p value in this case
nsp_pet.plot()
INFO | 01/06/26 15:07:19 | nispace.api: *** NiSpace.colocalize() - Estimating X & Y colocalizations. ***
INFO | 01/06/26 15:07:19 | nispace.api: Running 'spearman' colocalization.
INFO | 01/06/26 15:07:19 | nispace.api: Will perform X-set enrichment analysis (XSEA).
INFO | 01/06/26 15:07:19 | nispace.api: Using 5 sets with between 3 and 6 samples. Aggregating within-set colocalizations with: absmean.
INFO | 01/06/26 15:07:19 | nispace.api: Pre-ranking X and Y data.
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2839.75it/s]
INFO | 01/06/26 15:07:19 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 01/06/26 15:07:19 | nispace.api: Permutation of: Y maps.
INFO | 01/06/26 15:07:19 | nispace.api: Using default null method 'moran' (parcellation null space: 'MNI152NLin2009cAsym').
INFO | 01/06/26 15:07:19 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 01/06/26 15:07:19 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:19 | nispace.api: Generating permuted Y maps.
INFO | 01/06/26 15:07:19 | nispace.core.permute: Found existing null maps.
INFO | 01/06/26 15:07:19 | nispace.api: Running X Set Enrichment Analysis (XSEA) without set permutation.
INFO | 01/06/26 15:07:19 | nispace.api: Pre-ranking X and Y (null) data.
Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 9039.47it/s]
Null colocalizations (spearman, 4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 10799.96it/s]
INFO | 01/06/26 15:07:20 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'upper'}).
INFO | 01/06/26 15:07:20 | nispace.api: *** NiSpace.plot() - Plot colocalization results. ***
INFO | 01/06/26 15:07:20 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:20 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:20 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:20 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
INFO | 01/06/26 15:07:20 | nispace.api: Creating categorical plot for method spearman, colocalization stat rho.
INFO | 01/06/26 15:07:20 | nispace.plotting: Significance annotation: 1/5 p_uncorrected < 0.05, 0/5 p_meffgalwey < 0.05
[8]:
(<Figure size 500x250 with 1 Axes>,
<Axes: title={'center': "$Spearman's\\ Rho$ colocalization\n(permutation of $X\\ maps$)"}, xlabel='$Rho$'>,
<seaborn._core.plot.Plotter at 0x328e220a0>)
XSEA via the workflow
For a one-liner version:
[9]:
from nispace.workflows import xsea
nsp_wf = xsea(
y={"Pain": pain_map},
x="mrna",
x_collection="CellTypesPsychEncodeTPM",
parcellation="Schaefer100TianS1",
colocalization_method="spearman",
n_perm=1000,
seed=42,
n_proc=4,
return_nispace_only=True
)
INFO | 01/06/26 15:07:20 | nispace.workflows: Loading integrated mrna dataset as X data.
INFO | 01/06/26 15:07:20 | nispace.datasets: Loading mrna maps.
INFO | 01/06/26 15:07:20 | nispace.datasets: Loading integrated collection 'CellTypesPsychEncodeTPM' for dataset 'mrna'.
INFO | 01/06/26 15:07:20 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:07:20 | nispace.datasets: Loading and inner-merging data parcellated with 'Schaefer100Parcels7Networks' and 'TianS1'
The NiSpace "mRNA" dataset is based on Allen Human Brain Atlas (AHBA) gene expression data published in Hawrylycz et al.,
2012 (https://doi.org/10.1038/nature11405). The dataset consists of mRNA expression data from postmortem brain tissue of
six donors, mapped onto MNI or fsaverage parcels using the abagen toolbox (Markello et al., 2021, https://doi.org/10.7554/eLife.72129).
The data was extracted using abagen.get_expression_data(..., lr_mirror="bidirectional", norm_matched=False), considering
parcel hemisphere and cortical vs. subcortical location. Gene stability was assessed independently of any specific
parcellation using a voxel-level atlas constructed from Schaefer100 (cortex) and TianS1 (subcortex) at 8mm isotropic
resolution (each voxel assigned a unique identifier; sample-to-voxel tolerance=8mm). Per-donor expression matrices were
obtained via abagen and genes were retained if their mean donor-to-donor Spearman rank correlation exceeded 0.2
(abagen.keep_stable_genes, rank=True, threshold=0.2). This stable gene set was applied uniformly across all parcellations.
In addition to the two publications listed above, please cite publications associated with gene set collections as appropriate.
To ensure reproducibility, note the NiSpace commit/version: 0.0.1b5.dev68+g20be93445.d20260520
- CellTypesPsychEncodeTPM Source: Lake2016 https://doi.org/10.1126/science.aaf1204
- CellTypesPsychEncodeTPM Source: Darmanis2015 https://doi.org/10.1073/pnas.1507125112
- CellTypesPsychEncodeTPM Source: Wang2018 https://doi.org/10.1126/science.aat8464
INFO | 01/06/26 15:07:20 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 01/06/26 15:07:20 | nispace.core.parcellation: Building combined Parcellation 'Schaefer100Parcels7Networks+TianS1' from library.
INFO | 01/06/26 15:07:20 | nispace.core.parcellation: Common MNI space(s) for combined: ['MNI152NLin2009cAsym', 'MNI152NLin6Asym'].
INFO | 01/06/26 15:07:20 | nispace.core.parcellation: Merging 'Schaefer100Parcels7Networks' and 'TianS1' for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:07:20 | nispace.core.parcellation: Merging 'Schaefer100Parcels7Networks' and 'TianS1' for space 'MNI152NLin6Asym'.
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer100Parcels7Networks' in 'fsaverage' (for spin tests).
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Fetching cx surface data for 'Schaefer100Parcels7Networks' in 'fsLR' (for spin tests).
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Combined parcellation 'Schaefer100Parcels7NetworksTianS1' ready. MNI space(s): ['MNI152NLin2009cAsym', 'MNI152NLin6Asym']. Cx surface space(s) for spins: ['fsaverage', 'fsLR'].
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Parcellation 'Schaefer100Parcels7NetworksTianS1': validation passed.
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Parcellation 'Schaefer100Parcels7NetworksTianS1': active space set to 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:07:21 | nispace.core.parcellation: Combined parcellation: cx-LH parcels = 58, cx-RH parcels = 58.
INFO | 01/06/26 15:07:21 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 01/06/26 15:07:21 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:07:21 | nispace.api: Got 'x' data for 465 x 116 parcels.
INFO | 01/06/26 15:07:21 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 01/06/26 15:07:21 | nispace.io: Input type: dict, assuming (img_name, img) pairs for imaging data.
INFO | 01/06/26 15:07:21 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:07:21 | nispace.io: Parcellating imaging data.
Parcellating (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2425.86it/s]
INFO | 01/06/26 15:07:22 | nispace.api: Got 'y' data for 1 x 116 parcels.
INFO | 01/06/26 15:07:22 | nispace.api: Z-standardizing 'X' data.
INFO | 01/06/26 15:07:22 | nispace.api: *** NiSpace.colocalize() - Estimating X & Y colocalizations. ***
INFO | 01/06/26 15:07:22 | nispace.api: Running 'spearman' colocalization.
INFO | 01/06/26 15:07:22 | nispace.api: Will perform X-set enrichment analysis (XSEA).
INFO | 01/06/26 15:07:22 | nispace.api: Using 24 sets with between 2 and 68 samples. Aggregating within-set colocalizations with: mean.
INFO | 01/06/26 15:07:22 | nispace.api: Pre-ranking X and Y data.
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2519.10it/s]
INFO | 01/06/26 15:07:22 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 01/06/26 15:07:22 | nispace.api: Permutation of: Y maps.
INFO | 01/06/26 15:07:22 | nispace.api: Using default null method 'moran' (parcellation null space: 'MNI152NLin2009cAsym').
INFO | 01/06/26 15:07:22 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 01/06/26 15:07:22 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:22 | nispace.api: Generating permuted Y maps.
INFO | 01/06/26 15:07:22 | nispace.nulls: Resampling volumetric parcellation from 1mm to 2mm for distance matrix generation.
INFO | 01/06/26 15:07:22 | nispace.nulls: Estimating euclidean distance matrix: 116 volumetric parcels, voxel-to-voxel mode, 4 proc.
Distance matrix (4 proc): 10%|████████████▎ | 12/116 [00:00<00:06, 15.92it/s]/Applications/miniforge3/envs/nsp309/lib/python3.9/site-packages/joblib/externals/loky/process_executor.py:752: UserWarning: A worker stopped while some jobs were given to the executor. This can be caused by a too short worker timeout or by a memory leak.
warnings.warn(
Distance matrix (4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 116/116 [00:08<00:00, 13.69it/s]
INFO | 01/06/26 15:07:31 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:07:31 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 01/06/26 15:07:31 | nispace.nulls: Null map generation: Assuming n = 1 data vector(s) for n = 116 parcels.
INFO | 01/06/26 15:07:31 | nispace.nulls: Using provided distance matrix/matrices.
Moran null maps (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1342.18it/s]
INFO | 01/06/26 15:07:33 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:07:33 | nispace.api: Running X Set Enrichment Analysis (XSEA) without set permutation.
INFO | 01/06/26 15:07:33 | nispace.api: Pre-ranking X and Y (null) data.
Processing null arrays (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:01<00:00, 775.37it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 1530.12it/s]
INFO | 01/06/26 15:07:37 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:07:37 | nispace.api: *** NiSpace.correct_p() - Correct p values for multiple comparisons. ***
INFO | 01/06/26 15:07:37 | nispace.api: Correction method: 'meff_galwey', alpha: 0.05, dimension: 'array'.
INFO | 01/06/26 15:07:37 | nispace.api: Returning X dataframe:
| X_REDUCTION |
| False |
INFO | 01/06/26 15:07:37 | nispace.api: Meff_X (galwey) = 10.55 (from 24 maps).
INFO | 01/06/26 15:07:37 | nispace.api: *** NiSpace.normalize_colocalizations() - Normalize colocalizations against null distribution. ***
INFO | 01/06/26 15:07:37 | nispace.api: Z-score method: robust (median/MAD).
INFO | 01/06/26 15:07:37 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Stored normalized colocalizations: xdimred-false_ytrans-false_coloc-spearman_stat-rho_xsea-true_perm-ymaps
INFO | 01/06/26 15:07:37 | nispace.api: *** NiSpace.plot() - Plot colocalization results. ***
INFO | 01/06/26 15:07:37 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Creating categorical plot for method spearman, colocalization stat rho.
INFO | 01/06/26 15:07:37 | nispace.api: Returning z-scored colocalizations.
INFO | 01/06/26 15:07:37 | nispace.plotting: Significance annotation: 5/24 p_uncorrected < 0.05, 4/24 p_meffgalwey < 0.05
INFO | 01/06/26 15:07:37 | nispace.api: Returning colocalizations:
| METHOD | XSEA | X_REDUCTION | Y_TRANSFORM |
| spearman | True | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | None | False | False |
INFO | 01/06/26 15:07:37 | nispace.api: Returning p values:
| METHOD | PERMUTE_WHAT | XSEA | MC_METHOD | X_REDUCTION | Y_TRANSFORM |
| spearman | ymaps | True | meffgalwey | False | False |
Summary
XSEA aggregates individual map colocalizations within predefined sets and tests the set-level mean.
Enable it by passing
xsea="mean"(or"median") tocolocalize().Permutation testing works the same as for individual maps:
permute("maps").The default null model (map permutation) avoids inflation from within-set co-expression, following Fulcher et al. (2021).
ABAnnotate (the predecessor toolbox) used the same approach — XSEA in NiSpace is the generalized, multi-dataset version.
For the workflow version:
xsea().
Next: Notebook 11 covers advanced topics: dimensionality reduction, multi-modal parcellations, alternative colocalization methods, and individual-level analyses.