atlas
classes.atlas
Runtime helpers for brain atlases and parcellation volumes.
Provides the Atlas wrapper around the LinkML BrainAtlas datamodel, exposing lazy, computed access to the parcellation volume, SANDS terminology, region labels, and region centers. Also defines helpers to build atlas metadata and to produce ranked (relabelled) parcellation volumes from FreeSurfer segmentations.
Attributes
| Name | Description |
|---|---|
| aseg_gm_regions | |
| atlas_data | |
| available_atlases | |
| logger |
Classes
| Name | Description |
|---|---|
| Atlas | BrainAtlas with lazy, computed properties for data files and derived attributes. |
Atlas
classes.atlas.Atlas(atlas=None, **kwargs)BrainAtlas with lazy, computed properties for data files and derived attributes.
Usage mirrors other runtime wrappers (Dynamics, SimulationExperiment): - Construct from a BrainAtlas instance, a string name, or nothing (defaults to ‘wholebrain’). - Access metadata to get a self-reference as a LinkML object. - Access properties: volume, volume_file, metadata_file, region_labels, centers.
SANDS entities are stored in self.terminology.entities — a schema-native dict[ParcellationEntityName, ParcellationEntity] produced by the LinkML loader (the entities slot uses inlined: true in the SANDS schema).
Attributes
| Name | Description |
|---|---|
| centers | Region center coordinates as (N, 3) array. |
| metadata | Return this atlas itself as its LinkML metadata object. |
| metadata_file | Filesystem path to the atlas _dseg.yaml metadata file, or None if not uniquely found. |
| region_labels | Region labels sorted by SANDS lookupLabel. |
| volume | NIfTI image of the atlas parcellation volume. |
| volume_file | Filesystem path to the atlas parcellation volume, or None if not found. |
Methods
| Name | Description |
|---|---|
| create_terminology | Build terminology entities from the atlas volume if not already populated. |
| get_label_by_lookup | Return the region name for a given SANDS lookup label. |
| to_yaml | Serialise the atlas to YAML. |
create_terminology
classes.atlas.Atlas.create_terminology()Build terminology entities from the atlas volume if not already populated.
get_label_by_lookup
classes.atlas.Atlas.get_label_by_lookup(lookup_id)Return the region name for a given SANDS lookup label.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lookup_id | The lookupLabel value to match against the terminology entities. |
required |
Returns
| Name | Type | Description |
|---|---|---|
The matching entity name, or None if no entity has that lookup label. |
to_yaml
classes.atlas.Atlas.to_yaml(fname=None)Serialise the atlas to YAML.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| fname | Optional path to write the YAML to; if omitted, the YAML is returned as a string. | None |
Returns
| Name | Type | Description |
|---|---|---|
The written file path when fname is given, otherwise the YAML string. |
Functions
| Name | Description |
|---|---|
| create_atlas_metadata | Build BrainAtlas metadata and region centers of mass from a parcellation file. |
| rank_atlas | Relabel a parcellation with contiguous rank IDs and write the ranked volume and metadata. |
| tqdm | No-op tqdm fallback used when the package is unavailable. |
create_atlas_metadata
classes.atlas.create_atlas_metadata(fname_atlas, labels='freesurfer')Build BrainAtlas metadata and region centers of mass from a parcellation file.
Parses BIDS entities from the file name to seed a BrainAtlas with its coordinate space and terminology, then computes the center of mass of each non-background label in the parcellation volume.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| fname_atlas | Path to the parcellation NIfTI file to derive metadata from. | required | |
| labels | Reserved for a labelling scheme; currently unused (region labels are read directly from the parcellation volume). | 'freesurfer' |
rank_atlas
classes.atlas.rank_atlas(
fname_atlas,
labels='freesurfer',
desc='ranked',
gm_only=True,
)Relabel a parcellation with contiguous rank IDs and write the ranked volume and metadata.
Remaps each original label to a consecutive integer (1, 2, 3, …), records the mapping as ParcellationEntity metadata (keeping the original lookup label), then saves the ranked NIfTI volume alongside its .yaml metadata using a BIDS-style path with the given desc.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| fname_atlas | Path to the source parcellation NIfTI file. | required | |
| labels | Labelling scheme; "freesurfer" maps indices to region names via the FreeSurfer lookup, otherwise labels is indexed by label id. |
'freesurfer' |
|
| desc | BIDS desc entity used when building the output file path. |
'ranked' |
|
| gm_only | When using FreeSurfer labels, keep only cortical (ctx) and grey-matter subcortical regions, skipping all others. |
True |
Returns
| Name | Type | Description |
|---|---|---|
| The ranked parcellation as a NIfTI image. |
tqdm
classes.atlas.tqdm(x, **kwargs)No-op tqdm fallback used when the package is unavailable.