Data: datasets, parcellations & custom inputs

Before running analyses, you need data. NiSpace ships with no data bundled — everything is downloaded on demand and cached locally. This notebook covers what’s available, how to fetch it, how to use your own data, and how the parcellation system works under the hood.

For a full overview of the integrated datasets, see the Datasets, Parcellations, and Templates pages.

[1]:

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

Fetching reference datasets

NiSpace provides a curated collection of reference brain maps; e.g. PET receptor densities, mRNA gene expression, ENIGMA effect sizes, and many more. Use fetch_reference() to load any of them.

The first call downloads the data; subsequent calls use the local cache.

If you pass a parcellation, you will receive parcellated data. If you do not, you will receive nifti or gifti maps (as defined by the space argument). Some reference datasets are only available for specific spaces, or only in tabulated format for specific parcellations.

Let us first fetch all the included PET maps in MNI152NLin2009cAsym space.

[2]:

from nispace.datasets import fetch_reference

pet_maps = fetch_reference("pet")
print("First two pet maps:")
print(pet_maps[0])
print(pet_maps[1])

INFO | 01/06/26 15:03:16 | nispace.datasets: Loading pet maps.
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-cumi101_n-8_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-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-az10419369_n-36_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-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-5HT1b_tracer-p943_n-65_dx-hc_pub-gallezot2010           Source: Gallezot2010       CC BY-NC-SA 4.0  https://doi.org/10.1038/jcbfm.2009.195, https://doi.org/10.1007/s00213-010-1881-0, https://doi.org/10.1001/archgenpsychiatry.2011.91, https://doi.org/10.1016/j.biopsych.2013.11.022, https://doi.org/10.1016/j.jad.2016.02.021, https://doi.org/10.1007/s00259-014-2958-5, https://doi.org/10.1002/syn.22159
- 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-5HT2a_tracer-cimbi36_n-29_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-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-100_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-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-5HTT_tracer-madam_n-10_dx-hc_pub-fazio2016              Source: Fazio2016          CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2016.03.019
- 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-fmpepd2_n-22_dx-hc_pub-laurikainen2019       Source: Laurikainen2019    CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2018.10.013
- 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-fallypride_n-49_dx-hc_pub-jaworska2020       Source: Jaworska2020       CC BY-NC-SA 4.0  https://doi.org/10.1038/s41386-020-0662-7
- target-D23_tracer-flb457_n-37_dx-hc_pub-smith2017              Source: Smith2017          CC BY-NC-SA 4.0  https://doi.org/10.1177/0271678X17737693
- 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-fepe2i_n-6_dx-hc_pub-sasaki2012              Source: Sasaki2012         CC BY-NC-SA 4.0  https://doi.org/10.2967/jnumed.111.101626
- 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-DAT_tracer-fpcit_n-30_dx-hc_pub-garciagomez2013         Source: Garciagomez2013    free             https://doi.org/10.1016/j.remn.2013.02.009
    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-16_dx-hc_pub-norgaard2021     Source: Norgaard2021       CC BY-NC-SA 4.0  https://doi.org/10.1016/j.neuroimage.2021.117878
    CAVE: Processed in fsaverage space, use  volumetric maps only for subcortex!
- 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-22_dx-hc_pub-rosaneto            Source: Rosaneto           CC BY-NC-SA 4.0  https://doi.org/10.1101/2021.10.28.466336
- target-mGluR5_tracer-abp688_n-28_dx-hc_pub-dubois2015          Source: Dubois2015         CC BY-NC-SA 4.0  https://doi.org/10.1007/s00259-015-3167-6
- 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-MOR_tracer-carfentanil_n-39_dx-hc_pub-turtonen2021      Source: Turtonen2021       CC BY-NC-SA 4.0  https://doi.org/10.1016/j.bpsc.2020.10.013
- 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-NET_tracer-mrb_n-77_dx-hc_pub-ding2010                  Source: Ding2010           CC BY-NC-SA 4.0  https://doi.org/10.1002/syn.20696, https://doi.org/10.1016/j.neuroimage.2013.10.004, https://doi.org/10.1038/s41366-019-0471-4, https://doi.org/10.1210/jc.2017-02717
- 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-VAChT_tracer-feobv_n-4_dx-hc_pub-tuominen               Source: Tuominen           CC BY-NC-SA 4.0  https://doi.org/10.1101/2021.10.28.466336
- target-VAChT_tracer-feobv_n-5_dx-hc_pub-bedard2019             Source: Bedard2019         CC BY-NC-SA 4.0  https://doi.org/10.1016/j.sleep.2018.12.020
- 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

First two pet maps:
/Users/llotter/nispace-data/reference/pet/map/target-5HT1a_tracer-cumi101_n-8_dx-hc_pub-beliveau2017/target-5HT1a_tracer-cumi101_n-8_dx-hc_pub-beliveau2017_space-MNI152NLin2009cAsym.nii.gz
/Users/llotter/nispace-data/reference/pet/map/target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012/target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012_space-MNI152NLin2009cAsym.nii.gz

Let us now pass a parcellation to fetch tabulated data directly:

[3]:

# fetch PET maps in Schaefer200 parcellation
pet_tab = fetch_reference(
    "pet",
    parcellation="Schaefer200",
    print_references=False
)
print(f"PET: {pet_tab.shape[0]} maps x {pet_tab.shape[1]} parcels")
print(f"Index: {pet_tab.index.names}")   # ['set', 'map'] — two-level MultiIndex
print("First two entries:", list(pet_tab.index[:2]))

INFO | 01/06/26 15:03:16 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:03:16 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
PET: 49 maps x 200 parcels
Index: ['map']
First two entries: ['target-5HT1a_tracer-cumi101_n-8_dx-hc_pub-beliveau2017', 'target-5HT1a_tracer-way100635_n-35_dx-hc_pub-savli2012']

We often do not want to fetch all maps; NiSpace provides readymade “collections” of reference datasets, which can be called via the collection argument.

[4]:

# fetch PET maps in Schaefer200 parcellation using the UniqueTracers collection
# -> one map per tracer/target
pet_unique = fetch_reference(
    "pet",
    parcellation="Schaefer200",
    collection="UniqueTracers",
    print_references=False
)
print(f"PET (UniqueTracers): {pet_unique.shape[0]} maps x {pet_unique.shape[1]} parcels")
print(f"Index: {pet_unique.index.names}")   # ['set', 'map'] — two-level MultiIndex
print("First few entries:", list(pet_unique.index[:5]))

INFO | 01/06/26 15:03:16 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:03:16 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:03:16 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:03:16 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
PET (UniqueTracers): 29 maps x 200 parcels
Index: ['set', 'map']
First few entries: [('General', 'target-CMRglu_tracer-fdg_n-20_dx-hc_pub-castrillon2023'), ('General', 'target-rCPS_tracer-leucine_n-42_dx-hc_pub-smith2023'), ('General', 'target-SV2A_tracer-ucbj_n-76_dx-hc_pub-finnema2016'), ('General', 'target-HDAC_tracer-martinostat_n-8_dx-hc_pub-wey2016'), ('General', 'target-VMAT2_tracer-dtbz_n-76_dx-hc_pub-larsen2020')]

The result is a DataFrame with a two-level ['set', 'map'] MultiIndex. The set level groups maps by biological system (e.g. "Serotonin", "Dopamine"); the map level is the individual tracer identifier. This set structure is what X-Set Enrichment Analysis (Notebook 10) operates on.

Collections

A collection is a predefined selection of maps. You pass its name as the collection argument. The index structure you get back depends on how the collection is defined internally:

Scenario	Example	Index
No collection	`fetch_reference("pet")`	Flat `['map']` — all maps, no grouping
Text-file collection	`collection="All"`	Flat `['map']` — a named subset, still no grouping
JSON collection	`collection="UniqueTracers"`	Two-level `['set', 'map']` — maps organized into named groups

A flat index is fine for all standard colocalization analyses. The two-level index is required only if you want to use XSEA (where the set groupings are the unit of analysis).

For PET, "UniqueTracers" is the recommended default: it keeps one representative tracer per receptor to reduce redundancy and groups them by neurotransmitter system. Again, here is what you get without a collection, for comparison:

[5]:

# without a collection: all maps, flat ['map'] index
pet_all = fetch_reference("pet", parcellation="Schaefer200", print_references=False)
print(f"No collection:  {pet_all.shape[0]} maps, index: {pet_all.index.names}")
print(f"UniqueTracers:  {pet_unique.shape[0]} maps, index: {pet_unique.index.names}")

INFO | 01/06/26 15:03:16 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:03:16 | nispace.datasets: Loading data parcellated with 'Schaefer200Parcels7Networks'
No collection:  49 maps, index: ['map']
UniqueTracers:  29 maps, index: ['set', 'map']

[6]:

# two other available reference datasets

# mRNA gene expression (Allen Human Brain Atlas)
mrna = fetch_reference(
    "mrna",
    parcellation="DesikanKilliany",
    collection="CellTypesSilettiSuperclusters",
    print_references=False
)
print(f"mRNA (CellTypesSilettiSuperclusters): {mrna.shape[0]} genes in "
      f"{mrna.index.get_level_values('set').nunique()} cell-type sets x {mrna.shape[1]} parcels")

# ENIGMA cortical thickness effect sizes (Cohen's d, cases vs. controls)
# Note: this is a reference dataset — not example data — but we use it as input in Notebook 11
enigma_thick = fetch_reference(
    "enigmathick",
    parcellation="DesikanKilliany",
    print_references=False
)
print(f"ENIGMA thickness: {enigma_thick.shape[0]} disorders x {enigma_thick.shape[1]} cortical parcels")
print(list(enigma_thick.index))

INFO | 01/06/26 15:03:16 | nispace.datasets: Loading mrna maps.
INFO | 01/06/26 15:03:16 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 01/06/26 15:03:16 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
mRNA (CellTypesSilettiSuperclusters): 613 genes in 29 cell-type sets x 68 parcels
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading enigmathick maps.
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
ENIGMA thickness: 22 disorders x 68 cortical parcels
['dx-mdd_age-adult_pub-schmaal2017', 'dx-mdd_age-adolescent_pub-schmaal2017', 'dx-adhd_age-allages_pub-hoogman2019', 'dx-adhd_age-adult_pub-hoogman2019', 'dx-adhd_age-adolescent_pub-hoogman2019', 'dx-adhd_age-pediatric_pub-hoogman2019', 'dx-asd_pub-vanrooij2018', 'dx-bd_age-adult_pub-hibar2018', 'dx-bd_age-adolescent_pub-hibar2018', 'dx-scz_pub-vanerp2018', 'dx-ocd_age-adult_pub-boedhoe2018', 'dx-ocd_age-pediatric_pub-boedhoe2018', 'dx-epilepsy_pub-whelan2018', 'dx-epilepsy_subtype-gge_pub-whelan2018', 'dx-epilepsy_subtype-ltle_pub-whelan2018', 'dx-epilepsy_subtype-rtle_pub-whelan2018', 'dx-22q_pub-sun2020', 'dx-an_pub-walton2022', 'dx-an_subtype-acAN_pub-walton2022', 'dx-an_subtype-pwrAN_pub-walton2022', 'dx-antisocial_pub-gao2024', 'dx-pd_pub-laansma2021']

Fetching example data

For demos and testing, NiSpace includes the "anorexianervosa" example dataset: parcellated grey matter values for 50 anorexia nervosa patients and 50 healthy controls. We use this throughout the series wherever we need individual-subject data.

Note: This dataset is simulated and not intended for scientific use. The numbers are realistic but fabricated — please do not draw any clinical or scientific conclusions from it.

Group labels are encoded in the subject IDs: sub-XXXAN = patient, sub-XXXHC = healthy control.

[7]:

from nispace.datasets import fetch_example

an_data = fetch_example("anorexianervosa", parcellation="Schaefer200")

print(f"Shape: {an_data.shape}  ({an_data.shape[0]} subjects x {an_data.shape[1]} parcels)")
print("First few IDs:", list(an_data.index[:4]), "...")
print("Last few IDs: ...", list(an_data.index[-4:]))

# extract group labels from the index
import pandas as pd
groups = an_data.index.str.extract(r'(AN|HC)$')[0]
print("\nGroup counts:", groups.value_counts().to_dict())

INFO | 01/06/26 15:03:17 | nispace.datasets: Loading example dataset: 'anorexianervosa', parcellated with: Schaefer200Parcels7Networks.
Shape: (100, 200)  (100 subjects x 200 parcels)
First few IDs: ['sub-001AN', 'sub-002AN', 'sub-003AN', 'sub-004AN'] ...
Last few IDs: ... ['sub-097HC', 'sub-098HC', 'sub-099HC', 'sub-100HC']

Group counts: {'AN': 50, 'HC': 50}

Fetching parcellations

fetch_parcellation() downloads and returns any of NiSpace’s built-in parcellations. The returned object is a multi-space Parcellation instance.

[8]:

from nispace.datasets import fetch_parcellation

parc = fetch_parcellation("Schaefer200")
print(parc)

INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Building multi-space Parcellation for 'Schaefer200Parcels7Networks' from library.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsaverage, fsLR
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': validation passed.
<nispace.core.parcellation.Parcellation object at 0x10360cf40>

The Parcellation concept

You might expect a parcellation to be a single NIfTI file. In NiSpace, it’s a multi-space object — a Parcellation instance that holds representations in all supported coordinate spaces: MNI152 (volumetric, two versions: NLin2009cAsym and NLin6Asym), fsaverage (FreeSurfer surface), and fsLR (HCP surface).

When you pass parcellation="Schaefer200" to NiSpace(), this object is built internally. It automatically detects the space of your input data and uses the right version of the parcellation, resampling as needed. You don’t have to think about this.

If used outside of the NiSpace API, you may need to set the current “active” space explicitely, otherwise some methods will raise errors.

The multi-space design also enables space-aware distance matrices and spin matrices:

Distance matrix: geodesic distances between parcel centroids along the cortical surface. Used by Moran and Burt null models.
Spin matrix: a precomputed set of spatial permutations on the sphere. Used by the Alexander-Bloch spin test.

For standard parcellations, both are precomputed and downloaded automatically. You can also load them manually:

[9]:

# set active space
parc.set_active_space("MNI152NLin2009cAsym")

# geodesic distance matrix between Schaefer200 parcel centroids
dist_mat = parc.get_dist_mat()

print(f"Distance matrix: {dist_mat.shape}  (parcels x parcels, in mm)")

INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7Networks': active space set to 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Lazy-loading dist mat for 'Schaefer200Parcels7Networks' in space 'MNI152NLin2009cAsym'.
Distance matrix: (200, 200)  (parcels x parcels, in mm)

Combined cortex + subcortex parcellations

NiSpace’s built-in atlases are separated by cortex and subcortex to allow for the multi-space approach. As we have done above with cortical atlases, subcortical atlases and data parcellated using these can be directly fetched by the name of the atlas. You can combine a cortical and a subcortical atlas by concatenating their names:

parcellation = "Schaefer200TianS1"   # Schaefer200 cortex + Tian scale 1 subcortex

The same combined string works wherever a parcellation name is accepted: NiSpace(parcellation=...), fetch_reference(parcellation=...), and fetch_parcellation(...). Writing it with a space ("Schaefer200 TianS1") also works.

Available subcortical atlases (refer to the Parcellations page for an up-to-date list):

Name	Regions	Notes
`TianS1`	16	Coarsest; good default for whole-brain analyses
`TianS2`	32	Intermediate
`TianS3`	50	Finest Tian scale
`Aseg`	~40	FreeSurfer automatic subcortical segmentation
`HarvardOxfordSubcortical`	21	Harvard-Oxford subcortical atlas
…

If possible, reference datasets (PET, mRNA, etc) are pre-parcellated with all atlases, including subcortical ones, so fetch_reference() with a combined parcellation just works.

Null models: The spin test requires a spherical cortical surface projection and cannot be applied to combined parcellations. NiSpace automatically selects Moran spectral randomization for combined parcellations — see Notebook 5.

[10]:

# combined parcellation: Schaefer200 cortex + TianS1 subcortex
parc_combined = fetch_parcellation("Schaefer200TianS1")
print(f"Combined: {parc_combined}")

# reference data for the combined parcellation
pet_combined = fetch_reference(
    "pet",
    parcellation="Schaefer200TianS1",
    collection="UniqueTracers",
    print_references=False
)
n_cx = 200  # Schaefer200 cortex parcels
n_total = pet_combined.shape[1]
print(f"\nPET (Schaefer200+TianS1): {pet_combined.shape[0]} maps x {n_total} parcels")
print(f"  → {n_cx} cortex + {n_total - n_cx} subcortex parcels")

INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Building combined Parcellation 'Schaefer200Parcels7Networks+TianS1' from library.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation:   Common MNI space(s) for combined: ['MNI152NLin2009cAsym', 'MNI152NLin6Asym'].
INFO | 01/06/26 15:03:17 | nispace.core.parcellation:   Merging 'Schaefer200Parcels7Networks' and 'TianS1' for space 'MNI152NLin2009cAsym'.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation:   Merging 'Schaefer200Parcels7Networks' and 'TianS1' for space 'MNI152NLin6Asym'.
INFO | 01/06/26 15:03:17 | nispace.core.parcellation:   Fetching cx surface data for 'Schaefer200Parcels7Networks' in 'fsaverage' (for spin tests).
INFO | 01/06/26 15:03:17 | nispace.core.parcellation:   Fetching cx surface data for 'Schaefer200Parcels7Networks' in 'fsLR' (for spin tests).
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Combined parcellation 'Schaefer200Parcels7NetworksTianS1' ready. MNI space(s): ['MNI152NLin2009cAsym', 'MNI152NLin6Asym']. Cx surface space(s) for spins: ['fsaverage', 'fsLR'].
INFO | 01/06/26 15:03:17 | nispace.core.parcellation: Parcellation 'Schaefer200Parcels7NetworksTianS1': validation passed.
Combined: <nispace.core.parcellation.Parcellation object at 0x103480a00>
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading pet maps.
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 01/06/26 15:03:17 | nispace.datasets: Filtering maps by collection.
INFO | 01/06/26 15:03:17 | nispace.datasets: Loading and inner-merging data parcellated with 'Schaefer200Parcels7Networks' and 'TianS1'

PET (Schaefer200+TianS1): 29 maps x 216 parcels
  → 200 cortex + 16 subcortex parcels

Storage and reproducibility

By default, all data lands in ~/nispace-data/. Change this with:

import os
os.environ["NISPACE_DATA_DIR"] = "/your/path"

Every downloaded file is verified against a SHA-256 hash manifest — corrupted or incomplete downloads are detected and re-fetched automatically. See the Data Management page for details on versioning and reproducibility.

Summary

Function / pattern	Purpose
`fetch_reference(dataset, parcellation, collection)`	Load curated reference maps (PET, mRNA, ENIGMA, …)
`fetch_example("anorexianervosa", parcellation)`	Load the group-comparison example dataset
`fetch_parcellation(name)`	Fetch a built-in parcellation as a multi-space object
`parcellation="Schaefer200TianS1"`	Combined cortex + subcortex (TianS1/S2/S3, Aseg, …)
`NiSpace(parcellation=nifti_img)`	Use any NIfTI as a custom parcellation

Next: Notebook 4 shows how to compute group-level effect sizes from individual subject data.

[11]:

from nilearn import datasets as nilearn_datasets
from nispace.io import load_img
from nispace.api import NiSpace

