templates¶

Global MNI brain-space configuration for nltools.

This module manages the default MNI template used by BrainData and related classes when no explicit mask is provided. Set it once (e.g., at the top of a notebook) and all subsequent operations pick it up automatically.

Classes:

Methods:

Modules:

Examples:

Set the global brain space:

    import nltools
    nltools.set_brainspace(template="fmriprep", resolution=2)

Inspect the current configuration:

    cfg = nltools.get_brainspace()
    print(cfg.mask)

Scope a change to a block:

    with nltools.with_brainspace(resolution=1):
        brain = BrainData(...)

Classes¶

BrainSpaceConfig¶

BrainSpaceConfig(template: TemplateName = 'default', resolution: Resolution = 2) -> None

Immutable MNI template configuration.

Attributes:

TemplateMatch¶

TemplateMatch(template: str, resolution: int, mask_path: str, brain_path: str, plot_path: str, match_distance: float) -> None

Result of matching a data affine to a template.

Attributes:

Methods¶

fetch_resource¶

fetch_resource(relpath: str) -> str

Return a local path to a file from the nltools/niftis HF dataset.

Parameters:

Returns:

get_bg_image¶

get_bg_image(affine: np.ndarray, img_type: str = 'brain', config: BrainSpaceConfig | None = None) -> str

Get a background image path matching a data resolution.

Uses config (or the current global brain space) and finds the matching resolution from the affine. Used by plotting functions to pick an appropriate background anatomical.

Parameters:

Returns:

get_brainspace¶

get_brainspace() -> BrainSpaceConfig

Return the current global brain-space configuration.

is_standard_space¶

is_standard_space(affine: np.ndarray, *, config: BrainSpaceConfig | None = None) -> tuple[bool, str | None]

Check whether an affine is compatible with our MNI templates.

A “standard space” affine has isotropic voxels at one of the supported template resolutions (the union of SUPPORTED_RESOLUTIONS). Plotting surfaces (glass brain, flatmap, surface montage) and template-driven background lookup all assume this — non-isotropic or off-grid data would render in misleading positions.

Parameters:

Returns:

list_resources¶

list_resources(prefix: str | None = None) -> list[str]

List files available in the nltools/niftis HF dataset.

Companion to fetch_resource — surfaces what’s downloadable without forcing users to remember relpath strings or visit the HF web UI.

Parameters:

Returns:

match_resolution¶

match_resolution(affine: np.ndarray, prefer_exact: bool = True, warn_resample: bool = True) -> TemplateMatch

Find the best matching template for a given affine matrix.

Searches available templates by priority and returns the one whose resolution most closely matches the data’s voxel size.

Parameters:

Returns:

reset_brainspace¶

reset_brainspace() -> BrainSpaceConfig

Reset the global brain-space configuration to defaults.

resolve_paths¶

resolve_paths(template: str, resolution: int) -> dict[str, str]

Build mask/brain/plot paths for a template + resolution.

Parameters:

Returns:

resolve_template_name¶

resolve_template_name(template_name: str, file_type: str = 'mask') -> str

Resolve a template name string to a file path.

Supports names of the form '{res}mm-MNI152-2009{version}'.

Parameters:

Returns:

set_brainspace¶

set_brainspace(template: TemplateName | None = None, resolution: Resolution | None = None) -> BrainSpaceConfig

Set the global brain-space configuration.

Call with no arguments to return the current config without mutating it. Call with one or both arguments to mutate the global state; unspecified fields retain their current value.

Parameters:

Returns:

with_brainspace¶

with_brainspace(template: TemplateName | None = None, resolution: Resolution | None = None) -> Iterator[BrainSpaceConfig]

Temporarily change the global brain-space configuration.

Restores the previous configuration on exit, even if an exception is raised inside the block.

Parameters:

Yields:

Modules¶

config¶

Global brain-space configuration: frozen dataclass + set/get/with API.

Classes:

Methods:

Classes¶

BrainSpaceConfig¶

BrainSpaceConfig(template: TemplateName = 'default', resolution: Resolution = 2) -> None

Immutable MNI template configuration.

Attributes:

####### Attributes##

brain¶

brain: str

Path to the brain-extracted image.

######## mask

mask: str

Path to the brain mask file.

######## plot

plot: str

Path to the full T1 image used for plotting.

######## resolution

resolution: Resolution = 2

######## template

template: TemplateName = 'default'

