NiSpace workflows

The notebooks so far have built up the NiSpace pipeline step by step — fit(), transform_y(), clean_y(), colocalize(), permute(), plot(). That level of control is great when you need flexibility. But for standard analyses, NiSpace provides workflow functions that run the complete pipeline in a single call.

Three workflows are available:

Function	Question answered	Null model
`colocalization()`	Does this map/ Do these maps colocalize with reference maps?	Surrogate map permutation
`group_colocalization()`	Do brain alterations in this group colocalize with reference maps?	Group label permutation
`xsea()`	Does this map/ Do these maps colocalize with predefined sets of reference maps?	Surrogate map permutation
`group_xsea()`	Do brain alterations in this group colocalize with predefined sets of reference maps?	Group label permutation

All workflows return a fitted NiSpace object. Use the get_* methods to retrieve results:

nsp = colocalization(...)
colocs   = nsp.get_colocalizations()
p_values = nsp.get_p_values()
q_values = nsp.get_p_values(mc_method="meff")   # or any other mc_method

[1]:

import tqdm.notebook
tqdm.notebook.tqdm = tqdm.tqdm

import pandas as pd
import numpy as np

`colocalization()` — single map

The simplest workflow: you have one group-level brain map and want to test whether they colocalize with a set of reference maps.

[2]:

from nispace.workflows import colocalization
from nispace.io import load_img

pain_map = load_img("neuroquery/pain.nii.gz")

nsp = colocalization(
    y={"Pain": pain_map},  # dict key becomes the map label; can also be just the image
    x="pet",               # string shortcut: automatically fetches the PET reference dataset
    x_collection="UniqueTracers", # dataset collection to use for the PET reference dataset, optional
    parcellation="Schaefer200", # parcellation to use for the analysis
    colocalization_method="spearman", # colocalization method, default is "spearman"
    permute_kwargs={"p_tails": "upper"},  # directional test
    mc_method="meff", # multiple comparison correction method, default is "meff" (effective number of tests)
    n_perm=1000, # number of null runs, increase to >=10000 for final analyses
    seed=42, # random seed for reproducibility
    n_proc=4, # number of processes to use for parallelization, default is 1; set to -1 to use all available cores
    return_nispace_only=True # return only the NiSpace object, will be default in future versions
)

