brain_deer.surface.atlas¶

Cortical / subcortical parcellations and data->region mapping.

Two responsibilities:

Parse parcellations into a common Parcellation (region names, region integer ids, per-element label array, optional per-region RGB). Supported: FreeSurfer .annot, GIFTI label (.label.gii), NIfTI label volume + LUT.
Map user data onto regions the way yabplot does: - array: strict positional order aligned to the atlas region list. - dict: name-based, partial allowed; unlisted regions become NaN. Then expand per-region values to per-vertex (or per-voxel) via the label array.

All functions are headless (numpy + nibabel only), so mapping logic is unit-tested without VTK/Qt.

Classes¶

Parcellation

A labelling of vertices or voxels into named regions.

Functions¶

`load_annot`(→ Parcellation)	Load a FreeSurfer `.annot` parcellation (per-vertex labels).
`load_gifti_label`(→ Parcellation)	Load a GIFTI label file (`*.label.gii`) as a per-vertex parcellation.
`load_label_volume`(→ Parcellation)	Load a NIfTI integer-label volume as a (voxel-domain) parcellation.
`get_atlas_regions`(→ list[str])	Region names in plotting order (background already excluded).
`map_data_to_regions`(→ numpy.ndarray)	Align user data to `region_names` as a float array (missing -> NaN).
`expand_region_values_to_elements`(→ numpy.ndarray)	Broadcast per-region values (aligned to `parc.region_names`) to per-element.
`region_rgb_to_elements`(→ Optional[numpy.ndarray])	Per-element RGB (0..1) from the parcellation colour table, or None.
`read_region_data`(path)	Read region data from CSV/TSV (name,value dict) or a 1-D .npy/.txt array.
`load_parcellation`(→ Parcellation)	Dispatch a parcellation file by extension (.annot / .label.gii / NIfTI).

Module Contents¶

class brain_deer.surface.atlas.Parcellation¶

A labelling of vertices or voxels into named regions.

labels maps each element (vertex or voxel, flattened) to a region id. region_ids and region_names are aligned and exclude the background (id 0 / ‘unknown’) by default so region_names matches the plotting order. region_rgb (optional, aligned to region_ids) holds baked colours for ‘label’ colouring mode.

brain_deer.surface.atlas.load_annot(path: str, *, drop_background: bool = True) → Parcellation¶: Load a FreeSurfer .annot parcellation (per-vertex labels).

brain_deer.surface.atlas.load_gifti_label(path: str, *, drop_background: bool = True) → Parcellation¶: Load a GIFTI label file (*.label.gii) as a per-vertex parcellation.

brain_deer.surface.atlas.load_label_volume(label_nifti, *, lut: Mapping[int, str] | None = None, lut_rgb: Mapping[int, tuple[int, int, int]] | None = None, drop_background: bool = True) → Parcellation¶

Load a NIfTI integer-label volume as a (voxel-domain) parcellation.

label_nifti may be a nibabel image or a path. lut maps label id -> name; if omitted, regions are named region_<id>.

brain_deer.surface.atlas.get_atlas_regions(parc: Parcellation) → list[str]¶: Region names in plotting order (background already excluded).

brain_deer.surface.atlas.map_data_to_regions(data: DataInput, region_names: Sequence[str]) → numpy.ndarray¶

Align user data to region_names as a float array (missing -> NaN).

Mapping/dict: name-based; only listed regions get values (partial ok). Case-insensitive fallback matching is applied for convenience.
array/sequence: strict positional order; length must match region_names (a length-mismatch is a hard error to avoid silent misalignment).

brain_deer.surface.atlas.expand_region_values_to_elements(parc: Parcellation, region_values: numpy.ndarray) → numpy.ndarray¶

Broadcast per-region values (aligned to parc.region_names) to per-element.

Elements whose region is background or has a NaN value become NaN so the renderer can make them transparent (yabplot-style masking).

brain_deer.surface.atlas.region_rgb_to_elements(parc: Parcellation) → numpy.ndarray | None¶: Per-element RGB (0..1) from the parcellation colour table, or None.

brain_deer.surface.atlas.read_region_data(path: str)¶: Read region data from CSV/TSV (name,value dict) or a 1-D .npy/.txt array.

brain_deer.surface.atlas.load_parcellation(path: str, **kwargs) → Parcellation¶: Dispatch a parcellation file by extension (.annot / .label.gii / NIfTI).