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.

[2]:

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 MNI152NLin6Asym space.

[3]:

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 | 20/07/26 18:20:26 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:20:26 | nispace.datasets: Auto-selected space 'MNI152NLin6Asym' for dataset 'pet'.
INFO | 20/07/26 18:20:26 | 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]CUMI-101     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!
  5HT1a   [11C]WAY-100635   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT1b   [11C]AZ10419369   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!
  5HT1b   [11C]P943         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.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
  5HT2a   [18F]Altanserin   CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HT2a   [11C]Cimbi-36     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!
  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.1523/JNEUROSCI.2830-16.2016
   CAVE: Processed in fsaverage space, use volumetric maps only for subcortex!
  5HTT    [11C]DASB         CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2012.07.001
  5HTT    [11C]MADAM        CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2016.03.019
  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     [18F]FMPEP-d2     CC BY-NC-SA 4.0 https://doi.org/10.1016/j.neuroimage.2018.10.013
  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     [18F]Fallypride   CC BY-NC-SA 4.0 https://doi.org/10.1038/s41386-020-0662-7
  D23     [11C]FLB-457      CC BY-NC-SA 4.0 https://doi.org/10.1177/0271678X17737693
  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
  D23     [11C]Raclopride   CC0 1.0         https://doi.org/10.1016/j.neuroimage.2022.119149
  D23     [11C]Raclopride   CC BY-NC-SA 4.0 https://doi.org/10.1038/jcbfm.2015.53
  DAT     [18F]FE-PE2I      CC BY-NC-SA 4.0 https://doi.org/10.2967/jnumed.111.101626
  DAT     [123I]-FP-CIT     CC BY-NC-SA 4.0 https://doi.org/10.1038/s41598-018-22444-0
   CAVE: SPECT, not PET!
  DAT     [123I]-FP-CIT     free            https://doi.org/10.1016/j.remn.2013.02.009
   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.1016/j.neuroimage.2021.117878
   CAVE: Processed in fsaverage space, use volumetric maps only for subcortex!
  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.1101/2021.10.28.466336
  mGluR5  [11C]ABP688       CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-015-3167-6
  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
  MOR     [11C]Carfentanil  CC BY-NC-SA 4.0 https://doi.org/10.1016/j.bpsc.2020.10.013
  NET     [11C]MRB          CC BY-NC-SA 4.0 https://doi.org/10.1007/s00259-016-3590-3
  NET     [11C]MRB          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
  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
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1101/2021.10.28.466336
  VAChT   [18F]FEOBV        CC BY-NC-SA 4.0 https://doi.org/10.1016/j.sleep.2018.12.020
  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
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-MNI152NLin6Asym.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-MNI152NLin6Asym.nii.gz

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

[4]:

# fetch PET maps in Yan200 parcellation
pet_tab = fetch_reference(
    "pet",
    parcellation="Yan200",
    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 | 20/07/26 18:20:26 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading data parcellated with 'Yan200'
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.

[5]:

# fetch PET maps in Yan200 parcellation using the UniqueTracers collection
# -> one map per tracer/target
pet_unique = fetch_reference(
    "pet",
    parcellation="Yan200",
    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 | 20/07/26 18:20:26 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading integrated collection 'UniqueTracers' for dataset 'pet'.
INFO | 20/07/26 18:20:26 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading data parcellated with 'Yan200'
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:

[6]:

# without a collection: all maps, flat ['map'] index
pet_all = fetch_reference("pet", parcellation="Yan200", 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 | 20/07/26 18:20:26 | nispace.datasets: Loading pet maps.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading data parcellated with 'Yan200'
No collection:  49 maps, index: ['map']
UniqueTracers:  29 maps, index: ['set', 'map']

[7]:

# 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 | 20/07/26 18:20:26 | nispace.datasets: Loading mrna maps.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading integrated collection 'CellTypesSilettiSuperclusters' for dataset 'mrna'.
INFO | 20/07/26 18:20:26 | nispace.datasets: Filtering maps by collection.
INFO | 20/07/26 18:20:26 | nispace.datasets: Loading data parcellated with 'DesikanKilliany'
mRNA (CellTypesSilettiSuperclusters): 613 genes in 29 cell-type sets x 68 parcels
INFO | 20/07/26 18:20:27 | nispace.datasets: Loading enigmathick maps.
INFO | 20/07/26 18:20:27 | 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.

[8]:

from nispace.datasets import fetch_example

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

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 | 20/07/26 18:20:27 | nispace.datasets: Loading example dataset: 'anorexianervosa', parcellated with: Yan200.
Updating /Users/llotter/nispace-data/example/example-anorexianervosa_parc-Yan200.csv.gz
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.

[9]:

from nispace.datasets import fetch_parcellation

parc = fetch_parcellation("Yan200")
print(parc)

INFO | 20/07/26 18:20:27 | nispace.core.parcellation: Building cortex Parcellation for 'Yan200' from library. DOI: 10.1016/j.neuroimage.2023.120010
INFO | 20/07/26 18:20:27 | nispace.core.parcellation: Available spaces: MNI152NLin2009cAsym, MNI152NLin6Asym, fsLR, fsaverage
INFO | 20/07/26 18:20:27 | nispace.core.parcellation: Parcellation 'Yan200': validation passed.
<nispace.core.parcellation.Parcellation object at 0x10393e610>

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="Yan200" 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 explicitly, otherwise some methods will raise errors.

Why Yan? Yan et al. (2023) introduced a homotopic extension of the Schaefer parcellation — each left-hemisphere parcel has a mirror counterpart of identical shape on the right. This symmetry property is important for spin-based null model methods (see Notebook 5), which rotate both hemispheres and rely on bilateral correspondence. We use the 17-network Kong variant. NiSpace includes the 100, 200, 400, and 1000 parcel versions. The Parcellations page lists all available parcellations.

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 spin test methods (e.g., "cornblath").

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

[10]:

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

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

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

INFO | 20/07/26 18:20:27 | nispace.core.parcellation: Lazy-loading parcellation image for space 'MNI152NLin2009cAsym'.
INFO | 20/07/26 18:20:28 | nispace.core.parcellation: Parcellation 'Yan200': active space set to 'MNI152NLin2009cAsym'.
INFO | 20/07/26 18:20:28 | nispace.core.parcellation: Lazy-loading dist mat for 'Yan200' 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 using "+" as separator:

parcellation = "Yan200+TianS1"          # string form (canonical)
parcellation = ("Yan200", "TianS1")     # tuple form — also accepted

The same combined syntax works wherever a parcellation name is accepted: NiSpace(parcellation=...), fetch_reference(parcellation=...), and fetch_parcellation(...).

Available subcortical atlases (refer to theParcellationspage for a full list):

Name	Regions	Notes
`TianS1`	16	Coarsest; good default for whole-brain analyses
`TianS2`	32	Intermediate
`TianS3`	50	Finest Tian scale
`Aseg`	16	FreeSurfer automatic subcortical segmentation
`HarvardOxfordSubcortical`	14	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. For a full list of available reference datasets, see the Datasets page.

Null models for combined parcellations: NiSpace uses split Moran spectral randomization (("moran", "moran")) by default — generating null maps independently for the cortical and subcortical components. This is handled automatically. See Notebook 5 for details.

[11]:

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

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

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

PET (Yan200+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="Yan200+TianS1"`	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.

[12]:

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 | 20/07/26 18:20:28 | nispace.api: *** NiSpace.fit() - Data extraction and preparation. ***
INFO | 20/07/26 18:20:28 | nispace.core.parcellation: Building Parcellation from path / image.
INFO | 20/07/26 18:20:28 | nispace.core.parcellation: Parcellation space: 'MNI152NLin6Asym'.

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

INFO | 20/07/26 18:20:28 | nispace.core.parcellation: Parcellation 'None': validation passed.
INFO | 20/07/26 18:20:28 | nispace.api: Checking input data for 'x' (should be, e.g., PET data):
INFO | 20/07/26 18:20:28 | nispace.io: Input type: list, assuming imaging data.
INFO | 20/07/26 18:20:28 | nispace.io: Background (bg) handling: background_value='auto'; reporting bg-only parcels: False
INFO | 20/07/26 18:20:28 | nispace.io: Parcellating imaging data.

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

WARNING | 20/07/26 18:20:30 | nispace.io: Parcellated data contains nan values!
INFO | 20/07/26 18:20:30 | nispace.api: Got 'x' data for 5 x 116 parcels.
INFO | 20/07/26 18:20:30 | nispace.api: Checking input data for 'y' (should be, e.g., subject data):
INFO | 20/07/26 18:20:30 | nispace.io: Input type: list, assuming imaging data.
INFO | 20/07/26 18:20:30 | nispace.io: Background (bg) handling: background_value='auto'; reporting bg-only parcels: False
INFO | 20/07/26 18:20:30 | nispace.io: Parcellating imaging data.


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

INFO | 20/07/26 18:20:30 | nispace.api: Got 'y' data for 1 x 116 parcels.
INFO | 20/07/26 18:20:30 | nispace.api: Z-standardizing 'X' data.
INFO | 20/07/26 18:20:30 | 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.