INFO | 01/06/26 15:06:10 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 01/06/26 15:06:10 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:06:10 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:06:10 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:10 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
The NiSpace "PET" dataset is based on openly available nuclear imaging maps largely accessed via neuromaps
(https://neuromaps-main.readthedocs.io/). If requested in the varying original spaces and resolutions (termed "MNI152",
"fsaverageOriginal", or "fsLROriginal"), the maps are downloaded directly from the source and cached locally. If, as is highly
recommended, the maps are requested in a defined space ("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR"),
they are downloaded from the NiSpace-data GitHub repo (find them in `~HOME/nispace-data/reference/pet/map`).
The NiSpace-hosted MNI maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to 2mm MNI152NLin2009cAsym
with a pre-estimated MNI-to-MNI transformation using SynthMorph v4 (https://martinos.org/malte/synthmorph/). The resulting maps
were masked with a liberal grey matter mask generated from the Harvard-Oxford atlas and scaled from 1e-6 to 1. The scaling was
transferred from MNI to surface maps if both were available for the same source (e.g., maps from Beliveau et al.).
The accompanying metadata table contains detailed information about tracers, source samples, original publications and data
sources, as well as the publication licenses. Every map should be cited when used. The responsibility for this lies with the user!
We additionally ask to cite:
- Markello et al., 2022 (https://doi.org/10.1038/s41592-022-01625-w)
- Hansen et al., 2022 (https://doi.org/10.1038/s41593-022-01186-3)
- Dukart et al., 2021 (https://doi.org/10.1002/hbm.25244)
- Hoffmann et al., 2024 (https://doi.org/10.1162/imag_a_00197; if NiSpace-processed maps are used)
To ensure reproducibility, note the NiSpace commit/version: 0.0.1b5.dev68+g20be93445.d20260520

- target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012         Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT1b_tracer-p943_n-23_dx-hc_pub-savli2012              Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT2a_tracer-altanserin_n-19_dx-hc_pub-savli2012        Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT4_tracer-sb207145_n-59_dx-hc_pub-beliveau2017        Source: Beliveau2017       CC BY-NC-SA 4.0  https://doi.org/10.1523/JNEUROSCI.2830-16.2016
    CAVE: Processed in fsaverage space, use  volumetric maps only for subcortex!
- target-5HT6_tracer-gsk215083_n-30_dx-hc_pub-radhakrishnan2018  Source: Radhakrishnan2018  CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.117.206516, https://doi.org/10.1016/j.pscychresns.2019.111007
- target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012               Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-A4B2_tracer-flubatine_n-30_dx-hc_pub-hillmer2016        Source: Hillmer2016        CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2016.07.026, https://doi.org/10.1093/ntr/ntx091
- target-CB1_tracer-omar_n-77_dx-hc_pub-normandin2015            Source: Normandin2015      CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2015.46, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1016/j.biopsych.2015.08.021, https://doi.org/10.1111/j.1530-0277.2012.01815.x
- target-CMRglu_tracer-fdg_n-20_dx-hc_pub-castrillon2023         Source: Castrillon2023     CC BY-NC-SA 4.0  https://doi.org/10.1126/sciadv.adi7632
- target-COX1_tracer-ps13_n-11_dx-hc_pub-kim2020                 Source: Kim2020            CC0 1.0          https://doi.org/10.1007/s00259-020-04855-2, https://doi.org/10.18112/openneuro.ds004401.v1.0.1
- target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017            Source: Kaller2017         CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-017-3645-0
- target-D23_tracer-flb457_n-55_dx-hc_pub-sandiego2015           Source: Sandiego2015       CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2014.237, https://doi.org/10.1177/0271678X17737693, https://doi.org/10.1038/s41386-019-0456-y, https://doi.org/10.1001/jamapsychiatry.2014.2414, https://doi.org/10.1038/npp.2017.223
- target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018             Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
    CAVE: SPECT, not PET!
- target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018  Source: Garciagomez2018    free             https://doi.org/10.33588/imagendiagnostica.901.2
- target-GABAa_tracer-flumazenil_n-6_dx-hc_pub-dukart2018        Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
- target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022         Source: Lukow2022          CC BY 4.0        https://doi.org/10.1038/s42003-022-03268-1
- target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017          Source: Gallezot2017       CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X16650697, https://doi.org/10.1038/jcbfm.2009.195
- target-HDAC_tracer-martinostat_n-8_dx-hc_pub-wey2016           Source: Wey2016            CC0 1.0          https://doi.org/10.1126/scitranslmed.aaf7551
- target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018           Source: Vijay2018          CC BY-NC-SA 4.0  https://doi.org/10.1038/s41386-018-0199-1
- target-M1_tracer-lsn3172176_n-24_dx-hc_pub-naganawa2020        Source: Naganawa2020       CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.120.246967
- target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019           Source: Smart2019          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-018-4252-4
- target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020     Source: Kantonen2020       CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017                 Source: Hesse2017          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-016-3590-3
- target-NMDA_tracer-ge179_n-29_dx-hc_pub-galovic2021            Source: Galovic2021        CC BY-NC-SA 4.0  https://doi.org/10.1001/jamaneurol.2022.4352, https://doi.org/10.1016/j.neuroimage.2021.118194, https://doi.org/10.2967/jnumed.113.130641
    CAVE: Unlike other tracers, [18F]GE-179 binds to open (active) NMDA receptors!
- target-rCPS_tracer-leucine_n-42_dx-hc_pub-smith2023            Source: Smith2023          CC0 1.0          https://doi.org/10.18112/openneuro.ds004654.v1.0.1, https://doi.org/10.18112/openneuro.ds004730.v1.0.0, https://doi.org/10.18112/openneuro.ds004731.v1.0.0, https://doi.org/10.18112/openneuro.ds004733.v1.0.0, https://doi.org/10.1016/j.nbd.2020.104978, https://doi.org/10.1177/0271678X221090997, https://doi.org/10.1038/jcbfm.2009.7, https://doi.org/10.1093/sleep/zsy088, https://doi.org/10.1177/0271678X221121873
- target-SV2A_tracer-ucbj_n-76_dx-hc_pub-finnema2016             Source: Finnema2016        CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X17724947, https://doi.org/10.2967/jnumed.120.246967, https://doi.org/10.1177/0271678X211004312, https://doi.org/10.1186/s13195-020-00742-y, https://doi.org/10.1177/0271678X20946198, https://doi.org/10.1093/cid/ciab484, https://doi.org/10.1038/s41380-021-01184-0, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1111/epi.16653, https://doi.org/10.1186/s13550-020-00670-w, https://doi.org/10.1002/alz.12097, https://doi.org/10.1111/epi.14701, https://doi.org/10.1038/s41467-019-09562-7, https://doi.org/10.1001/jamaneurol.2018.1836
- target-TSPO_tracer-pbr28_n-6_dx-hc_pub-lois2018                Source: Lois2018           MIT              https://doi.org/10.1021/acschemneuro.8b00072, https://doi.org/10.5281/zenodo.1174364
- target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017         Source: Aghourian2017      CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020             Source: Larsen2020         CC0 1.0          https://doi.org/10.18112/openneuro.ds002385.v1.1.0, https://doi.org/10.1038/s41467-020-14693-3

INFO | 01/06/26 15:06:10 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 01/06/26 15:06:10 | nispace.core.parcellation: Building multi-space Parcellation for 'Schaefer200Parcels7Networks' from library.
INFO | 01/06/26 15:06:10 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:10 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': validation passed.
INFO | 01/06/26 15:06:10 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:06:11 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': active space set to 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:06:11 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 01/06/26 15:06:11 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:11 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:06:11 | nispace.api: Got 'x' data for 29 x 200 parcels.
INFO | 01/06/26 15:06:11 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 01/06/26 15:06:11 | nispace.io: Input type: dict, assuming (img_name, img) pairs for imaging data.
INFO | 01/06/26 15:06:11 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:06:11 | nispace.io: Parcellating imaging data.

Parcellating (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 135.76it/s]

INFO | 01/06/26 15:06:15 | nispace.api: Got 'y' data for 1 x 200 parcels.
INFO | 01/06/26 15:06:15 | nispace.api: Z-standardizing 'X' data.
INFO | 01/06/26 15:06:15 | nispace.api: *** NiSpace.colocalize() - Estimating X & Y colocalizations. ***
INFO | 01/06/26 15:06:15 | nispace.api: Running 'spearman' colocalization.
INFO | 01/06/26 15:06:15 | nispace.api: Pre-ranking X and Y data.

Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 2775.85it/s]

INFO | 01/06/26 15:06:17 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 01/06/26 15:06:17 | nispace.api: Permutation of: X maps.
INFO | 01/06/26 15:06:17 | nispace.api: Using default null method 'alexander_bloch' (parcellation null space: 'fsLR').
INFO | 01/06/26 15:06:17 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 01/06/26 15:06:17 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 01/06/26 15:06:17 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:06:17 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'alexander_bloch').
INFO | 01/06/26 15:06:17 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsaverage'.
INFO | 01/06/26 15:06:17 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 200 parcels.
INFO | 01/06/26 15:06:17 | nispace.nulls: Using provided precomputed spin matrix.

Spin null maps: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 224.45it/s]

INFO | 01/06/26 15:06:17 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:06:17 | nispace.core.permute: Z-standardizing null maps.


Processing null arrays (4 proc): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:01<00:00, 969.10it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 7817.19it/s]

INFO | 01/06/26 15:06:21 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'upper'}).
INFO | 01/06/26 15:06:21 | nispace.plotting: Significance annotation: 2/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_3_9.png

[3]:

colocs   = nsp.get_colocalizations()
p_values = nsp.get_p_values()
q_values = nsp.get_p_values(mc_method="meff")

results = pd.concat([colocs, p_values, q_values], keys=["rho", "p", "q"])
results.droplevel(1).T.sort_values(by="p").head(8)

[3]:

		rho	p	q
set	map
Noradrenaline/Acetylcholine	target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017	0.435971	0.020	0.219690
Opioids/Endocannabinoids	target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018	0.339014	0.031	0.320682
Noradrenaline/Acetylcholine	target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017	0.309315	0.068	0.578821
Histamine	target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017	0.304823	0.075	0.616060
Glutamate	target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019	0.219451	0.167	0.893923
Serotonin	target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012	0.176491	0.227	0.957637
Opioids/Endocannabinoids	target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020	0.151909	0.254	0.972622
Dopamine	target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018	0.129229	0.272	0.979716

[4]:

# the nsp_object is a fully fitted NiSpace object — you can use all methods on it
nsp.plot(sort_by="coloc")

INFO | 01/06/26 15:06:22 | nispace.plotting: Significance annotation: 2/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_5_1.png

[4]:

(<Figure size 500x730 with 1 Axes>,
 <Axes: title={'center': "$Spearman's\\ Rho$ colocalization\n(permutation of $X\\ maps$)"}, xlabel='$Rho$'>,
 <seaborn._core.plot.Plotter at 0x16c5127f0>)

`colocalization()` — multiple maps

You have multiple brain maps and want to test whether they colocalize with a set of reference maps.

Here, we have an important parameter, pooled_p, that determines if p values are calculated for the average of colocalizations acoss your input maps or if one p value is calculated for each of the input maps.

Examples:

pooled_p=True: Multiple alterations maps from the same disorder (e.g., subject-level or group-level). “Do these 5 meta-analytic maps comparing depression to controls colocalize consistently with X?”
pooled_p=False: “How does each of these ENGIMA maps for different disorders correlate spatially with nuclear imaging maps?”

[5]:

from nispace.datasets import fetch_reference

# ENIGMA cortical thickness effect sizes — 22 psychiatric disorders, DesikanKilliany parcellation
# This is a natural multi-map case: we have separate effect size maps per disorder
enigma = fetch_reference("enigmathick", parcellation="DesikanKilliany", print_references=False)
print(f"ENIGMA: {enigma.shape[0]} disorder maps x {enigma.shape[1]} parcels")
print("Disorders:", list(enigma.index[:4]), "...")

# --- pooled_p=False (default): one p-value per disorder × receptor pair ---
# Use case: "how does each disorder's cortical thinning relate to each receptor?"
nsp_multi = colocalization(
    y=enigma,
    x="pet",
    x_collection="UniqueTracers",
    parcellation="DesikanKilliany",
    colocalization_method="spearman",
    pooled_p=False,     # one p per (Y map, X map) pair — default
    mc_method="meff",
    n_perm=1000,        # increase to >=10000 for final analyses
    seed=42, n_proc=4,
    plot=False, # not correctly implemented currently
    return_nispace_only=True
)
p_per_map = nsp_multi.get_p_values()
print(f"\npooled_p=False  → p-values shape: {p_per_map.shape}")
print(f"  {enigma.shape[0]} disorder rows × {p_per_map.shape[1]} receptor columns")

# --- pooled_p="mean": one pooled p-value per X map across all Y maps ---
# Use case: "do these disorders collectively and consistently colocalize with each receptor?"
nsp_pooled = colocalization(
    y=enigma,
    x="pet",
    x_collection="UniqueTracers",
    parcellation="DesikanKilliany",
    colocalization_method="spearman",
    pooled_p="mean",    # average colocs across Y maps → one p per X map
    mc_method="meff",
    n_perm=1000,
    seed=42, n_proc=4,
    plot=True,
    return_nispace_only=True
)
p_pooled = nsp_pooled.get_p_values()
print(f"\npooled_p='mean' → p-values shape: {p_pooled.shape}")
print(f"  1 pooled row × {p_pooled.shape[1]} receptor columns")