# fetch a standard atlas via nilearn
aal = nilearn_datasets.fetch_atlas_aal()
aal_map = aal.maps
aal_labels = aal.labels[1:] # start with "background"
print(f"AAL atlas: {len(aal.labels)} labels")

# use it directly as a custom parcellation in NiSpace
nsp_custom = NiSpace(
    x=pet_maps[:5], # use the first 5 maps of the PET map data loaded above
    y=load_img("neuroquery/pain.nii.gz"),
    y_labels="Pain",
    parcellation=aal_map,          # custom NIfTI image
    parcellation_labels=aal_labels  # parcel names (optional)
)
nsp_custom.fit()
print(f"Parcellated with Destrieux: {nsp_custom.get_y().shape[1]} parcels")

[fetch_atlas_aal] Dataset found in /Users/llotter/nilearn_data/aal_SPM12
AAL atlas: 117 labels
INFO | 01/06/26 15:03:18 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 01/06/26 15:03:18 | nispace.core.parcellation: Building Parcellation from path / image.
INFO | 01/06/26 15:03:18 | nispace.core.parcellation: Parcellation space: 'MNI152NLin6Asym'.

/var/folders/6n/h4150p8d5gz5kbnqv5_406940000gp/T/ipykernel_28706/3862712985.py:6: DeprecationWarning: Starting in version 0.13, the default fetched mask will beAAL 3v2 instead.
  aal = nilearn_datasets.fetch_atlas_aal()

INFO | 01/06/26 15:03:18 | nispace.core.parcellation: Parcellation 'None': validation passed.
INFO | 01/06/26 15:03:18 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 01/06/26 15:03:18 | nispace.io: Input type: list, assuming imaging data.
INFO | 01/06/26 15:03:18 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:03:18 | nispace.io: Parcellating imaging data.

Parcellating (1 proc): 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 5/5 [00:02<00:00,  2.29it/s]

WARNING | 01/06/26 15:03:20 | nispace.io: Parcellated data contains nan values!
INFO | 01/06/26 15:03:20 | nispace.api: Got 'x' data for 5 x 116 parcels.
INFO | 01/06/26 15:03:20 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 01/06/26 15:03:20 | nispace.io: Input type: list, assuming imaging data.
INFO | 01/06/26 15:03:20 | nispace.io: Background (bg) handling: ignoring bg: True (bg value: ['auto', 0.0]); dropping bg parcels: False
INFO | 01/06/26 15:03:20 | nispace.io: Parcellating imaging data.


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

INFO | 01/06/26 15:03:20 | nispace.api: Got 'y' data for 1 x 116 parcels.
INFO | 01/06/26 15:03:20 | nispace.api: Z-standardizing 'X' data.
INFO | 01/06/26 15:03:20 | nispace.api: Returning Y dataframe:
| Y_TRANSFORM |
| False       | 
Parcellated with Destrieux: 116 parcels

When using a custom parcellation, precomputed spin/distance matrices are not available. NiSpace computes a distance matrix from parcel centroids on the fly when you run permutation tests — this takes a bit longer the first time.

Storage and reproducibility

By default, all data lands in ~/nispace-data/. Change this with:

import os
os.environ["NISPACE_DATA_DIR"] = "/your/path"

Every downloaded file is verified against a SHA-256 hash manifest — corrupted or incomplete downloads are detected and re-fetched automatically. See the Data Management page for details on versioning and reproducibility.

Summary

Function	Purpose
`fetch_reference(dataset, parcellation, collection)`	Load curated reference maps (PET, mRNA, ENIGMA, …)
`fetch_example("anorexianervosa", parcellation)`	Load the group-comparison example dataset
`fetch_parcellation(name)`	Fetch a built-in parcellation as a multi-space object
`NiSpace(parcellation=nifti_img)`	Use any NIfTI as a custom parcellation
`get_distance_matrix(parcellation)`	Load/compute geodesic distance matrix

Next: Notebook 4 shows how to compute group-level effect sizes from individual subject data.