spectralbrain.utils.atlas#

Brain atlas label registries.

Maps atlas label IDs to human-readable region names, hemispheres, network assignments, and canonical colours. Covers the 19 atlases in AtlasScheme.

The two primary use cases are:

  1. Point-cloud extraction: look up label IDs for a structure (get_label_id("aseg", "Left-Hippocampus") → 17).

  2. Geometric connectome: map Schaefer parcels to Yeo networks for block-level aggregation.

Label tables for subcortical atlases (aseg, thalamic nuclei, hippocampal subfields, amygdala nuclei) are embedded. Cortical atlases (Schaefer, DKT, Destrieux) load from FreeSurfer annotation files when available.

Functions

get_label_id(atlas, name)

Reverse lookup: region name → label ID.

get_label_name(atlas, label_id)

Look up the region name for a label ID.

get_structure_ids(atlas[, hemisphere])

Get all label IDs for a hemisphere.

list_labels(atlas)

Return all label ID → name mappings for an atlas.

schaefer_to_yeo(parcel_id[, n_parcels, ...])

Map a Schaefer parcel ID to its Yeo network name.
spectralbrain.utils.atlas.get_label_id(atlas, name)[source]#

Reverse lookup: region name → label ID.

Parameters:

  • atlas (str)

  • name (str) – Region name (case-insensitive substring match).

Returns:

int or None

Return type:

int | None

spectralbrain.utils.atlas.get_label_name(atlas, label_id)[source]#

Look up the region name for a label ID.

Parameters:

  • atlas (str) – Atlas name (e.g. "aseg", "thalamic_nuclei").

  • label_id (int)

Returns:

str – Region name, or "Unknown-{label_id}".

Return type:

str

spectralbrain.utils.atlas.get_structure_ids(atlas, hemisphere='both')[source]#

Get all label IDs for a hemisphere.

Parameters:

  • atlas (str)

  • hemisphere (str)

Returns:

list of int

Return type:

list[int]

spectralbrain.utils.atlas.list_labels(atlas)[source]#

Return all label ID → name mappings for an atlas.

Parameters:

atlas (str)

Returns:

dict

Return type:

dict[int, str]

spectralbrain.utils.atlas.schaefer_to_yeo(parcel_id, n_parcels=200, n_networks=7)[source]#

Map a Schaefer parcel ID to its Yeo network name.

Schaefer parcels encode the network in their naming convention: 7Networks_LH_Vis_1 → “Visual”.

Parameters:

  • parcel_id (int) – 1-indexed Schaefer parcel ID.

  • n_parcels (int) – Total parcels (100, 200, 400, etc.).

  • n_networks (int) – 7 or 17.

Returns:

str – Network name.

Return type:

str

Notes

This is a heuristic based on the standard Schaefer ordering. For exact mapping, load the annotation file and parse names.