Skip to content

registry

lacuna.assets.connectomes.registry

Connectome metadata classes.

This module defines metadata structures for both structural and functional connectomes used in lesion network mapping.

FunctionalConnectomeMetadata dataclass

Bases: SpatialAssetMetadata

Metadata for a functional connectome (voxel-wise timeseries).

Used for functional lesion network mapping (fLNM). Requires HDF5 file(s) containing whole-brain voxel-wise BOLD timeseries data.

HDF5 structure: - 'timeseries': (n_subjects, n_timepoints, n_voxels) array - 'mask_indices': (3, n_voxels) or (n_voxels, 3) brain mask coordinates - 'mask_affine': (4, 4) affine transformation matrix - 'mask_shape': Tuple as attribute (e.g., (91, 109, 91))

Attributes:

Name Type Description
name str

Unique identifier (e.g., "GSP1000")
space str

Coordinate space (typically "MNI152NLin6Asym")
resolution float

Resolution in mm (typically 2.0 for functional data)
description str

Human-readable description
n_subjects int

Sample size in connectome
modality str

Imaging modality (always "bold")
data_path Path

Path to .h5 file or directory containing batch files
is_batched bool

True if data_path is directory with multiple HDF5 files
Source code in src/lacuna/assets/connectomes/registry.py 
 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
@dataclass(frozen=True)
class FunctionalConnectomeMetadata(SpatialAssetMetadata):
    """Metadata for a functional connectome (voxel-wise timeseries).

    Used for functional lesion network mapping (fLNM). Requires HDF5 file(s)
    containing whole-brain voxel-wise BOLD timeseries data.

    HDF5 structure:
    - 'timeseries': (n_subjects, n_timepoints, n_voxels) array
    - 'mask_indices': (3, n_voxels) or (n_voxels, 3) brain mask coordinates
    - 'mask_affine': (4, 4) affine transformation matrix
    - 'mask_shape': Tuple as attribute (e.g., (91, 109, 91))

    Attributes
    ----------
    name : str
        Unique identifier (e.g., "GSP1000")
    space : str
        Coordinate space (typically "MNI152NLin6Asym")
    resolution : float
        Resolution in mm (typically 2.0 for functional data)
    description : str
        Human-readable description
    n_subjects : int
        Sample size in connectome
    modality : str
        Imaging modality (always "bold")
    data_path : Path
        Path to .h5 file or directory containing batch files
    is_batched : bool
        True if data_path is directory with multiple HDF5 files
    """

    n_subjects: int = 0
    modality: str = "bold"
    data_path: Path | None = None
    is_batched: bool = False

    def __repr__(self) -> str:
        """Concise representation showing only essential fields."""
        return (
            f"FunctionalConnectomeMetadata("
            f"name={self.name!r}, "
            f"space={self.space!r}, "
            f"resolution={self.resolution}, "
            f"n_subjects={self.n_subjects}, "
            f"data_path={self.data_path})"
        )

__repr__()

Concise representation showing only essential fields.

Source code in src/lacuna/assets/connectomes/registry.py 
111
112
113
114
115
116
117
118
119
120
def __repr__(self) -> str:
    """Concise representation showing only essential fields."""
    return (
        f"FunctionalConnectomeMetadata("
        f"name={self.name!r}, "
        f"space={self.space!r}, "
        f"resolution={self.resolution}, "
        f"n_subjects={self.n_subjects}, "
        f"data_path={self.data_path})"
    )

StructuralConnectomeMetadata dataclass

Bases: SpatialAssetMetadata

Metadata for a structural connectome (tractography-based).

Used for structural lesion network mapping (sLNM). Requires: - Tractogram file (.tck format from MRtrix3) - TDI computed on-the-fly during analysis (with optional caching)

Note: Unlike functional connectomes, structural connectomes (tractograms) don't have an inherent voxel resolution - they exist in continuous 3D space. The output resolution is controlled by the StructuralNetworkMapping analysis.

Attributes:

Name Type Description
name str

Unique identifier (e.g., "dTOR985")
space str

Coordinate space (typically "MNI152NLin2009bAsym")
resolution float

Resolution in mm (placeholder value, not used for tractograms)
description str

Human-readable description
modality str

Imaging modality (always "dwi")
tractogram_path Path

Path to .tck streamlines file
template_path Path | None

Optional path to template image defining output grid
Source code in src/lacuna/assets/connectomes/registry.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
@dataclass(frozen=True)
class StructuralConnectomeMetadata(SpatialAssetMetadata):
    """Metadata for a structural connectome (tractography-based).

    Used for structural lesion network mapping (sLNM). Requires:
    - Tractogram file (.tck format from MRtrix3)
    - TDI computed on-the-fly during analysis (with optional caching)

    Note: Unlike functional connectomes, structural connectomes (tractograms)
    don't have an inherent voxel resolution - they exist in continuous 3D space.
    The output resolution is controlled by the StructuralNetworkMapping analysis.

    Attributes
    ----------
    name : str
        Unique identifier (e.g., "dTOR985")
    space : str
        Coordinate space (typically "MNI152NLin2009bAsym")
    resolution : float
        Resolution in mm (placeholder value, not used for tractograms)
    description : str
        Human-readable description
    modality : str
        Imaging modality (always "dwi")
    tractogram_path : Path
        Path to .tck streamlines file
    template_path : Path | None
        Optional path to template image defining output grid
    """

    modality: str = "dwi"
    tractogram_path: Path | None = None
    template_path: Path | None = None

    def __repr__(self) -> str:
        """Concise representation showing only essential fields."""
        return (
            f"StructuralConnectomeMetadata("
            f"name={self.name!r}, "
            f"space={self.space!r}, "
            f"tractogram_path={self.tractogram_path})"
        )

    def validate(self) -> None:
        """Validate space only (tractograms don't have inherent resolution).

        Raises
        ------
        ValueError
            If space is invalid
        """
        from lacuna.core.spaces import SUPPORTED_SPACES

        # Check if space is supported
        if self.space not in SUPPORTED_SPACES:
            raise ValueError(f"Unsupported space: {self.space}. Supported: {SUPPORTED_SPACES}")

__repr__()

Concise representation showing only essential fields.

Source code in src/lacuna/assets/connectomes/registry.py 
49
50
51
52
53
54
55
56
def __repr__(self) -> str:
    """Concise representation showing only essential fields."""
    return (
        f"StructuralConnectomeMetadata("
        f"name={self.name!r}, "
        f"space={self.space!r}, "
        f"tractogram_path={self.tractogram_path})"
    )

validate()

Validate space only (tractograms don't have inherent resolution).

Raises:

Type Description
ValueError

If space is invalid
Source code in src/lacuna/assets/connectomes/registry.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
def validate(self) -> None:
    """Validate space only (tractograms don't have inherent resolution).

    Raises
    ------
    ValueError
        If space is invalid
    """
    from lacuna.core.spaces import SUPPORTED_SPACES

    # Check if space is supported
    if self.space not in SUPPORTED_SPACES:
        raise ValueError(f"Unsupported space: {self.space}. Supported: {SUPPORTED_SPACES}")