Skip to content

loader

lacuna.assets.parcellations.loader

Parcellation loading functions for bundled and user-registered parcellations.

This module provides functions to load parcellations from the registry. Supports both bundled parcellations (shipped with Lacuna) and user-registered custom parcellations.

Examples:

>>> from lacuna.assets.parcellations import load_parcellation
>>>
>>> # Load a bundled parcellation
>>> parcellation = load_parcellation("schaefer2018parcels100networks7")
>>> print(parcellation.image.shape)
>>> print(list(parcellation.labels.keys())[:5])
>>>
>>> # Access metadata
>>> print(parcellation.metadata.space)
>>> print(parcellation.metadata.citation)

Parcellation dataclass

Loaded parcellation with image data, labels, and metadata.

Attributes:

Name Type Description
image Nifti1Image

The parcellation image (3D or 4D for probabilistic parcellations)
labels dict[int, str]

Mapping from region ID to region name
metadata ParcellationMetadata

Parcellation metadata from registry
Source code in src/lacuna/assets/parcellations/loader.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@dataclass
class Parcellation:
    """Loaded parcellation with image data, labels, and metadata.

    Attributes
    ----------
    image : nib.Nifti1Image
        The parcellation image (3D or 4D for probabilistic parcellations)
    labels : dict[int, str]
        Mapping from region ID to region name
    metadata : ParcellationMetadata
        Parcellation metadata from registry
    """

    image: nib.Nifti1Image
    labels: dict[int, str]
    metadata: ParcellationMetadata

load_parcellation(parcellation_name)

Load an parcellation by name from the registry.

Loads bundled parcellations or user-registered custom parcellations.

Parameters:

Name Type Description Default
parcellation_name str

Name of the parcellation from PARCELLATION_REGISTRY

 required

Returns:

Type Description
Parcellation

Loaded parcellation with image, labels, and metadata

Raises:

Type Description
KeyError

If parcellation_name is not in the registry
FileNotFoundError

If parcellation files are not found

Examples:

>>> parcellation = load_parcellation("schaefer2018parcels100networks7")
>>> print(f"Parcellation has {len(parcellation.labels)} regions")
>>> print(f"Space: {parcellation.metadata.space}")
Source code in src/lacuna/assets/parcellations/loader.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def load_parcellation(
    parcellation_name: str,
) -> Parcellation:
    """Load an parcellation by name from the registry.

    Loads bundled parcellations or user-registered custom parcellations.

    Parameters
    ----------
    parcellation_name : str
        Name of the parcellation from PARCELLATION_REGISTRY

    Returns
    -------
    Parcellation
        Loaded parcellation with image, labels, and metadata

    Raises
    ------
    KeyError
        If parcellation_name is not in the registry
    FileNotFoundError
        If parcellation files are not found

    Examples
    --------
    >>> parcellation = load_parcellation("schaefer2018parcels100networks7")
    >>> print(f"Parcellation has {len(parcellation.labels)} regions")
    >>> print(f"Space: {parcellation.metadata.space}")
    """
    # Get metadata from registry
    if parcellation_name not in PARCELLATION_REGISTRY:
        available = list(PARCELLATION_REGISTRY.keys())
        raise KeyError(
            f"Parcellation '{parcellation_name}' not found in registry. "
            f"Available parcellations: {', '.join(available)}"
        )

    metadata = PARCELLATION_REGISTRY[parcellation_name]

    # Determine parcellation directory (bundled or custom)
    # If parcellation_filename is absolute path, use it directly
    # Otherwise, look in bundled parcellations directory
    parcellation_filename_path = Path(metadata.parcellation_filename)
    if parcellation_filename_path.is_absolute():
        parcellation_path = parcellation_filename_path
    else:
        parcellation_path = BUNDLED_PARCELLATIONS_DIR / metadata.parcellation_filename
    if not parcellation_path.exists():
        raise FileNotFoundError(
            f"Parcellation file not found: {parcellation_path}\n"
            f"Expected: {metadata.parcellation_filename}"
        )

    image = nib.load(parcellation_path)

    # Load labels (same logic: absolute or relative to bundled dir)
    labels_filename_path = Path(metadata.labels_filename)
    if labels_filename_path.is_absolute():
        labels_path = labels_filename_path
    else:
        labels_path = BUNDLED_PARCELLATIONS_DIR / metadata.labels_filename
    if not labels_path.exists():
        raise FileNotFoundError(
            f"Labels file not found: {labels_path}\n" f"Expected: {metadata.labels_filename}"
        )

    labels = _load_labels_file(labels_path)

    return Parcellation(image=image, labels=labels, metadata=metadata)