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

[2]:

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.

[3]:

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="Yan200", # 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 | 20/07/26 18:24:23 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 20/07/26 18:24:23 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:24:23 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 20/07/26 18:24:23 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:23 | nispace.datasets: Loading data parcellated with 'Yan200'
INFO | 20/07/26 18:24:23 | nispace.datasets: Fetching map info for dataset 'pet'.
The NiSpace "PET" dataset contains a growing collection of nuclear imaging maps from different
source publications. Most maps were originally accessed via neuromaps (https://neuromaps-
main.readthedocs.io/) and can be downloaded directly via neuromaps using the "original" spaces
"MNIOriginal", "fsaverageOriginal", or "fsLROriginal". Maps requested in a defined space
("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR") are sourced from the NiSpace-data
GitHub repo. These maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to
2mm MNI152NLin2009cAsym with a pre-estimated MNI-to-MNI transformation using SynthMorph v4. 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 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!
  - 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
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  5HT1a   [11C]WAY-100635   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT1b   [11C]P943         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT2a   [18F]Altanserin   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT4    [11C]SB207145     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!
  5HT6    [11C]GSK215083    CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.117.206516; https://doi.org/10.1016/j.pscychresns.2019.111007
  5HTT    [11C]DASB         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  A4B2    [18F]Flubatine    CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2016.07.026; https://doi.org/10.1093/ntr/ntx091
  CB1     [11C]OMAR         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
  CMRglu  [18F]FDG          CC BY-NC-SA 4.0 https://doi.org/10.1126/sciadv.adi7632
  COX1    [11C]PS13         CC0 1.0         https://doi.org/10.1007/s00259-020-04855-2; https://doi.org/10.18112/openneuro.ds004401.v1.0.1
  D1      [11C]SCH23390     CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-017-3645-0
  D23     [11C]FLB-457      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
  DAT     [123I]-FP-CIT     CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
   CAVE: SPECT, not PET!
  FDOPA   [18F]DOPA         free            https://doi.org/10.33588/imagendiagnostica.901.2
   CAVE: Unlike other tracers, [18F]DOPA measures AADC activity (dopamine synthesis), not receptor/transporter density
  GABAa   [11C]Flumazenil   CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
  GABAa5  [11C]Ro15-4513    CC BY 4.0       https://doi.org/10.1038/s42003-022-03268-1
  H3      [11C]GSK189254    CC BY-NC-SA 4.0 https://doi.org/10.1177/0271678X16650697; https://doi.org/10.1038/jcbfm.2009.195
  HDAC    [11C]Martinostat  CC0 1.0         https://doi.org/10.1126/scitranslmed.aaf7551
  KOR     [11C]LY2795050    CC BY-NC-SA 4.0 https://doi.org/10.1038/s41386-018-0199-1
  M1      [11C]LSN3172176   CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.120.246967
  mGluR5  [11C]ABP688       CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-018-4252-4
  MOR     [11C]Carfentanil  CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  NET     [11C]MRB          CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-016-3590-3
  NMDA    [18F]GE-179       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!
  rCPS    [11C]Leucine      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
  SV2A    [11C]UCB-J        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
  TSPO    [ 11C]PBR28       MIT             https://doi.org/10.1021/acschemneuro.8b00072; https://doi.org/10.5281/zenodo.1174364
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  VMAT2   [11C]DTBZ         CC0 1.0         https://doi.org/10.18112/openneuro.ds002385.v1.1.0; https://doi.org/10.1038/s41467-020-14693-3
INFO | 20/07/26 18:24:23 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 20/07/26 18:24:23 | nispace.core.parcellation: Building cortex Parcellation for 'Yan200' from library. DOI: 10.1016/j.neuroimage.2023.120010
INFO | 20/07/26 18:24:23 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:24 | nispace.core.parcellation: Parcellation 'Yan200': validation passed.
INFO | 20/07/26 18:24:24 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 20/07/26 18:24:24 | nispace.core.parcellation: Parcellation 'Yan200': active space set to 'MNI152NLin2009cAsym'.
INFO | 20/07/26 18:24:24 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 20/07/26 18:24:24 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:24 | nispace.io: Parcellated data contains nan values!
INFO | 20/07/26 18:24:24 | nispace.api: Got 'x' data for 29 x 200 parcels.
INFO | 20/07/26 18:24:24 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 20/07/26 18:24:24 | nispace.io: Input type: dict, assuming (img_name, img) pairs for imaging data.
INFO | 20/07/26 18:24:24 | nispace.io: Background (bg) handling: background_value='auto'; reporting bg-only parcels: False
INFO | 20/07/26 18:24:24 | nispace.io: Parcellating imaging data.

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

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

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