INFO | 01/06/26 15:06:22 | nispace.datasets: Loading enigmathick maps.
INFO | 01/06/26 15:06:22 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
ENIGMA: 22 disorder maps x 68 parcels
Disorders: ['dx-mdd_age-adult_pub-schmaal2017', 'dx-mdd_age-adolescent_pub-schmaal2017', 'dx-adhd_age-allages_pub-hoogman2019', 'dx-adhd_age-adult_pub-hoogman2019'] ...
INFO | 01/06/26 15:06:22 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 01/06/26 15:06:22 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:06:22 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:06:22 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:22 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
The NiSpace "PET" dataset is based on openly available nuclear imaging maps largely accessed via neuromaps
(https://neuromaps-main.readthedocs.io/). If requested in the varying original spaces and resolutions (termed "MNI152",
"fsaverageOriginal", or "fsLROriginal"), the maps are downloaded directly from the source and cached locally. If, as is highly
recommended, the maps are requested in a defined space ("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR"),
they are downloaded from the NiSpace-data GitHub repo (find them in `~HOME/nispace-data/reference/pet/map`).
The NiSpace-hosted MNI maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to 2mm MNI152NLin2009cAsym
with a pre-estimated MNI-to-MNI transformation using SynthMorph v4 (https://martinos.org/malte/synthmorph/). The resulting maps
were masked with a liberal grey matter mask generated from the Harvard-Oxford atlas and scaled from 1e-6 to 1. The scaling was
transferred from MNI to surface maps if both were available for the same source (e.g., maps from Beliveau et al.).
The accompanying metadata table contains detailed information about tracers, source samples, original publications and data
sources, as well as the publication licenses. Every map should be cited when used. The responsibility for this lies with the user!
We additionally ask to cite:
- Markello et al., 2022 (https://doi.org/10.1038/s41592-022-01625-w)
- Hansen et al., 2022 (https://doi.org/10.1038/s41593-022-01186-3)
- Dukart et al., 2021 (https://doi.org/10.1002/hbm.25244)
- Hoffmann et al., 2024 (https://doi.org/10.1162/imag_a_00197; if NiSpace-processed maps are used)
To ensure reproducibility, note the NiSpace commit/version: 0.0.1b5.dev68+g20be93445.d20260520

- target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012         Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT1b_tracer-p943_n-23_dx-hc_pub-savli2012              Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT2a_tracer-altanserin_n-19_dx-hc_pub-savli2012        Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT4_tracer-sb207145_n-59_dx-hc_pub-beliveau2017        Source: Beliveau2017       CC BY-NC-SA 4.0  https://doi.org/10.1523/JNEUROSCI.2830-16.2016
    CAVE: Processed in fsaverage space, use  volumetric maps only for subcortex!
- target-5HT6_tracer-gsk215083_n-30_dx-hc_pub-radhakrishnan2018  Source: Radhakrishnan2018  CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.117.206516, https://doi.org/10.1016/j.pscychresns.2019.111007
- target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012               Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-A4B2_tracer-flubatine_n-30_dx-hc_pub-hillmer2016        Source: Hillmer2016        CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2016.07.026, https://doi.org/10.1093/ntr/ntx091
- target-CB1_tracer-omar_n-77_dx-hc_pub-normandin2015            Source: Normandin2015      CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2015.46, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1016/j.biopsych.2015.08.021, https://doi.org/10.1111/j.1530-0277.2012.01815.x
- target-CMRglu_tracer-fdg_n-20_dx-hc_pub-castrillon2023         Source: Castrillon2023     CC BY-NC-SA 4.0  https://doi.org/10.1126/sciadv.adi7632
- target-COX1_tracer-ps13_n-11_dx-hc_pub-kim2020                 Source: Kim2020            CC0 1.0          https://doi.org/10.1007/s00259-020-04855-2, https://doi.org/10.18112/openneuro.ds004401.v1.0.1
- target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017            Source: Kaller2017         CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-017-3645-0
- target-D23_tracer-flb457_n-55_dx-hc_pub-sandiego2015           Source: Sandiego2015       CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2014.237, https://doi.org/10.1177/0271678X17737693, https://doi.org/10.1038/s41386-019-0456-y, https://doi.org/10.1001/jamapsychiatry.2014.2414, https://doi.org/10.1038/npp.2017.223
- target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018             Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
    CAVE: SPECT, not PET!
- target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018  Source: Garciagomez2018    free             https://doi.org/10.33588/imagendiagnostica.901.2
- target-GABAa_tracer-flumazenil_n-6_dx-hc_pub-dukart2018        Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
- target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022         Source: Lukow2022          CC BY 4.0        https://doi.org/10.1038/s42003-022-03268-1
- target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017          Source: Gallezot2017       CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X16650697, https://doi.org/10.1038/jcbfm.2009.195
- target-HDAC_tracer-martinostat_n-8_dx-hc_pub-wey2016           Source: Wey2016            CC0 1.0          https://doi.org/10.1126/scitranslmed.aaf7551
- target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018           Source: Vijay2018          CC BY-NC-SA 4.0  https://doi.org/10.1038/s41386-018-0199-1
- target-M1_tracer-lsn3172176_n-24_dx-hc_pub-naganawa2020        Source: Naganawa2020       CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.120.246967
- target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019           Source: Smart2019          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-018-4252-4
- target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020     Source: Kantonen2020       CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017                 Source: Hesse2017          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-016-3590-3
- target-NMDA_tracer-ge179_n-29_dx-hc_pub-galovic2021            Source: Galovic2021        CC BY-NC-SA 4.0  https://doi.org/10.1001/jamaneurol.2022.4352, https://doi.org/10.1016/j.neuroimage.2021.118194, https://doi.org/10.2967/jnumed.113.130641
    CAVE: Unlike other tracers, [18F]GE-179 binds to open (active) NMDA receptors!
- target-rCPS_tracer-leucine_n-42_dx-hc_pub-smith2023            Source: Smith2023          CC0 1.0          https://doi.org/10.18112/openneuro.ds004654.v1.0.1, https://doi.org/10.18112/openneuro.ds004730.v1.0.0, https://doi.org/10.18112/openneuro.ds004731.v1.0.0, https://doi.org/10.18112/openneuro.ds004733.v1.0.0, https://doi.org/10.1016/j.nbd.2020.104978, https://doi.org/10.1177/0271678X221090997, https://doi.org/10.1038/jcbfm.2009.7, https://doi.org/10.1093/sleep/zsy088, https://doi.org/10.1177/0271678X221121873
- target-SV2A_tracer-ucbj_n-76_dx-hc_pub-finnema2016             Source: Finnema2016        CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X17724947, https://doi.org/10.2967/jnumed.120.246967, https://doi.org/10.1177/0271678X211004312, https://doi.org/10.1186/s13195-020-00742-y, https://doi.org/10.1177/0271678X20946198, https://doi.org/10.1093/cid/ciab484, https://doi.org/10.1038/s41380-021-01184-0, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1111/epi.16653, https://doi.org/10.1186/s13550-020-00670-w, https://doi.org/10.1002/alz.12097, https://doi.org/10.1111/epi.14701, https://doi.org/10.1038/s41467-019-09562-7, https://doi.org/10.1001/jamaneurol.2018.1836
- target-TSPO_tracer-pbr28_n-6_dx-hc_pub-lois2018                Source: Lois2018           MIT              https://doi.org/10.1021/acschemneuro.8b00072, https://doi.org/10.5281/zenodo.1174364
- target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017         Source: Aghourian2017      CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020             Source: Larsen2020         CC0 1.0          https://doi.org/10.18112/openneuro.ds002385.v1.1.0, https://doi.org/10.1038/s41467-020-14693-3

INFO | 01/06/26 15:06:22 | nispace.core.parcellation: Building multi-space Parcellation for 'DesikanKilliany' from library.
INFO | 01/06/26 15:06:22 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:22 | nispace.core.parcellation: Parcellation 'DesikanKilliany': validation passed.
INFO | 01/06/26 15:06:22 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:22 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:06:22 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:22 | nispace.io: Parcellated data contains nan values!

Colocalizing (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████| 22/22 [00:00<00:00, 1834.38it/s]

INFO | 01/06/26 15:06:22 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 01/06/26 15:06:22 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:06:22 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'alexander_bloch').
INFO | 01/06/26 15:06:22 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 68 parcels.
INFO | 01/06/26 15:06:22 | nispace.nulls: Using provided precomputed spin matrix.


Spin null maps: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 260.91it/s]

INFO | 01/06/26 15:06:22 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:06:22 | nispace.core.permute: Z-standardizing null maps.


Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 8848.54it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 4430.31it/s]

INFO | 01/06/26 15:06:23 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).

pooled_p=False  → p-values shape: (22, 29)
  22 disorder rows × 29 receptor columns
INFO | 01/06/26 15:06:23 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 01/06/26 15:06:23 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:06:23 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:06:23 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:23 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
The NiSpace "PET" dataset is based on openly available nuclear imaging maps largely accessed via neuromaps
(https://neuromaps-main.readthedocs.io/). If requested in the varying original spaces and resolutions (termed "MNI152",
"fsaverageOriginal", or "fsLROriginal"), the maps are downloaded directly from the source and cached locally. If, as is highly
recommended, the maps are requested in a defined space ("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR"),
they are downloaded from the NiSpace-data GitHub repo (find them in `~HOME/nispace-data/reference/pet/map`).
The NiSpace-hosted MNI maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to 2mm MNI152NLin2009cAsym
with a pre-estimated MNI-to-MNI transformation using SynthMorph v4 (https://martinos.org/malte/synthmorph/). The resulting maps
were masked with a liberal grey matter mask generated from the Harvard-Oxford atlas and scaled from 1e-6 to 1. The scaling was
transferred from MNI to surface maps if both were available for the same source (e.g., maps from Beliveau et al.).
The accompanying metadata table contains detailed information about tracers, source samples, original publications and data
sources, as well as the publication licenses. Every map should be cited when used. The responsibility for this lies with the user!
We additionally ask to cite:
- Markello et al., 2022 (https://doi.org/10.1038/s41592-022-01625-w)
- Hansen et al., 2022 (https://doi.org/10.1038/s41593-022-01186-3)
- Dukart et al., 2021 (https://doi.org/10.1002/hbm.25244)
- Hoffmann et al., 2024 (https://doi.org/10.1162/imag_a_00197; if NiSpace-processed maps are used)
To ensure reproducibility, note the NiSpace commit/version: 0.0.1b5.dev68+g20be93445.d20260520

- target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012         Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT1b_tracer-p943_n-23_dx-hc_pub-savli2012              Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT2a_tracer-altanserin_n-19_dx-hc_pub-savli2012        Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT4_tracer-sb207145_n-59_dx-hc_pub-beliveau2017        Source: Beliveau2017       CC BY-NC-SA 4.0  https://doi.org/10.1523/JNEUROSCI.2830-16.2016
    CAVE: Processed in fsaverage space, use  volumetric maps only for subcortex!
- target-5HT6_tracer-gsk215083_n-30_dx-hc_pub-radhakrishnan2018  Source: Radhakrishnan2018  CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.117.206516, https://doi.org/10.1016/j.pscychresns.2019.111007
- target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012               Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-A4B2_tracer-flubatine_n-30_dx-hc_pub-hillmer2016        Source: Hillmer2016        CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2016.07.026, https://doi.org/10.1093/ntr/ntx091
- target-CB1_tracer-omar_n-77_dx-hc_pub-normandin2015            Source: Normandin2015      CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2015.46, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1016/j.biopsych.2015.08.021, https://doi.org/10.1111/j.1530-0277.2012.01815.x
- target-CMRglu_tracer-fdg_n-20_dx-hc_pub-castrillon2023         Source: Castrillon2023     CC BY-NC-SA 4.0  https://doi.org/10.1126/sciadv.adi7632
- target-COX1_tracer-ps13_n-11_dx-hc_pub-kim2020                 Source: Kim2020            CC0 1.0          https://doi.org/10.1007/s00259-020-04855-2, https://doi.org/10.18112/openneuro.ds004401.v1.0.1
- target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017            Source: Kaller2017         CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-017-3645-0
- target-D23_tracer-flb457_n-55_dx-hc_pub-sandiego2015           Source: Sandiego2015       CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2014.237, https://doi.org/10.1177/0271678X17737693, https://doi.org/10.1038/s41386-019-0456-y, https://doi.org/10.1001/jamapsychiatry.2014.2414, https://doi.org/10.1038/npp.2017.223
- target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018             Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
    CAVE: SPECT, not PET!
- target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018  Source: Garciagomez2018    free             https://doi.org/10.33588/imagendiagnostica.901.2
- target-GABAa_tracer-flumazenil_n-6_dx-hc_pub-dukart2018        Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
- target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022         Source: Lukow2022          CC BY 4.0        https://doi.org/10.1038/s42003-022-03268-1
- target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017          Source: Gallezot2017       CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X16650697, https://doi.org/10.1038/jcbfm.2009.195
- target-HDAC_tracer-martinostat_n-8_dx-hc_pub-wey2016           Source: Wey2016            CC0 1.0          https://doi.org/10.1126/scitranslmed.aaf7551
- target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018           Source: Vijay2018          CC BY-NC-SA 4.0  https://doi.org/10.1038/s41386-018-0199-1
- target-M1_tracer-lsn3172176_n-24_dx-hc_pub-naganawa2020        Source: Naganawa2020       CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.120.246967
- target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019           Source: Smart2019          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-018-4252-4
- target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020     Source: Kantonen2020       CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017                 Source: Hesse2017          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-016-3590-3
- target-NMDA_tracer-ge179_n-29_dx-hc_pub-galovic2021            Source: Galovic2021        CC BY-NC-SA 4.0  https://doi.org/10.1001/jamaneurol.2022.4352, https://doi.org/10.1016/j.neuroimage.2021.118194, https://doi.org/10.2967/jnumed.113.130641
    CAVE: Unlike other tracers, [18F]GE-179 binds to open (active) NMDA receptors!
- target-rCPS_tracer-leucine_n-42_dx-hc_pub-smith2023            Source: Smith2023          CC0 1.0          https://doi.org/10.18112/openneuro.ds004654.v1.0.1, https://doi.org/10.18112/openneuro.ds004730.v1.0.0, https://doi.org/10.18112/openneuro.ds004731.v1.0.0, https://doi.org/10.18112/openneuro.ds004733.v1.0.0, https://doi.org/10.1016/j.nbd.2020.104978, https://doi.org/10.1177/0271678X221090997, https://doi.org/10.1038/jcbfm.2009.7, https://doi.org/10.1093/sleep/zsy088, https://doi.org/10.1177/0271678X221121873
- target-SV2A_tracer-ucbj_n-76_dx-hc_pub-finnema2016             Source: Finnema2016        CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X17724947, https://doi.org/10.2967/jnumed.120.246967, https://doi.org/10.1177/0271678X211004312, https://doi.org/10.1186/s13195-020-00742-y, https://doi.org/10.1177/0271678X20946198, https://doi.org/10.1093/cid/ciab484, https://doi.org/10.1038/s41380-021-01184-0, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1111/epi.16653, https://doi.org/10.1186/s13550-020-00670-w, https://doi.org/10.1002/alz.12097, https://doi.org/10.1111/epi.14701, https://doi.org/10.1038/s41467-019-09562-7, https://doi.org/10.1001/jamaneurol.2018.1836
- target-TSPO_tracer-pbr28_n-6_dx-hc_pub-lois2018                Source: Lois2018           MIT              https://doi.org/10.1021/acschemneuro.8b00072, https://doi.org/10.5281/zenodo.1174364
- target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017         Source: Aghourian2017      CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020             Source: Larsen2020         CC0 1.0          https://doi.org/10.18112/openneuro.ds002385.v1.1.0, https://doi.org/10.1038/s41467-020-14693-3

INFO | 01/06/26 15:06:23 | nispace.core.parcellation: Building multi-space Parcellation for 'DesikanKilliany' from library.
INFO | 01/06/26 15:06:23 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:23 | nispace.core.parcellation: Parcellation 'DesikanKilliany': validation passed.
INFO | 01/06/26 15:06:23 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:23 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:06:23 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:23 | nispace.io: Parcellated data contains nan values!

Colocalizing (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████| 22/22 [00:00<00:00, 1945.00it/s]

INFO | 01/06/26 15:06:23 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 01/06/26 15:06:23 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:06:23 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'alexander_bloch').
INFO | 01/06/26 15:06:23 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 68 parcels.
INFO | 01/06/26 15:06:23 | nispace.nulls: Using provided precomputed spin matrix.


Spin null maps: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 262.61it/s]

INFO | 01/06/26 15:06:23 | nispace.nulls: Null data generation finished.
INFO | 01/06/26 15:06:23 | nispace.core.permute: Z-standardizing null maps.


Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 8765.86it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 4291.92it/s]

INFO | 01/06/26 15:06:24 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:06:24 | nispace.plotting: Significance annotation: 2/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_7_13.png


pooled_p='mean' → p-values shape: (1, 29)
  1 pooled row × 29 receptor columns

`group_colocalization()` — patient vs. control

The group comparison workflow handles the full pipeline for individual subject data: covariate regression, effect size computation, colocalization, and group label permutation.

The design argument is a DataFrame with one row per subject. The column "groups" is required; any other columns are treated as covariates to regress out. A "site" column triggers ComBat harmonization if combat=True.

We use the anorexia nervosa example dataset here.

Note: This dataset is simulated and not intended for scientific use — it exists purely for demonstration purposes.

This workflow employs group label permutation to generate null maps (as compared to spatial null models). This is a very elegant approach for group comparisons in spatial correlation analyses because general spatial patterns will naturally be conserved in the permuted alteration images, without relying on a null model’s ability to capture said spatial patterns.

[6]:

from nispace.workflows import group_colocalization
from nispace.datasets import fetch_example

# load the anorexia nervosa example data
an_data = fetch_example("anorexianervosa", parcellation="Schaefer200")

# extract group labels
groups = an_data.index.str.extract(r'(AN|HC)$')[0].values

# generate synthetic covariates
rng = np.random.default_rng(42)
age = np.concatenate([rng.normal(25, 5, 50), rng.normal(30, 5, 50)])
sex = rng.integers(0, 2, 100)

# design matrix: groups column is mandatory, others are covariates
design = pd.DataFrame({
    "groups": groups,
    "age": age,
    "sex": sex
}, index=an_data.index)

nsp_gc = group_colocalization(
    y=an_data,
    design=design,
    x="pet",
    x_collection="UniqueTracers",
    parcellation="Schaefer200",
    comparison_method="hedges(a,b)",
    colocalization_method="spearman",
    n_perm=1000,
    seed=42,
    n_proc=4,
    return_nispace_only=True
)

INFO | 01/06/26 15:06:25 | nispace.datasets: Loading example dataset: 'anorexianervosa', parcellated with: Schaefer200Parcels7Networks.
INFO | 01/06/26 15:06:25 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 01/06/26 15:06:25 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:06:25 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:06:25 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:25 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
The NiSpace "PET" dataset is based on openly available nuclear imaging maps largely accessed via neuromaps
(https://neuromaps-main.readthedocs.io/). If requested in the varying original spaces and resolutions (termed "MNI152",
"fsaverageOriginal", or "fsLROriginal"), the maps are downloaded directly from the source and cached locally. If, as is highly
recommended, the maps are requested in a defined space ("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR"),
they are downloaded from the NiSpace-data GitHub repo (find them in `~HOME/nispace-data/reference/pet/map`).
The NiSpace-hosted MNI maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to 2mm MNI152NLin2009cAsym
with a pre-estimated MNI-to-MNI transformation using SynthMorph v4 (https://martinos.org/malte/synthmorph/). The resulting maps
were masked with a liberal grey matter mask generated from the Harvard-Oxford atlas and scaled from 1e-6 to 1. The scaling was
transferred from MNI to surface maps if both were available for the same source (e.g., maps from Beliveau et al.).
The accompanying metadata table contains detailed information about tracers, source samples, original publications and data
sources, as well as the publication licenses. Every map should be cited when used. The responsibility for this lies with the user!
We additionally ask to cite:
- Markello et al., 2022 (https://doi.org/10.1038/s41592-022-01625-w)
- Hansen et al., 2022 (https://doi.org/10.1038/s41593-022-01186-3)
- Dukart et al., 2021 (https://doi.org/10.1002/hbm.25244)
- Hoffmann et al., 2024 (https://doi.org/10.1162/imag_a_00197; if NiSpace-processed maps are used)
To ensure reproducibility, note the NiSpace commit/version: 0.0.1b5.dev68+g20be93445.d20260520

- target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012         Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT1b_tracer-p943_n-23_dx-hc_pub-savli2012              Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT2a_tracer-altanserin_n-19_dx-hc_pub-savli2012        Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-5HT4_tracer-sb207145_n-59_dx-hc_pub-beliveau2017        Source: Beliveau2017       CC BY-NC-SA 4.0  https://doi.org/10.1523/JNEUROSCI.2830-16.2016
    CAVE: Processed in fsaverage space, use  volumetric maps only for subcortex!
- target-5HT6_tracer-gsk215083_n-30_dx-hc_pub-radhakrishnan2018  Source: Radhakrishnan2018  CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.117.206516, https://doi.org/10.1016/j.pscychresns.2019.111007
- target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012               Source: Savli2012          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2012.07.001
- target-A4B2_tracer-flubatine_n-30_dx-hc_pub-hillmer2016        Source: Hillmer2016        CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2016.07.026, https://doi.org/10.1093/ntr/ntx091
- target-CB1_tracer-omar_n-77_dx-hc_pub-normandin2015            Source: Normandin2015      CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2015.46, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1016/j.biopsych.2015.08.021, https://doi.org/10.1111/j.1530-0277.2012.01815.x
- target-CMRglu_tracer-fdg_n-20_dx-hc_pub-castrillon2023         Source: Castrillon2023     CC BY-NC-SA 4.0  https://doi.org/10.1126/sciadv.adi7632
- target-COX1_tracer-ps13_n-11_dx-hc_pub-kim2020                 Source: Kim2020            CC0 1.0          https://doi.org/10.1007/s00259-020-04855-2, https://doi.org/10.18112/openneuro.ds004401.v1.0.1
- target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017            Source: Kaller2017         CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-017-3645-0
- target-D23_tracer-flb457_n-55_dx-hc_pub-sandiego2015           Source: Sandiego2015       CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2014.237, https://doi.org/10.1177/0271678X17737693, https://doi.org/10.1038/s41386-019-0456-y, https://doi.org/10.1001/jamapsychiatry.2014.2414, https://doi.org/10.1038/npp.2017.223
- target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018             Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
    CAVE: SPECT, not PET!
- target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018  Source: Garciagomez2018    free             https://doi.org/10.33588/imagendiagnostica.901.2
- target-GABAa_tracer-flumazenil_n-6_dx-hc_pub-dukart2018        Source: Dukart2018         CC BY-NC-SA 4.0  https://doi.org/10.1038/s41598-018-22444-0
- target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022         Source: Lukow2022          CC BY 4.0        https://doi.org/10.1038/s42003-022-03268-1
- target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017          Source: Gallezot2017       CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X16650697, https://doi.org/10.1038/jcbfm.2009.195
- target-HDAC_tracer-martinostat_n-8_dx-hc_pub-wey2016           Source: Wey2016            CC0 1.0          https://doi.org/10.1126/scitranslmed.aaf7551
- target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018           Source: Vijay2018          CC BY-NC-SA 4.0  https://doi.org/10.1038/s41386-018-0199-1
- target-M1_tracer-lsn3172176_n-24_dx-hc_pub-naganawa2020        Source: Naganawa2020       CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.120.246967
- target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019           Source: Smart2019          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-018-4252-4
- target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020     Source: Kantonen2020       CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017                 Source: Hesse2017          CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-016-3590-3
- target-NMDA_tracer-ge179_n-29_dx-hc_pub-galovic2021            Source: Galovic2021        CC BY-NC-SA 4.0  https://doi.org/10.1001/jamaneurol.2022.4352, https://doi.org/10.1016/j.neuroimage.2021.118194, https://doi.org/10.2967/jnumed.113.130641
    CAVE: Unlike other tracers, [18F]GE-179 binds to open (active) NMDA receptors!
- target-rCPS_tracer-leucine_n-42_dx-hc_pub-smith2023            Source: Smith2023          CC0 1.0          https://doi.org/10.18112/openneuro.ds004654.v1.0.1, https://doi.org/10.18112/openneuro.ds004730.v1.0.0, https://doi.org/10.18112/openneuro.ds004731.v1.0.0, https://doi.org/10.18112/openneuro.ds004733.v1.0.0, https://doi.org/10.1016/j.nbd.2020.104978, https://doi.org/10.1177/0271678X221090997, https://doi.org/10.1038/jcbfm.2009.7, https://doi.org/10.1093/sleep/zsy088, https://doi.org/10.1177/0271678X221121873
- target-SV2A_tracer-ucbj_n-76_dx-hc_pub-finnema2016             Source: Finnema2016        CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X17724947, https://doi.org/10.2967/jnumed.120.246967, https://doi.org/10.1177/0271678X211004312, https://doi.org/10.1186/s13195-020-00742-y, https://doi.org/10.1177/0271678X20946198, https://doi.org/10.1093/cid/ciab484, https://doi.org/10.1038/s41380-021-01184-0, https://doi.org/10.1016/j.bpsc.2015.09.008, https://doi.org/10.1111/epi.16653, https://doi.org/10.1186/s13550-020-00670-w, https://doi.org/10.1002/alz.12097, https://doi.org/10.1111/epi.14701, https://doi.org/10.1038/s41467-019-09562-7, https://doi.org/10.1001/jamaneurol.2018.1836
- target-TSPO_tracer-pbr28_n-6_dx-hc_pub-lois2018                Source: Lois2018           MIT              https://doi.org/10.1021/acschemneuro.8b00072, https://doi.org/10.5281/zenodo.1174364
- target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017         Source: Aghourian2017      CC BY-NC-SA 4.0  https://doi.org/10.1038/mp.2017.183
- target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020             Source: Larsen2020         CC0 1.0          https://doi.org/10.18112/openneuro.ds002385.v1.1.0, https://doi.org/10.1038/s41467-020-14693-3

INFO | 01/06/26 15:06:25 | nispace.core.parcellation: Building multi-space Parcellation for 'Schaefer200Parcels7Networks' from library.
INFO | 01/06/26 15:06:25 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:25 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': validation passed.
INFO | 01/06/26 15:06:25 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 01/06/26 15:06:25 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:06:25 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:06:25 | nispace.workflows: DataFrame provided for design. Expecting 'groups' and, if paired==True, 'subjects' columns.
INFO | 01/06/26 15:06:25 | nispace.workflows: Design matrix of shape (100, 3). Assuming 100 subjects/maps.
INFO | 01/06/26 15:06:25 | nispace.core.clean_y: Detected categorical covariates: none; continuous: ['age', 'sex'].

../_images/nb_introduction_intro09_workflows_9_1.png

INFO | 01/06/26 15:06:25 | nispace.core.clean_y: Protecting 1 variable(s) during regression: ['groups_HC'].
INFO | 01/06/26 15:06:25 | nispace.core.clean_y: Regressing 2 between covariate(s) from Y.

Regressing 2 between covariate(s) from Y, protecting 1 variable(s) (4 proc): 100%|██████████████████████████████████████████████████████████████████| 200/200 [00:01<00:00, 100.90it/s]
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1492.63it/s]

INFO | 01/06/26 15:06:27 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.


Permuting groups (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 944237.73it/s]
Null transformations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 4157.37it/s]
Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 3981.32it/s]
Null colocalizations (spearman, 4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 14832.86it/s]

INFO | 01/06/26 15:06:28 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:06:28 | nispace.plotting: Significance annotation: 9/29 p_uncorrected < 0.05, 5/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_9_7.png

[7]:

colocs_gc = nsp_gc.get_colocalizations()
p_gc      = nsp_gc.get_p_values()
q_gc      = nsp_gc.get_corrected_p_values() # short cut for get_p_values(mc_method="meff")

gc_results = pd.concat([colocs_gc, p_gc, q_gc], keys=["rho", "p", "q"])
gc_results.droplevel(1).T.sort_values(by="p").head(8)

[7]:

		rho	p	q
set	map
Serotonin	target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012	-0.289860	0.001	0.012210
GABA	target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022	-0.294028	0.001	0.012210
Dopamine	target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018	-0.258163	0.001	0.012210
Serotonin	target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012	-0.208632	0.004	0.048022
General	target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020	-0.208262	0.004	0.048022
Immunity	target-TSPO_tracer-pbr28_n-6_dx-hc_pub-lois2018	-0.200293	0.008	0.093917
Dopamine	target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017	-0.204952	0.008	0.093917
Dopamine	target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018	-0.152391	0.026	0.276367

[8]:

nsp_gc.plot(sort_by="coloc")

INFO | 01/06/26 15:06:28 | nispace.plotting: Significance annotation: 9/29 p_uncorrected < 0.05, 5/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_11_1.png

[8]:

(<Figure size 500x730 with 1 Axes>,
 <Axes: title={'center': "$Spearman's\\ Rho$ colocalization after $Hedges'\\ g$ transform\n(permutation of $Groups$)"}, xlabel='$Rho$'>,
 <seaborn._core.plot.Plotter at 0x31c8bbcd0>)

[9]:

# effect size map on the brain
nsp_gc.plot_brain(data="Y", symmetric_cmap=True)

WARNING | 01/06/26 15:06:28 | nispace.plotting: Brain plotting in NiSpace is experimental. If things look off, feel free to raise a GitHub issue!
INFO | 01/06/26 15:06:28 | nispace.plotting: brainplot: threshold='auto' → 0.001035715569742024
INFO | 01/06/26 15:06:28 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:06:29 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': active space set to 'MNI152NLin2009cAsym' (was 'fsLR').
INFO | 01/06/26 15:06:29 | nispace.plotting: brainplot: kind='glass', img_mode='None', surf_space='None', mni_space='MNI152NLin2009cAsym', surf_mesh='inflated'

../_images/nb_introduction_intro09_workflows_12_1.png

[9]:

(<Figure size 720x180 with 6 Axes>, [<Axes: >])

`xsea()` — X-Set Enrichment Analysis

XSEA tests whether the average colocalization between your input map and a set of reference maps is higher than expected by chance. This is useful when you have reference maps organized into biologically meaningful groups (e.g., gene expression grouped by cell type).

Note that, as above, you can pass more than one map here to the y parameter. The pooled_p here equally determines if you get one p value per input map or one p value across all input maps.

We’ll cover XSEA in much more detail in Notebook 10. Here’s a minimal example:

[10]:

from nispace.workflows import xsea
from nispace.datasets import fetch_reference

# use the anorexia nervosa Hedges' g map we computed above
hedges_g = nsp_gc.get_y()

# test against mRNA gene expression sets (cell type markers)
nsp_xsea = xsea(
    y=hedges_g,
    x="mrna",          # mRNA gene expression reference
    x_collection="CellTypesSilettiSuperclusters",  # predefined cell type sets
    parcellation="Schaefer200",
    colocalization_method="spearman",
    n_perm=1000,
    seed=42,
    n_proc=4,
    return_nispace_only=True
)

INFO | 01/06/26 15:06:32 | nispace.workflows: Loading integrated mrna dataset as X data.
INFO | 01/06/26 15:06:32 | nispace.datasets: Loading mrna maps.
INFO | 01/06/26 15:06:32 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 01/06/26 15:06:32 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:32 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
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


INFO | 01/06/26 15:06:33 | nispace.core.parcellation: Building multi-space Parcellation for 'Schaefer200Parcels7Networks' from library.
INFO | 01/06/26 15:06:33 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:33 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': validation passed.
INFO | 01/06/26 15:06:33 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:06:33 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).

Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1779.51it/s]

INFO | 01/06/26 15:06:33 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 01/06/26 15:06:33 | nispace.core.permute: No null maps found.
INFO | 01/06/26 15:06:33 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'alexander_bloch').
INFO | 01/06/26 15:06:33 | nispace.nulls: Null map generation: Assuming n = 1 data vector(s) for n = 200 parcels.
INFO | 01/06/26 15:06:33 | nispace.nulls: Using provided precomputed spin matrix.


Spin null maps: 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 149.93it/s]

INFO | 01/06/26 15:06:33 | nispace.nulls: Null data generation finished.


Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 9295.50it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 2679.41it/s]

INFO | 01/06/26 15:06:34 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:06:34 | nispace.plotting: Significance annotation: 2/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_14_7.png

[11]:

nsp_xsea.plot(sort_by="coloc")

INFO | 01/06/26 15:06:34 | nispace.plotting: Significance annotation: 2/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_15_1.png

[11]:

(<Figure size 500x730 with 1 Axes>,
 <Axes: title={'center': "$Spearman's\\ Rho$ colocalization\n(permutation of $X\\ maps$)"}, xlabel='$Rho$'>,
 <seaborn._core.plot.Plotter at 0x15e9f2c70>)

`group_xsea()` — group comparison with set enrichment

group_xsea() combines the group comparison design of group_colocalization() with the set-level aggregation of xsea(). It is the right workflow when you have individual subject data and want to ask whether the effect size map of a group difference aligns with specific biological systems — gene expression cell types, neurotransmitter systems, etc.

Under the hood it is exactly group_colocalization() with XSEA activated: group labels are permuted to generate null effect size maps, and those null maps are then used to build the null distribution for set-level colocalizations.

We use the same anorexia nervosa data and design matrix from the previous section.

Note: The anorexia nervosa dataset is simulated and not intended for scientific use.

[12]:

from nispace.workflows import group_xsea

nsp_gxsea = group_xsea(
    y=an_data,
    design=design,
    x="mrna",
    x_collection="CellTypesSilettiSuperclusters",
    parcellation="Schaefer200",
    comparison_method="hedges(a,b)",
    colocalization_method="spearman",
    mc_method="meff",
    n_perm=1000,
    seed=42, n_proc=4,
    return_nispace_only=True
)
nsp_gxsea.plot(sort_by="coloc")

INFO | 01/06/26 15:06:34 | nispace.workflows: Loading integrated mrna dataset as X data.
INFO | 01/06/26 15:06:34 | nispace.datasets: Loading mrna maps.
INFO | 01/06/26 15:06:34 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 01/06/26 15:06:34 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:06:35 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
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


INFO | 01/06/26 15:06:35 | nispace.core.parcellation: Building multi-space Parcellation for 'Schaefer200Parcels7Networks' from library.
INFO | 01/06/26 15:06:35 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:06:35 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': validation passed.
INFO | 01/06/26 15:06:35 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:06:35 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 01/06/26 15:06:35 | nispace.workflows: DataFrame provided for design. Expecting 'groups' and, if paired==True, 'subjects' columns.
INFO | 01/06/26 15:06:35 | nispace.workflows: Design matrix of shape (100, 3). Assuming 100 subjects/maps.
INFO | 01/06/26 15:06:35 | nispace.core.clean_y: Detected categorical covariates: none; continuous: ['age', 'sex'].

../_images/nb_introduction_intro09_workflows_17_1.png

INFO | 01/06/26 15:06:35 | nispace.core.clean_y: Protecting 1 variable(s) during regression: ['groups_HC'].
INFO | 01/06/26 15:06:35 | nispace.core.clean_y: Regressing 2 between covariate(s) from Y.

Regressing 2 between covariate(s) from Y, protecting 1 variable(s) (4 proc): 100%|█████████████████████████████████████████████████████████████████| 200/200 [00:00<00:00, 5835.68it/s]
Colocalizing (spearman, 4 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1520.23it/s]

INFO | 01/06/26 15:06:35 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.


Permuting groups (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 921825.05it/s]
Null transformations (spearman, 4 proc): 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 11803.87it/s]
Processing null arrays (4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 9453.49it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 2646.92it/s]

INFO | 01/06/26 15:06:36 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 01/06/26 15:06:37 | nispace.plotting: Significance annotation: 18/29 p_uncorrected < 0.05, 8/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_17_7.png

INFO | 01/06/26 15:06:37 | nispace.plotting: Significance annotation: 18/29 p_uncorrected < 0.05, 8/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_17_9.png

[12]:

(<Figure size 500x730 with 1 Axes>,
 <Axes: title={'center': "$Spearman's\\ Rho$ colocalization after $Hedges'\\ g$ transform\n(permutation of $Groups$)"}, xlabel='$Rho$'>,
 <seaborn._core.plot.Plotter at 0x32bf31d30>)

When to use workflows vs. the object API

Situation	Recommended approach
Quick analysis, standard pipeline	Workflow function
Need full control over each step	Object API (`NiSpace` class)
Custom preprocessing sequence	Object API
Running the same analysis on many maps	Object API (reuse the fitted object)
Embedding in a larger pipeline	Object API
Teaching/demonstration	Workflow (less boilerplate)

The two approaches are not exclusive. You can start with a workflow, inspect the returned nsp object, and then call additional methods on it.

Summary

Four workflow functions, all returning a fitted NiSpace object with return_nispace_only=True:

Function	Input Y	Reference X	Null model
`colocalization()`	Group-level map(s)	Any	Surrogate map permutation
`group_colocalization()`	Individual subjects + design	Any	Group label permutation
`xsea()`	Group-level map(s)	Set-structured	Surrogate map permutation
`group_xsea()`	Individual subjects + design	Set-structured	Group label permutation

The pooled_p parameter controls how p-values are computed when multiple Y maps are passed:

pooled_p=False — one p-value per (Y map × X map) pair (default)
pooled_p="mean" — average colocalizations across Y maps first, then compute one p per X map
pooled_p="auto" — False for a single Y map, "mean" otherwise

nsp = colocalization(y, x="pet", x_collection=None, parcellation="Schaefer200",
                     colocalization_method="spearman", mc_method="meff",
                     pooled_p=False, n_perm=10000, seed=None, n_proc=1, return_nispace_only=True)

nsp = group_colocalization(y, design, x="pet", comparison_method="hedges(a,b)",
                           parcellation="Schaefer200", colocalization_method="spearman",
                           mc_method="meff", n_perm=10000,
                           seed=None, n_proc=1, return_nispace_only=True)

nsp = xsea(y, x="mrna", x_collection=None, parcellation="Schaefer200",
           colocalization_method="spearman", mc_method="meff",
           pooled_p=False, n_perm=10000, seed=None, n_proc=1, return_nispace_only=True)

nsp = group_xsea(y, design, x="mrna", x_collection=None,
                 comparison_method="hedges(a,b)", parcellation="Schaefer200",
                 colocalization_method="spearman", mc_method="meff",
                 n_perm=10000, seed=None, n_proc=1, return_nispace_only=True)

# retrieve results
colocs   = nsp.get_colocalizations()
p_values = nsp.get_p_values()
q_values = nsp.get_p_values(mc_method="meff")

Next: Notebook 10 dives deep into X-Set Enrichment Analysis.

NiSpace workflows

colocalization() — single map

colocalization() — multiple maps

group_colocalization() — patient vs. control

xsea() — X-Set Enrichment Analysis

group_xsea() — group comparison with set enrichment