`atlases`¶

Atlas registry, lazy loading, and coordinate labeling.

Atlases are hosted at huggingface.co/datasets/nltools/niftis under atlases/ and fetched on first use via fetch_resource. Cached locally afterwards.

The labeling logic was adapted from atlasreader (BSD-3-Clause). Cite:

Notter et al. (2019). AtlasReader. JOSS 4(34), 1257. Notter et al. (2019)

Attributes:

Name	Type	Description
`ATLASES`	`dict [ str , AtlasMetadata ]`
`AtlasKind`
`DEFAULT_ATLASES`	`tuple [ str , ...]`

Classes:

Name	Description
`Atlas`	A loaded atlas — image, labels, and metadata.
`AtlasMetadata`	Static description of a registered atlas.
`ClusterReport`	Result of `BrainData.cluster_report`.

Methods:

Name	Description
`cluster_report_data`	Compute cluster report DataFrames + thresholded BrainData.
`label_coords`	Look up anatomical labels for a set of MNI mm coordinates.
`list_atlases`	Return the sorted list of registered atlas names.
`load_atlas`	Lazy-load an atlas by registry name.

Modules:

Name	Description
`labeling`	Coordinate-level atlas labeling.
`loading`	Lazy loading of atlas NIfTI + label CSV files from the HF dataset.
`registry`	Static registry of atlases hosted at `nltools/niftis/atlases`.
`reporting`	Cluster reports — peak/cluster geometry plus atlas labels.

Classes¶

`Atlas`¶

Atlas(name: str, image: nb.Nifti1Image, labels: pl.DataFrame, kind: AtlasKind, citation: str) -> None

A loaded atlas — image, labels, and metadata.

Constructed by load_atlas; users normally don’t instantiate directly.

Attributes:

Name	Type	Description
`name`	`str`	Registry key (e.g. `"harvard_oxford"`).
`image`	`Nifti1Image`	NIfTI volume. 3D for deterministic atlases, 4D for probabilistic ones (last axis indexes regions).
`labels`	`DataFrame`	Two-column `index, name` table. For deterministic atlases `index` is the integer voxel value; for probabilistic atlases `index` is the region index along the 4th dim of `image`.
`kind`	`AtlasKind`	`"deterministic"` or `"probabilistic"`.
`citation`	`str`	Short citation for the original atlas.

`AtlasMetadata`¶

AtlasMetadata(kind: AtlasKind, citation: str) -> None

Static description of a registered atlas.

Attributes:

Name	Type	Description
`kind`	`AtlasKind`	`"deterministic"` (3D integer-labeled) or `"probabilistic"` (4D, last axis indexes regions).
`citation`	`str`	Short citation string for the original atlas.

`ClusterReport`¶

ClusterReport(peaks: pl.DataFrame, clusters: pl.DataFrame, stat_img: BrainData) -> None

Result of BrainData.cluster_report.

Attributes:

Name	Type	Description
`peaks`	`DataFrame`	Polars DataFrame, one row per peak (incl. sub-peaks). Columns `cluster_id`, `x`, `y`, `z` (mm), `peak_stat`, `volume_mm3`, `n_voxels`, then one Utf8 column per atlas. `cluster_id` shares the integer id space of `clusters` (they are joinable); sub-peaks carry their parent cluster’s id.
`clusters`	`DataFrame`	Polars DataFrame, one row per cluster. Columns `cluster_id`, `peak_x`, `peak_y`, `peak_z`, `mean_stat`, `volume_mm3`, `n_voxels`, then one Utf8 column per atlas (mass-weighted top regions).
`stat_img`	`BrainData`	BrainData with the thresholded stat map (sub-cluster voxels and clusters smaller than `cluster_threshold` zeroed).

Methods:

Name	Description
`plot`	Render an overview glass brain + one slice figure per cluster.
`to_csv`	Write `peaks.csv` and `clusters.csv` into `output_dir`.

Methods¶

`plot`¶

plot(*, output_dir: str | Path | None = None) -> list[tuple[str, Figure]] | None

Render an overview glass brain + one slice figure per cluster.

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path \| None`	If given, save `overview.png` and `cluster_NN.png` files into the directory and return `None`. If omitted, return a list of `(label, matplotlib.figure.Figure)` tuples without writing to disk.	`None`

Returns:

Type	Description
`list [ tuple [ str , Figure ]] \| None`	`None` when `output_dir` is set, else a list of
`list [ tuple [ str , Figure ]] \| None`	`(label, figure)` tuples.

`to_csv`¶

to_csv(output_dir: str | Path) -> None

Write peaks.csv and clusters.csv into output_dir.

Methods¶

`cluster_report_data`¶

cluster_report_data(bd: BrainData, *, stat_threshold: float | None = 3.0, cluster_threshold: int = 10, two_sided: bool = True, min_distance: float = 8.0, atlas: str | Sequence[str] = DEFAULT_ATLASES, prob_threshold: float = 5.0) -> tuple[pl.DataFrame, pl.DataFrame, BrainData]

Compute cluster report DataFrames + thresholded BrainData.

Pure function — the BrainData facade BrainData.cluster_report wraps the result in a ClusterReport.

Parameters:

Name	Type	Description	Default
`bd`	`BrainData`	BrainData with a 3D stat map (single sample).	required
`stat_threshold`	`float \| None`	Voxel-level threshold. `None` means treat `bd` as already thresholded (skip voxel filtering, keep all non-zero voxels).	`3.0`
`cluster_threshold`	`int`	Minimum cluster size in voxels.	`10`
`two_sided`	`bool`	Report negative clusters as separate clusters.	`True`
`min_distance`	`float`	Minimum distance (mm) between sub-peaks. Passed to `get_clusters_table`.	`8.0`
`atlas`	`str \| Sequence [ str ]`	Atlas name or list of names from `list_atlases`.	`DEFAULT_ATLASES`
`prob_threshold`	`float`	Drop probabilistic-atlas regions below this %.	`5.0`

Returns:

Type	Description
`tuple [ DataFrame , DataFrame , BrainData ]`	Tuple `(peaks, clusters, thresholded_bd)`.

`label_coords`¶

label_coords(coords: CoordsLike, *, atlas: str | Sequence[str] = 'harvard_oxford', prob_threshold: float = 5.0) -> pl.DataFrame

Look up anatomical labels for a set of MNI mm coordinates.

For each coordinate, returns the atlas region(s) it falls in. Works for both deterministic atlases (single label per coord) and probabilistic atlases (formatted "42.0% Foo; 18.0% Bar" strings, sorted by descending probability).

Parameters:

Name	Type	Description	Default
`coords`	`CoordsLike`	`(N, 3)` array-like of MNI mm coordinates `(x, y, z)`. A single coord like `(-42, -22, 56)` is also accepted.	required
`atlas`	`str \| Sequence [ str ]`	Atlas name or list of names from `list_atlases`. One column is added to the output per atlas.	`‘harvard_oxford’`
`prob_threshold`	`float`	For probabilistic atlases only — drop regions with probability (in percent units) below this threshold.	`5.0`

Returns:

Type	Description
`DataFrame`	Polars DataFrame with columns `x`, `y`, `z` plus one
`DataFrame`	column per atlas. All atlas columns are `Utf8`.

`list_atlases`¶

list_atlases() -> list[str]

Return the sorted list of registered atlas names.

Returns:

Type	Description
`list [ str ]`	Sorted list of atlas names usable with
`list [ str ]`	`load_atlas`.

`load_atlas`¶

load_atlas(name: str) -> Atlas

Lazy-load an atlas by registry name.

First call fetches the NIfTI + label CSV from huggingface.co/datasets/nltools/niftis (cached locally afterwards). Subsequent calls in the same process are memoized.

Parameters:

Name	Type	Description	Default
`name`	`str`	Atlas key from `list_atlases`.	required

Returns:

Type	Description
`Atlas`	An `Atlas` with image, labels, and metadata loaded.

Modules¶

`labeling`¶

Coordinate-level atlas labeling.

Adapted from atlasreader (BSD-3-Clause). Cite:

Notter et al. (2019). AtlasReader. JOSS 4(34), 1257.

Attributes:

Name	Type	Description
`CoordsLike`

Methods:

Name	Description
`label_coords`	Look up anatomical labels for a set of MNI mm coordinates.

Classes¶

Methods¶

`label_coords`¶

label_coords(coords: CoordsLike, *, atlas: str | Sequence[str] = 'harvard_oxford', prob_threshold: float = 5.0) -> pl.DataFrame

Look up anatomical labels for a set of MNI mm coordinates.

Parameters:

Name	Type	Description	Default
`coords`	`CoordsLike`	`(N, 3)` array-like of MNI mm coordinates `(x, y, z)`. A single coord like `(-42, -22, 56)` is also accepted.	required
`atlas`	`str \| Sequence [ str ]`	Atlas name or list of names from `list_atlases`. One column is added to the output per atlas.	`‘harvard_oxford’`
`prob_threshold`	`float`	For probabilistic atlases only — drop regions with probability (in percent units) below this threshold.	`5.0`

Returns:

Type	Description
`DataFrame`	Polars DataFrame with columns `x`, `y`, `z` plus one
`DataFrame`	column per atlas. All atlas columns are `Utf8`.

`loading`¶

Lazy loading of atlas NIfTI + label CSV files from the HF dataset.

Classes:

Name	Description
`Atlas`	A loaded atlas — image, labels, and metadata.

Methods:

Name	Description
`load_atlas`	Lazy-load an atlas by registry name.

Classes¶

`Atlas`¶

Atlas(name: str, image: nb.Nifti1Image, labels: pl.DataFrame, kind: AtlasKind, citation: str) -> None

A loaded atlas — image, labels, and metadata.

Constructed by load_atlas; users normally don’t instantiate directly.

Attributes:

Name	Type	Description
`name`	`str`	Registry key (e.g. `"harvard_oxford"`).
`image`	`Nifti1Image`	NIfTI volume. 3D for deterministic atlases, 4D for probabilistic ones (last axis indexes regions).
`labels`	`DataFrame`	Two-column `index, name` table. For deterministic atlases `index` is the integer voxel value; for probabilistic atlases `index` is the region index along the 4th dim of `image`.
`kind`	`AtlasKind`	`"deterministic"` or `"probabilistic"`.
`citation`	`str`	Short citation for the original atlas.

####### Attributes##

`citation`¶

citation: str

######## image

image: nb.Nifti1Image

######## kind

kind: AtlasKind

######## labels

labels: pl.DataFrame

######## name

name: str

Methods¶

`load_atlas`¶

load_atlas(name: str) -> Atlas

Lazy-load an atlas by registry name.

First call fetches the NIfTI + label CSV from huggingface.co/datasets/nltools/niftis (cached locally afterwards). Subsequent calls in the same process are memoized.

Parameters:

Name	Type	Description	Default
`name`	`str`	Atlas key from `list_atlases`.	required

Returns:

Type	Description
`Atlas`	An `Atlas` with image, labels, and metadata loaded.

`registry`¶

Static registry of atlases hosted at nltools/niftis/atlases.

Each entry describes an atlas’s kind (deterministic vs probabilistic) and the citation users should cite when they use it. The actual NIfTI + label files are fetched lazily by load_atlas via fetch_resource.

Atlases were sourced from atlasreader (BSD-3-Clause) and are subject to their original upstream licenses — see LICENSES.md in the HF dataset.

Attributes:

Name	Type	Description
`ATLASES`	`dict [ str , AtlasMetadata ]`
`AtlasKind`
`DEFAULT_ATLASES`	`tuple [ str , ...]`

Classes:

Name	Description
`AtlasMetadata`	Static description of a registered atlas.

Methods:

Name	Description
`list_atlases`	Return the sorted list of registered atlas names.

Classes¶

`AtlasMetadata`¶

AtlasMetadata(kind: AtlasKind, citation: str) -> None

Static description of a registered atlas.

Attributes:

Name	Type	Description
`kind`	`AtlasKind`	`"deterministic"` (3D integer-labeled) or `"probabilistic"` (4D, last axis indexes regions).
`citation`	`str`	Short citation string for the original atlas.

####### Attributes##

`citation`¶

citation: str

######## kind

kind: AtlasKind

Methods¶

`list_atlases`¶

list_atlases() -> list[str]

Return the sorted list of registered atlas names.

Returns:

Type	Description
`list [ str ]`	Sorted list of atlas names usable with
`list [ str ]`	`load_atlas`.

`reporting`¶

Cluster reports — peak/cluster geometry plus atlas labels.

The peak/sub-peak geometry comes from get_clusters_table; the cluster masks and mass-weighted labels are computed locally so we can attribute every voxel of every cluster to one or more atlases.

Classes:

Name	Description
`ClusterReport`	Result of `BrainData.cluster_report`.

Methods:

Name	Description
`cluster_report_data`	Compute cluster report DataFrames + thresholded BrainData.

Classes¶

`ClusterReport`¶

ClusterReport(peaks: pl.DataFrame, clusters: pl.DataFrame, stat_img: BrainData) -> None

Result of BrainData.cluster_report.

Attributes:

Name	Type	Description
`peaks`	`DataFrame`	Polars DataFrame, one row per peak (incl. sub-peaks). Columns `cluster_id`, `x`, `y`, `z` (mm), `peak_stat`, `volume_mm3`, `n_voxels`, then one Utf8 column per atlas. `cluster_id` shares the integer id space of `clusters` (they are joinable); sub-peaks carry their parent cluster’s id.
`clusters`	`DataFrame`	Polars DataFrame, one row per cluster. Columns `cluster_id`, `peak_x`, `peak_y`, `peak_z`, `mean_stat`, `volume_mm3`, `n_voxels`, then one Utf8 column per atlas (mass-weighted top regions).
`stat_img`	`BrainData`	BrainData with the thresholded stat map (sub-cluster voxels and clusters smaller than `cluster_threshold` zeroed).

Methods:

Name	Description
`plot`	Render an overview glass brain + one slice figure per cluster.
`to_csv`	Write `peaks.csv` and `clusters.csv` into `output_dir`.

####### Attributes##

`clusters`¶

clusters: pl.DataFrame

######## peaks

peaks: pl.DataFrame

######## stat_img

stat_img: BrainData

####### Functions##

`plot`¶

plot(*, output_dir: str | Path | None = None) -> list[tuple[str, Figure]] | None

Render an overview glass brain + one slice figure per cluster.

Parameters:

Name	Type	Description	Default
`output_dir`	`str \| Path \| None`	If given, save `overview.png` and `cluster_NN.png` files into the directory and return `None`. If omitted, return a list of `(label, matplotlib.figure.Figure)` tuples without writing to disk.	`None`

Returns:

Type	Description
`list [ tuple [ str , Figure ]] \| None`	`None` when `output_dir` is set, else a list of
`list [ tuple [ str , Figure ]] \| None`	`(label, figure)` tuples.

######## to_csv

to_csv(output_dir: str | Path) -> None

Write peaks.csv and clusters.csv into output_dir.

Methods¶

`cluster_report_data`¶

cluster_report_data(bd: BrainData, *, stat_threshold: float | None = 3.0, cluster_threshold: int = 10, two_sided: bool = True, min_distance: float = 8.0, atlas: str | Sequence[str] = DEFAULT_ATLASES, prob_threshold: float = 5.0) -> tuple[pl.DataFrame, pl.DataFrame, BrainData]

Compute cluster report DataFrames + thresholded BrainData.

Pure function — the BrainData facade BrainData.cluster_report wraps the result in a ClusterReport.

Parameters:

Name	Type	Description	Default
`bd`	`BrainData`	BrainData with a 3D stat map (single sample).	required
`stat_threshold`	`float \| None`	Voxel-level threshold. `None` means treat `bd` as already thresholded (skip voxel filtering, keep all non-zero voxels).	`3.0`
`cluster_threshold`	`int`	Minimum cluster size in voxels.	`10`
`two_sided`	`bool`	Report negative clusters as separate clusters.	`True`
`min_distance`	`float`	Minimum distance (mm) between sub-peaks. Passed to `get_clusters_table`.	`8.0`
`atlas`	`str \| Sequence [ str ]`	Atlas name or list of names from `list_atlases`.	`DEFAULT_ATLASES`
`prob_threshold`	`float`	Drop probabilistic-atlas regions below this %.	`5.0`

Returns:

Type	Description
`tuple [ DataFrame , DataFrame , BrainData ]`	Tuple `(peaks, clusters, thresholded_bd)`.

References¶

Notter, M., Gale, D., Herholz, P., Markello, R., Notter-Bielser, M.-L., & Whitaker, K. (2019). AtlasReader: A Python package to generate coordinate tables, region labels, and informative figures from statistical MRI images. Journal of Open Source Software, 4(34), 1257. 10.21105/joss.01257

atlases

atlases¶

Classes¶

Atlas¶

AtlasMetadata¶

ClusterReport¶

Methods¶

plot¶

to_csv¶

Methods¶

cluster_report_data¶

label_coords¶

list_atlases¶

load_atlas¶

Modules¶

labeling¶

Classes¶

Methods¶

label_coords¶

loading¶

Classes¶

Atlas¶

citation¶

Methods¶

load_atlas¶

registry¶

Classes¶

AtlasMetadata¶

citation¶

Methods¶

list_atlases¶

reporting¶

Classes¶

ClusterReport¶

clusters¶

plot¶

Methods¶

cluster_report_data¶

`atlases`¶

`Atlas`¶

`AtlasMetadata`¶

`ClusterReport`¶

`plot`¶

`to_csv`¶

`cluster_report_data`¶

`label_coords`¶

`list_atlases`¶

`load_atlas`¶

`labeling`¶

`label_coords`¶

`loading`¶

`Atlas`¶

`citation`¶

`load_atlas`¶

`registry`¶

`AtlasMetadata`¶

`citation`¶

`list_atlases`¶

`reporting`¶

`ClusterReport`¶

`clusters`¶

`plot`¶

`cluster_report_data`¶