INFO | 20/07/26 18:24:31 | nispace.api: *** NiSpace.permute() - Estimate exact non-parametric p values. ***
INFO | 20/07/26 18:24:31 | nispace.api: Permutation of: X maps.
INFO | 20/07/26 18:24:31 | nispace.api: Using default null method 'moran' (parcellation null space: 'fsLR').
INFO | 20/07/26 18:24:31 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 20/07/26 18:24:31 | nispace.api: Loading observed colocalizations (method = 'spearman').
INFO | 20/07/26 18:24:31 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 20/07/26 18:24:31 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 200 parcels.
INFO | 20/07/26 18:24:31 | nispace.nulls: Using provided distance matrix/matrices.

Moran null maps (4 proc): 100%|█████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 61.23it/s]

INFO | 20/07/26 18:24:34 | nispace.nulls: Null data generation finished.
INFO | 20/07/26 18:24:34 | nispace.core.permute: Z-standardizing null maps.

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

INFO | 20/07/26 18:24:36 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'upper'}).
INFO | 20/07/26 18:24:36 | nispace.plotting: Significance annotation: 0/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_3_9.png

[4]:

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)

[4]:

		rho	p	q
set	map
Noradrenaline/Acetylcholine	target-VAChT_tracer-feobv_n-18_dx-hc_pub-aghourian2017	0.422783	0.073	0.602089
Opioids/Endocannabinoids	target-KOR_tracer-ly2795050_n-28_dx-hc_pub-vijay2018	0.335397	0.103	0.733256
Histamine	target-H3_tracer-gsk189254_n-8_dx-hc_pub-gallezot2017	0.273213	0.164	0.886693
Glutamate	target-mGluR5_tracer-abp688_n-73_dx-hc_pub-smart2019	0.180214	0.172	0.899194
Noradrenaline/Acetylcholine	target-NET_tracer-mrb_n-10_dx-hc_pub-hesse2017	0.288889	0.255	0.972088
Opioids/Endocannabinoids	target-MOR_tracer-carfentanil_n-204_dx-hc_pub-kantonen2020	0.171576	0.259	0.973856
Serotonin	target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012	0.145715	0.294	0.985482
Dopamine	target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018	0.097589	0.332	0.992590

[5]:

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

INFO | 20/07/26 18:24:37 | nispace.plotting: Significance annotation: 0/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_5_1.png

[5]:

(<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 0x346162970>)

`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?”

[6]:

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 | 20/07/26 18:24:37 | nispace.datasets: Loading enigmathick maps.
INFO | 20/07/26 18:24:37 | 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 | 20/07/26 18:24:37 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 20/07/26 18:24:37 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:24:37 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 20/07/26 18:24:37 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:37 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
INFO | 20/07/26 18:24:37 | nispace.datasets: Fetching map info for dataset 'pet'.
The NiSpace "PET" dataset contains a growing collection of nuclear imaging maps from different
source publications. Most maps were originally accessed via neuromaps (https://neuromaps-
main.readthedocs.io/) and can be downloaded directly via neuromaps using the "original" spaces
"MNIOriginal", "fsaverageOriginal", or "fsLROriginal". Maps requested in a defined space
("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR") are sourced from the NiSpace-data
GitHub repo. These maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to
2mm MNI152NLin2009cAsym with a pre-estimated MNI-to-MNI transformation using SynthMorph v4. 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 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!
  - 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
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  5HT1a   [11C]WAY-100635   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT1b   [11C]P943         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT2a   [18F]Altanserin   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT4    [11C]SB207145     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!
  5HT6    [11C]GSK215083    CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.117.206516; https://doi.org/10.1016/j.pscychresns.2019.111007
  5HTT    [11C]DASB         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  A4B2    [18F]Flubatine    CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2016.07.026; https://doi.org/10.1093/ntr/ntx091
  CB1     [11C]OMAR         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
  CMRglu  [18F]FDG          CC BY-NC-SA 4.0 https://doi.org/10.1126/sciadv.adi7632
  COX1    [11C]PS13         CC0 1.0         https://doi.org/10.1007/s00259-020-04855-2; https://doi.org/10.18112/openneuro.ds004401.v1.0.1
  D1      [11C]SCH23390     CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-017-3645-0
  D23     [11C]FLB-457      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
  DAT     [123I]-FP-CIT     CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
   CAVE: SPECT, not PET!
  FDOPA   [18F]DOPA         free            https://doi.org/10.33588/imagendiagnostica.901.2
   CAVE: Unlike other tracers, [18F]DOPA measures AADC activity (dopamine synthesis), not receptor/transporter density
  GABAa   [11C]Flumazenil   CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
  GABAa5  [11C]Ro15-4513    CC BY 4.0       https://doi.org/10.1038/s42003-022-03268-1
  H3      [11C]GSK189254    CC BY-NC-SA 4.0 https://doi.org/10.1177/0271678X16650697; https://doi.org/10.1038/jcbfm.2009.195
  HDAC    [11C]Martinostat  CC0 1.0         https://doi.org/10.1126/scitranslmed.aaf7551
  KOR     [11C]LY2795050    CC BY-NC-SA 4.0 https://doi.org/10.1038/s41386-018-0199-1
  M1      [11C]LSN3172176   CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.120.246967
  mGluR5  [11C]ABP688       CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-018-4252-4
  MOR     [11C]Carfentanil  CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  NET     [11C]MRB          CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-016-3590-3
  NMDA    [18F]GE-179       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!
  rCPS    [11C]Leucine      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
  SV2A    [11C]UCB-J        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
  TSPO    [ 11C]PBR28       MIT             https://doi.org/10.1021/acschemneuro.8b00072; https://doi.org/10.5281/zenodo.1174364
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  VMAT2   [11C]DTBZ         CC0 1.0         https://doi.org/10.18112/openneuro.ds002385.v1.1.0; https://doi.org/10.1038/s41467-020-14693-3
INFO | 20/07/26 18:24:37 | nispace.core.parcellation: Building cortex Parcellation for 'DesikanKilliany' from library. DOI: 10.1016/j.neuroimage.2006.01.021
INFO | 20/07/26 18:24:37 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:37 | nispace.core.parcellation: Parcellation 'DesikanKilliany': validation passed.
INFO | 20/07/26 18:24:37 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:37 | nispace.io: Parcellated data contains nan values!
INFO | 20/07/26 18:24:37 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:37 | nispace.io: Parcellated data contains nan values!

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

INFO | 20/07/26 18:24:37 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 20/07/26 18:24:37 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 20/07/26 18:24:37 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 68 parcels.
INFO | 20/07/26 18:24:37 | nispace.nulls: Using provided distance matrix/matrices.


Moran null maps (4 proc): 100%|████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 125.00it/s]

INFO | 20/07/26 18:24:38 | nispace.nulls: Null data generation finished.
INFO | 20/07/26 18:24:38 | nispace.core.permute: Z-standardizing null maps.

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

INFO | 20/07/26 18:24:39 | 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 | 20/07/26 18:24:39 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 20/07/26 18:24:39 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:24:39 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 20/07/26 18:24:39 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:39 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
INFO | 20/07/26 18:24:39 | nispace.datasets: Fetching map info for dataset 'pet'.
The NiSpace "PET" dataset contains a growing collection of nuclear imaging maps from different
source publications. Most maps were originally accessed via neuromaps (https://neuromaps-
main.readthedocs.io/) and can be downloaded directly via neuromaps using the "original" spaces
"MNIOriginal", "fsaverageOriginal", or "fsLROriginal". Maps requested in a defined space
("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR") are sourced from the NiSpace-data
GitHub repo. These maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to
2mm MNI152NLin2009cAsym with a pre-estimated MNI-to-MNI transformation using SynthMorph v4. 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 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!
  - 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
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  5HT1a   [11C]WAY-100635   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT1b   [11C]P943         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT2a   [18F]Altanserin   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT4    [11C]SB207145     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!
  5HT6    [11C]GSK215083    CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.117.206516; https://doi.org/10.1016/j.pscychresns.2019.111007
  5HTT    [11C]DASB         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  A4B2    [18F]Flubatine    CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2016.07.026; https://doi.org/10.1093/ntr/ntx091
  CB1     [11C]OMAR         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
  CMRglu  [18F]FDG          CC BY-NC-SA 4.0 https://doi.org/10.1126/sciadv.adi7632
  COX1    [11C]PS13         CC0 1.0         https://doi.org/10.1007/s00259-020-04855-2; https://doi.org/10.18112/openneuro.ds004401.v1.0.1
  D1      [11C]SCH23390     CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-017-3645-0
  D23     [11C]FLB-457      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
  DAT     [123I]-FP-CIT     CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
   CAVE: SPECT, not PET!
  FDOPA   [18F]DOPA         free            https://doi.org/10.33588/imagendiagnostica.901.2
   CAVE: Unlike other tracers, [18F]DOPA measures AADC activity (dopamine synthesis), not receptor/transporter density
  GABAa   [11C]Flumazenil   CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
  GABAa5  [11C]Ro15-4513    CC BY 4.0       https://doi.org/10.1038/s42003-022-03268-1
  H3      [11C]GSK189254    CC BY-NC-SA 4.0 https://doi.org/10.1177/0271678X16650697; https://doi.org/10.1038/jcbfm.2009.195
  HDAC    [11C]Martinostat  CC0 1.0         https://doi.org/10.1126/scitranslmed.aaf7551
  KOR     [11C]LY2795050    CC BY-NC-SA 4.0 https://doi.org/10.1038/s41386-018-0199-1
  M1      [11C]LSN3172176   CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.120.246967
  mGluR5  [11C]ABP688       CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-018-4252-4
  MOR     [11C]Carfentanil  CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  NET     [11C]MRB          CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-016-3590-3
  NMDA    [18F]GE-179       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!
  rCPS    [11C]Leucine      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
  SV2A    [11C]UCB-J        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
  TSPO    [ 11C]PBR28       MIT             https://doi.org/10.1021/acschemneuro.8b00072; https://doi.org/10.5281/zenodo.1174364
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  VMAT2   [11C]DTBZ         CC0 1.0         https://doi.org/10.18112/openneuro.ds002385.v1.1.0; https://doi.org/10.1038/s41467-020-14693-3
INFO | 20/07/26 18:24:39 | nispace.core.parcellation: Building cortex Parcellation for 'DesikanKilliany' from library. DOI: 10.1016/j.neuroimage.2006.01.021
INFO | 20/07/26 18:24:39 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:39 | nispace.core.parcellation: Parcellation 'DesikanKilliany': validation passed.
INFO | 20/07/26 18:24:39 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:39 | nispace.io: Parcellated data contains nan values!
INFO | 20/07/26 18:24:39 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:39 | nispace.io: Parcellated data contains nan values!

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

INFO | 20/07/26 18:24:39 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 20/07/26 18:24:39 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 20/07/26 18:24:39 | nispace.nulls: Null map generation: Assuming n = 29 data vector(s) for n = 68 parcels.
INFO | 20/07/26 18:24:39 | nispace.nulls: Using provided distance matrix/matrices.


Moran null maps (4 proc): 100%|█████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 77.28it/s]

INFO | 20/07/26 18:24:40 | nispace.nulls: Null data generation finished.
INFO | 20/07/26 18:24:40 | nispace.core.permute: Z-standardizing null maps.

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

INFO | 20/07/26 18:24:42 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 20/07/26 18:24:42 | nispace.plotting: Significance annotation: 0/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.

[7]:

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

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

# 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="Yan200",
    comparison_method="hedges(a,b)",
    colocalization_method="spearman",
    n_perm=1000,
    seed=42,
    n_proc=4,
    return_nispace_only=True
)

INFO | 20/07/26 18:24:42 | nispace.datasets: Loading example dataset: 'anorexianervosa', parcellated with: Yan200.
INFO | 20/07/26 18:24:42 | nispace.workflows: Loading integrated pet dataset as X data.
INFO | 20/07/26 18:24:42 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:24:42 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 20/07/26 18:24:42 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:42 | nispace.datasets: Loading data parcellated with 'Yan200'
INFO | 20/07/26 18:24:42 | nispace.datasets: Fetching map info for dataset 'pet'.
The NiSpace "PET" dataset contains a growing collection of nuclear imaging maps from different
source publications. Most maps were originally accessed via neuromaps (https://neuromaps-
main.readthedocs.io/) and can be downloaded directly via neuromaps using the "original" spaces
"MNIOriginal", "fsaverageOriginal", or "fsLROriginal". Maps requested in a defined space
("MNI152NLin2009cAsym", "MNI152NLin6Asym", "fsaverage", or "fsLR") are sourced from the NiSpace-data
GitHub repo. These maps were directly registered to 2mm MNI152NLin6Asym space, and transformed to
2mm MNI152NLin2009cAsym with a pre-estimated MNI-to-MNI transformation using SynthMorph v4. 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 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!
  - 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
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  5HT1a   [11C]WAY-100635   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT1b   [11C]P943         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT2a   [18F]Altanserin   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT4    [11C]SB207145     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!
  5HT6    [11C]GSK215083    CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.117.206516; https://doi.org/10.1016/j.pscychresns.2019.111007
  5HTT    [11C]DASB         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  A4B2    [18F]Flubatine    CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2016.07.026; https://doi.org/10.1093/ntr/ntx091
  CB1     [11C]OMAR         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
  CMRglu  [18F]FDG          CC BY-NC-SA 4.0 https://doi.org/10.1126/sciadv.adi7632
  COX1    [11C]PS13         CC0 1.0         https://doi.org/10.1007/s00259-020-04855-2; https://doi.org/10.18112/openneuro.ds004401.v1.0.1
  D1      [11C]SCH23390     CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-017-3645-0
  D23     [11C]FLB-457      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
  DAT     [123I]-FP-CIT     CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
   CAVE: SPECT, not PET!
  FDOPA   [18F]DOPA         free            https://doi.org/10.33588/imagendiagnostica.901.2
   CAVE: Unlike other tracers, [18F]DOPA measures AADC activity (dopamine synthesis), not receptor/transporter density
  GABAa   [11C]Flumazenil   CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
  GABAa5  [11C]Ro15-4513    CC BY 4.0       https://doi.org/10.1038/s42003-022-03268-1
  H3      [11C]GSK189254    CC BY-NC-SA 4.0 https://doi.org/10.1177/0271678X16650697; https://doi.org/10.1038/jcbfm.2009.195
  HDAC    [11C]Martinostat  CC0 1.0         https://doi.org/10.1126/scitranslmed.aaf7551
  KOR     [11C]LY2795050    CC BY-NC-SA 4.0 https://doi.org/10.1038/s41386-018-0199-1
  M1      [11C]LSN3172176   CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.120.246967
  mGluR5  [11C]ABP688       CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-018-4252-4
  MOR     [11C]Carfentanil  CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  NET     [11C]MRB          CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-016-3590-3
  NMDA    [18F]GE-179       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!
  rCPS    [11C]Leucine      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
  SV2A    [11C]UCB-J        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
  TSPO    [ 11C]PBR28       MIT             https://doi.org/10.1021/acschemneuro.8b00072; https://doi.org/10.5281/zenodo.1174364
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1038/mp.2017.183
  VMAT2   [11C]DTBZ         CC0 1.0         https://doi.org/10.18112/openneuro.ds002385.v1.1.0; https://doi.org/10.1038/s41467-020-14693-3
INFO | 20/07/26 18:24:42 | nispace.core.parcellation: Building cortex Parcellation for 'Yan200' from library. DOI: 10.1016/j.neuroimage.2023.120010
INFO | 20/07/26 18:24:42 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:43 | nispace.core.parcellation: Parcellation 'Yan200': validation passed.
INFO | 20/07/26 18:24:43 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
WARNING | 20/07/26 18:24:43 | nispace.io: Parcellated data contains nan values!
INFO | 20/07/26 18:24:43 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 20/07/26 18:24:43 | nispace.workflows: DataFrame provided for design. Expecting 'groups' and, if paired==True, 'subjects' columns.
INFO | 20/07/26 18:24:43 | nispace.workflows: Design matrix of shape (100, 3). Assuming 100 subjects/maps.
INFO | 20/07/26 18:24:43 | nispace.core.clean_y: Detected categorical covariates: none; continuous: ['age', 'sex'].

../_images/nb_introduction_intro09_workflows_9_1.png

INFO | 20/07/26 18:24:43 | nispace.core.clean_y: Protecting 1 variable(s) during regression: ['groups_HC'].
INFO | 20/07/26 18:24:43 | nispace.core.clean_y: Regressing 2 between covariate(s) from Y, protecting 1 variable(s).

Regressing 2 between covariate(s) from Y (4 proc): 100%|██████████████████████████████| 200/200 [00:02<00:00, 94.86it/s]
Colocalizing (spearman, 4 proc): 100%|██████████████████████████████████████████████████| 1/1 [00:00<00:00, 1644.83it/s]

INFO | 20/07/26 18:24:46 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.


Permuting groups (4 proc): 100%|████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 967990.77it/s]
Null transformations (spearman, 4 proc): 100%|████████████████████████████████████| 1000/1000 [00:00<00:00, 4444.80it/s]
Processing null arrays (4 proc): 100%|████████████████████████████████████████████| 1000/1000 [00:00<00:00, 3759.58it/s]
Null colocalizations (spearman, 4 proc): 100%|███████████████████████████████████| 1000/1000 [00:00<00:00, 13682.64it/s]

INFO | 20/07/26 18:24:46 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 20/07/26 18:24:47 | nispace.plotting: Significance annotation: 13/29 p_uncorrected < 0.05, 6/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_9_7.png

[8]:

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)

[8]:

		rho	p	q
set	map
Serotonin	target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012	-0.288109	0.001	0.012089
Serotonin	target-5HTT_tracer-dasb_n-18_dx-hc_pub-savli2012	-0.261052	0.001	0.012089
Dopamine	target-FDOPA_tracer-fluorodopa_n-12_dx-hc_pub-garciagomez2018	-0.275181	0.002	0.024045
Dopamine	target-D23_tracer-flb457_n-55_dx-hc_pub-sandiego2015	-0.239887	0.004	0.047558
General	target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020	-0.193007	0.004	0.047558
GABA	target-GABAa5_tracer-ro154513_n-10_dx-hc_pub-lukow2022	-0.242692	0.004	0.047558
Dopamine	target-DAT_tracer-fpcit_n-174_dx-hc_pub-dukart2018	-0.180989	0.012	0.136505
Dopamine	target-D1_tracer-sch23390_n-13_dx-hc_pub-kaller2017	-0.176689	0.016	0.178059

[9]:

nsp_gc.plot(sort_by="coloc")

INFO | 20/07/26 18:24:47 | nispace.plotting: Significance annotation: 13/29 p_uncorrected < 0.05, 6/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_11_1.png

[9]:

(<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 0x37f649d00>)

[10]:

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

WARNING | 20/07/26 18:24:47 | nispace.plotting: Brain plotting in NiSpace is experimental. If things look off, feel free to raise a GitHub issue!
INFO | 20/07/26 18:24:47 | nispace.plotting: brainplot: threshold='auto' → 0.0025389466900378466
INFO | 20/07/26 18:24:47 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 20/07/26 18:24:48 | nispace.core.parcellation: Parcellation 'Yan200': active space set to 'MNI152NLin2009cAsym' (was 'fsLR').
INFO | 20/07/26 18:24:48 | 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

[10]:

(<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:

[11]:

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="Yan200",
    colocalization_method="spearman",
    n_perm=1000,
    seed=42,
    n_proc=4,
    return_nispace_only=True
)

INFO | 20/07/26 18:24:51 | nispace.workflows: Loading integrated mrna dataset as X data.
INFO | 20/07/26 18:24:51 | nispace.datasets: Loading mrna maps.
INFO | 20/07/26 18:24:51 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 20/07/26 18:24:51 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:51 | nispace.datasets: Loading data parcellated with 'Yan200'
The NiSpace "mRNA" dataset contains whole-brain gene expression maps for > 10,000 genes based on
parcel-wise mapping. The dataset consists of Allen Brain Atlas mRNA expression data from postmortem
brain tissue of six donors (Hawrylycz et al., 2012), mapped onto MNI or fsaverage parcels using the
abagen toolbox (Markello et al., 2021; abagen.get_expression_data(..., lr_mirror="bidirectional",
norm_matched=False)). Gene stability was assessed using a voxel-level atlas at 8mm isotropic
resolution; genes were retained if their mean donor-to-donor Spearman rank correlation exceeded 0.2.
Please cite the source publications, as well as publications associated with gene set collections as
appropriate.
  - Hawrylycz et al., 2012  https://doi.org/10.1038/nature11405
  - Markello et al., 2021  https://doi.org/10.7554/eLife.72129
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  [CellTypesSilettiSuperclusters] Siletti et al., 2023  https://doi.org/10.1126/science.add7046
INFO | 20/07/26 18:24:52 | nispace.core.parcellation: Building cortex Parcellation for 'Yan200' from library. DOI: 10.1016/j.neuroimage.2023.120010
INFO | 20/07/26 18:24:52 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:53 | nispace.core.parcellation: Parcellation 'Yan200': validation passed.
INFO | 20/07/26 18:24:53 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 20/07/26 18:24:53 | 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, 1845.27it/s]

INFO | 20/07/26 18:24:53 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.
INFO | 20/07/26 18:24:53 | nispace.core.permute: Generating null maps (n = 1000, null_method = 'moran').
INFO | 20/07/26 18:24:53 | nispace.nulls: Null map generation: Assuming n = 1 data vector(s) for n = 200 parcels.
INFO | 20/07/26 18:24:53 | nispace.nulls: Using provided distance matrix/matrices.


Moran null maps (4 proc): 100%|█████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 1952.66it/s]

INFO | 20/07/26 18:24:53 | nispace.nulls: Null data generation finished.


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

INFO | 20/07/26 18:24:54 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).

INFO | 20/07/26 18:24:55 | nispace.plotting: Significance annotation: 0/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_14_9.png

[12]:

nsp_xsea.plot(sort_by="coloc")

INFO | 20/07/26 18:24:55 | nispace.plotting: Significance annotation: 0/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_15_1.png

[12]:

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

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

[13]:

from nispace.workflows import group_xsea

nsp_gxsea = group_xsea(
    y=an_data,
    design=design,
    x="mrna",
    x_collection="CellTypesSilettiSuperclusters",
    parcellation="Yan200",
    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 | 20/07/26 18:24:55 | nispace.workflows: Loading integrated mrna dataset as X data.
INFO | 20/07/26 18:24:55 | nispace.datasets: Loading mrna maps.
INFO | 20/07/26 18:24:55 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 20/07/26 18:24:55 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:24:56 | nispace.datasets: Loading data parcellated with 'Yan200'
The NiSpace "mRNA" dataset contains whole-brain gene expression maps for > 10,000 genes based on
parcel-wise mapping. The dataset consists of Allen Brain Atlas mRNA expression data from postmortem
brain tissue of six donors (Hawrylycz et al., 2012), mapped onto MNI or fsaverage parcels using the
abagen toolbox (Markello et al., 2021; abagen.get_expression_data(..., lr_mirror="bidirectional",
norm_matched=False)). Gene stability was assessed using a voxel-level atlas at 8mm isotropic
resolution; genes were retained if their mean donor-to-donor Spearman rank correlation exceeded 0.2.
Please cite the source publications, as well as publications associated with gene set collections as
appropriate.
  - Hawrylycz et al., 2012  https://doi.org/10.1038/nature11405
  - Markello et al., 2021  https://doi.org/10.7554/eLife.72129
To ensure reproducibility, note the NiSpace version: 0.0.2b2.dev48+g51f21588b.d20260717 (commit: g51f21588b).

  [CellTypesSilettiSuperclusters] Siletti et al., 2023  https://doi.org/10.1126/science.add7046
INFO | 20/07/26 18:24:56 | nispace.core.parcellation: Building cortex Parcellation for 'Yan200' from library. DOI: 10.1016/j.neuroimage.2023.120010
INFO | 20/07/26 18:24:56 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:24:57 | nispace.core.parcellation: Parcellation 'Yan200': validation passed.
INFO | 20/07/26 18:24:57 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 20/07/26 18:24:57 | nispace.io: Input type: DataFrame, assuming parcellated data with shape (n_files/subjects/etc, n_parcels).
INFO | 20/07/26 18:24:57 | nispace.workflows: DataFrame provided for design. Expecting 'groups' and, if paired==True, 'subjects' columns.
INFO | 20/07/26 18:24:57 | nispace.workflows: Design matrix of shape (100, 3). Assuming 100 subjects/maps.
INFO | 20/07/26 18:24:57 | nispace.core.clean_y: Detected categorical covariates: none; continuous: ['age', 'sex'].

../_images/nb_introduction_intro09_workflows_17_1.png

INFO | 20/07/26 18:24:57 | nispace.core.clean_y: Protecting 1 variable(s) during regression: ['groups_HC'].
INFO | 20/07/26 18:24:57 | nispace.core.clean_y: Regressing 2 between covariate(s) from Y, protecting 1 variable(s).

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

INFO | 20/07/26 18:24:57 | nispace.core.parcellation: Lazy-loading parcellation image for space 'fsLR'.


Permuting groups (4 proc): 100%|████████████████████████████████████████████████| 1000/1000 [00:00<00:00, 885808.66it/s]
Null transformations (spearman, 4 proc): 100%|███████████████████████████████████| 1000/1000 [00:00<00:00, 11367.39it/s]
Processing null arrays (4 proc): 100%|████████████████████████████████████████████| 1000/1000 [00:00<00:00, 9074.10it/s]
Null colocalizations (spearman, 4 proc): 100%|████████████████████████████████████| 1000/1000 [00:00<00:00, 2696.32it/s]

INFO | 20/07/26 18:24:58 | nispace.core.permute: Calculating exact p-values (tails = {'rho': 'two'}).
INFO | 20/07/26 18:24:58 | nispace.plotting: Significance annotation: 3/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_17_7.png

INFO | 20/07/26 18:24:59 | nispace.plotting: Significance annotation: 3/29 p_uncorrected < 0.05, 0/29 p_meffgalwey < 0.05

../_images/nb_introduction_intro09_workflows_17_9.png

[13]:

(<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 0x3c15192e0>)

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="Yan200",
                     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="Yan200", 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="Yan200",
           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="Yan200",
                 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