Methods¶

get_brainspace¶

get_brainspace() -> BrainSpaceConfig

Return the current global brain-space configuration.

reset_brainspace¶

reset_brainspace() -> BrainSpaceConfig

Reset the global brain-space configuration to defaults.

set_brainspace¶

set_brainspace(template: TemplateName | None = None, resolution: Resolution | None = None) -> BrainSpaceConfig

Set the global brain-space configuration.

Call with no arguments to return the current config without mutating it. Call with one or both arguments to mutate the global state; unspecified fields retain their current value.

Parameters:

Returns:

with_brainspace¶

with_brainspace(template: TemplateName | None = None, resolution: Resolution | None = None) -> Iterator[BrainSpaceConfig]

Temporarily change the global brain-space configuration.

Restores the previous configuration on exit, even if an exception is raised inside the block.

Parameters:

Yields:

fetch¶

Lazy fetcher for files hosted in the nltools/niftis HF dataset.

Covers MNI templates, parcellation label maps, the parcel-names CSV, and any other resources living under huggingface.co/datasets/nltools/niftis. First call for a given file downloads it into the local HF cache (~/.cache/huggingface/hub by default); subsequent calls return the cached path without touching the network.

Attributes:

Methods:

Methods¶

fetch_resource¶

fetch_resource(relpath: str) -> str

Return a local path to a file from the nltools/niftis HF dataset.

Parameters:

Returns:

list_resources¶

list_resources(prefix: str | None = None) -> list[str]

List files available in the nltools/niftis HF dataset.

Companion to fetch_resource — surfaces what’s downloadable without forcing users to remember relpath strings or visit the HF web UI.

Parameters:

Returns:

matching¶

Affine-based template matching and background-image selection.

Classes:

Methods:

Classes¶

TemplateMatch¶

TemplateMatch(template: str, resolution: int, mask_path: str, brain_path: str, plot_path: str, match_distance: float) -> None

Result of matching a data affine to a template.

Attributes:

####### Attributes##

brain_path¶

brain_path: str

######## mask_path

mask_path: str

######## match_distance

match_distance: float

######## plot_path

plot_path: str

######## resolution

resolution: int

######## template

template: str

Methods¶

detect_resolution¶

detect_resolution(affine: np.ndarray) -> tuple[float, bool]

Detect voxel resolution (mm) and isotropy from a NIfTI affine.

Voxels are treated as isotropic when the per-axis sizes agree to within three decimals. The reported resolution is that shared isotropic size, or the mean of the per-axis sizes when non-isotropic.

Parameters:

Returns:

get_bg_image¶

get_bg_image(affine: np.ndarray, img_type: str = 'brain', config: BrainSpaceConfig | None = None) -> str

Get a background image path matching a data resolution.

Uses config (or the current global brain space) and finds the matching resolution from the affine. Used by plotting functions to pick an appropriate background anatomical.

Parameters:

Returns:

is_standard_space¶

is_standard_space(affine: np.ndarray, *, config: BrainSpaceConfig | None = None) -> tuple[bool, str | None]

Check whether an affine is compatible with our MNI templates.

A “standard space” affine has isotropic voxels at one of the supported template resolutions (the union of SUPPORTED_RESOLUTIONS). Plotting surfaces (glass brain, flatmap, surface montage) and template-driven background lookup all assume this — non-isotropic or off-grid data would render in misleading positions.

Parameters:

Returns:

match_resolution¶

match_resolution(affine: np.ndarray, prefer_exact: bool = True, warn_resample: bool = True) -> TemplateMatch

Find the best matching template for a given affine matrix.

Searches available templates by priority and returns the one whose resolution most closely matches the data’s voxel size.

Parameters:

Returns:

paths¶

Pure path-resolution helpers for MNI template files.

Resolves logical (template, resolution, file_type) tuples to local paths. Files are fetched on first use from the nltools/niftis HF dataset; see nltools.templates.fetch.

Methods:

Methods¶

resolve_paths¶

resolve_paths(template: str, resolution: int) -> dict[str, str]

Build mask/brain/plot paths for a template + resolution.

Parameters:

Returns:

resolve_template_name¶

resolve_template_name(template_name: str, file_type: str = 'mask') -> str

Resolve a template name string to a file path.

Supports names of the form '{res}mm-MNI152-2009{version}'.

Parameters:

Returns:

registry¶

Static registry of supported MNI templates.

Attributes: