Skip to content

Data Module

Brain Atlas

The Brain Atlas module provides tools and data structures for representing, manipulating, and analyzing brain region information. It serves as a foundational component for working with anatomical brain atlases, enabling users to access region metadata, and collect atlas data into neuroimaging workflows.

Use this module to facilitate research and development tasks that require standardized brain region definitions and mappings.

Tip

The full list of availble brain atlases and templates in the alstk can be fetch using the list_all() method, as seen in the API description below

Note

This module is intended for use with standardized brain atlases and may require adaptation for custom or non-standard datasets. Refer to the official documentation for integration guidelines and best practices.

Data Module API

Brain Atlas Module API

Brain Atlas Class API

BrainAtlas

Source code in asltk/data/brain_atlas/__init__.py 
 12
 13
 14
 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
 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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
class BrainAtlas:

    ATLAS_JSON_PATH = os.path.join(os.path.dirname(__file__))
    # Class-level variable to track API calls
    _last_api_call = None
    _min_call_interval = 2  # Minimum seconds between API calls

    def __init__(self, atlas_name: str = 'MNI2009', resolution: str = '1mm'):
        """
        Initializes the BrainAtlas class with a specified atlas name.
        If no atlas name is provided, it defaults to 'MNI2009'.

        Args:
            atlas_name (str, optional):  The name of the atlas to be used. Defaults to 'MNI2009'.
        """
        self._check_resolution_input(resolution)

        self._chosen_atlas = None
        self._resolution = resolution

        self.set_atlas(atlas_name)

    def set_atlas(self, atlas_name: str):
        """
        Sets the brain atlas to be used for ASLtk operations.
        This method checks if the provided atlas name exists in the available atlas database.
        If found, it loads the corresponding atlas JSON file, downloads the atlas data using the
        URL specified in the JSON (via kagglehub), and updates the atlas data with the local file
        location. The selected atlas data is then stored internally for further use.

        Notes:
        The atlas name should match one of the available atlases in the ASLtk database.
        To see all the available atlases, you can use the `list_atlas` method.

        Args:
            atlas_name (str): The name of the atlas to set. Must match an available atlas.

        Raises:
            ValueError: If the atlas name is not found in the database or if there is an error
                        downloading the atlas data.
        """
        if atlas_name not in self.list_atlas():
            raise ValueError(f'Atlas {atlas_name} not found in the database.')

        atlas_path = os.path.join(self.ATLAS_JSON_PATH, f'{atlas_name}.json')
        with open(atlas_path, 'r') as f:
            atlas_data = json.load(f)

        # Apply rate limiting before API call
        self._respect_rate_limits()

        # Add the current atlas file location in the atlas data
        try:
            path = kagglehub.dataset_download(
                atlas_data.get('dataset_url', None)
            )
            # Update the last API call timestamp after successful download
            BrainAtlas._last_api_call = datetime.now()
        except Exception as e:
            raise ValueError(f'Error downloading the atlas: {e}')

        # Assuming the atlas_data is a dictionary, we can add the path to it
        atlas_data['atlas_file_location'] = path
        # Assuming the atlas data contains a key for T1-weighted and Label image data
        atlas_data['resolution'] = self._resolution
        atlas_data['t1_data'] = os.path.join(path, self._collect_t1(path))
        atlas_data['label_data'] = os.path.join(
            path, self._collect_label(path)
        )

        self._chosen_atlas = atlas_data

    def get_atlas(self):
        """
        Get the current brain atlas data.

        Returns:
            dict: The current atlas data.
        """
        return self._chosen_atlas

    def set_resolution(self, resolution: str):
        self._check_resolution_input(resolution)
        self._resolution = resolution

    def get_resolution(self):
        return self._resolution

    def get_atlas_url(self, atlas_name: str):
        """
        Get the brain atlas URL of the chosen format in the ASLtk database.
        The atlas URL is the base Kaggle URL where the atlas is stored.


        Notes:
        The `atlas_name` should be the name of the atlas as it is stored in the ASLtk database.
        To check all the available atlases, you can use the `list_atlas` method.

        Args:
            atlas_name (str): The name of the atlas to retrieve the URL for.

        Raises:
            ValueError: If the atlas name is not found in the database.

        Returns:
            str: The Kaggle dataset URL of the atlas if it exists, otherwise None.
        """
        if atlas_name not in self.list_atlas():
            raise ValueError(f'Atlas {atlas_name} not found in the database.')

        try:
            atlas_url = self._chosen_atlas.get('dataset_url', None)
        except AttributeError:
            raise ValueError(
                f'Atlas {atlas_name} is not set or does not have a dataset URL.'
            )

        return atlas_url

    def get_atlas_labels(self):
        """
        Get the labels of the chosen brain atlas.
        This method retrieves the labels associated with the current atlas.
        Notes:
        The labels are typically used for parcellation or segmentation tasks in brain imaging.

        Returns:
            dict: The labels of the current atlas if available, otherwise None.
        """
        return self._chosen_atlas.get('labels', None)

    def list_atlas(self):
        """
        List all the available brain atlases in the ASLtk database.
        The atlas names are derived from the JSON files stored in the `ATLAS_JSON_PATH`.

        The JSON names should follow the format `<atlas_name>.json`.
        The atlas names are returned without the `.json` extension.

        Returns:
            list(str): List of atlas names available in the ASLtk database.
        """
        return [
            f[:-5]
            for f in os.listdir(self.ATLAS_JSON_PATH)
            if f.endswith('.json')
        ]

    def _collect_t1(self, path: str):  # pragma: no cover
        """
        Collect the T1-weighted image data from the atlas directory.
        Args:
            path (str): The path to the atlas directory.
        Returns:
            str: The filename of the T1-weighted image data.
        """
        t1_file = next(
            (f for f in os.listdir(path) if self._resolution + '_t1' in f),
            None,
        )
        if t1_file is None:
            raise ValueError(
                f"No file with '_t1_' and resolution {self._resolution} found in the atlas directory: {path}"
            )

        return t1_file

    def _collect_label(self, path: str):   # pragma: no cover
        """
        Collect the label file from the atlas directory.
        Args:
            path (str): The path to the atlas directory.
        Returns:
            str: The filename of the label file.
        """
        label_file = next(
            (f for f in os.listdir(path) if self._resolution + '_label' in f),
            None,
        )
        if label_file is None:
            raise ValueError(
                f"No file with '_label' and resolution {self._resolution} found in the atlas directory: {path}"
            )

        return label_file

    def _check_resolution_input(self, resolution):
        valid_resolutions = ['1mm', '2mm']
        if resolution not in valid_resolutions:
            raise ValueError(
                f"Invalid resolution '{resolution}'. Valid options are: {valid_resolutions}"
            )

    @classmethod
    def _respect_rate_limits(cls):
        """
        Ensures API calls respect rate limits by adding delay if necessary.
        This helps prevent 429 Too Many Requests errors.

        The method enforces a minimum interval between consecutive API calls
        by sleeping if the last call was too recent.
        """
        if cls._last_api_call is not None:
            elapsed = (datetime.now() - cls._last_api_call).total_seconds()
            if elapsed < cls._min_call_interval:
                time.sleep(cls._min_call_interval - elapsed)

__init__(atlas_name='MNI2009', resolution='1mm')

Initializes the BrainAtlas class with a specified atlas name. If no atlas name is provided, it defaults to 'MNI2009'.

Parameters:

Name Type Description Default
atlas_name str

The name of the atlas to be used. Defaults to 'MNI2009'.

 'MNI2009'
Source code in asltk/data/brain_atlas/__init__.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def __init__(self, atlas_name: str = 'MNI2009', resolution: str = '1mm'):
    """
    Initializes the BrainAtlas class with a specified atlas name.
    If no atlas name is provided, it defaults to 'MNI2009'.

    Args:
        atlas_name (str, optional):  The name of the atlas to be used. Defaults to 'MNI2009'.
    """
    self._check_resolution_input(resolution)

    self._chosen_atlas = None
    self._resolution = resolution

    self.set_atlas(atlas_name)

get_atlas()

Get the current brain atlas data.

Returns:

Name Type Description
dict

The current atlas data.
Source code in asltk/data/brain_atlas/__init__.py 
84
85
86
87
88
89
90
91
def get_atlas(self):
    """
    Get the current brain atlas data.

    Returns:
        dict: The current atlas data.
    """
    return self._chosen_atlas

get_atlas_labels()

Get the labels of the chosen brain atlas. This method retrieves the labels associated with the current atlas. Notes: The labels are typically used for parcellation or segmentation tasks in brain imaging.

Returns:

Name Type Description
dict

The labels of the current atlas if available, otherwise None.
Source code in asltk/data/brain_atlas/__init__.py 
131
132
133
134
135
136
137
138
139
140
141
def get_atlas_labels(self):
    """
    Get the labels of the chosen brain atlas.
    This method retrieves the labels associated with the current atlas.
    Notes:
    The labels are typically used for parcellation or segmentation tasks in brain imaging.

    Returns:
        dict: The labels of the current atlas if available, otherwise None.
    """
    return self._chosen_atlas.get('labels', None)

get_atlas_url(atlas_name)

Get the brain atlas URL of the chosen format in the ASLtk database. The atlas URL is the base Kaggle URL where the atlas is stored.

Notes: The atlas_name should be the name of the atlas as it is stored in the ASLtk database. To check all the available atlases, you can use the list_atlas method.

Parameters:

Name Type Description Default
atlas_name str

The name of the atlas to retrieve the URL for.

 required

Raises:

Type Description
ValueError

If the atlas name is not found in the database.

Returns:

Name Type Description
str

The Kaggle dataset URL of the atlas if it exists, otherwise None.
Source code in asltk/data/brain_atlas/__init__.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def get_atlas_url(self, atlas_name: str):
    """
    Get the brain atlas URL of the chosen format in the ASLtk database.
    The atlas URL is the base Kaggle URL where the atlas is stored.


    Notes:
    The `atlas_name` should be the name of the atlas as it is stored in the ASLtk database.
    To check all the available atlases, you can use the `list_atlas` method.

    Args:
        atlas_name (str): The name of the atlas to retrieve the URL for.

    Raises:
        ValueError: If the atlas name is not found in the database.

    Returns:
        str: The Kaggle dataset URL of the atlas if it exists, otherwise None.
    """
    if atlas_name not in self.list_atlas():
        raise ValueError(f'Atlas {atlas_name} not found in the database.')

    try:
        atlas_url = self._chosen_atlas.get('dataset_url', None)
    except AttributeError:
        raise ValueError(
            f'Atlas {atlas_name} is not set or does not have a dataset URL.'
        )

    return atlas_url

list_atlas()

List all the available brain atlases in the ASLtk database. The atlas names are derived from the JSON files stored in the ATLAS_JSON_PATH.

The JSON names should follow the format <atlas_name>.json. The atlas names are returned without the .json extension.

Returns:

Name Type Description
list str

List of atlas names available in the ASLtk database.
Source code in asltk/data/brain_atlas/__init__.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def list_atlas(self):
    """
    List all the available brain atlases in the ASLtk database.
    The atlas names are derived from the JSON files stored in the `ATLAS_JSON_PATH`.

    The JSON names should follow the format `<atlas_name>.json`.
    The atlas names are returned without the `.json` extension.

    Returns:
        list(str): List of atlas names available in the ASLtk database.
    """
    return [
        f[:-5]
        for f in os.listdir(self.ATLAS_JSON_PATH)
        if f.endswith('.json')
    ]

set_atlas(atlas_name)

Sets the brain atlas to be used for ASLtk operations. This method checks if the provided atlas name exists in the available atlas database. If found, it loads the corresponding atlas JSON file, downloads the atlas data using the URL specified in the JSON (via kagglehub), and updates the atlas data with the local file location. The selected atlas data is then stored internally for further use.

Notes: The atlas name should match one of the available atlases in the ASLtk database. To see all the available atlases, you can use the list_atlas method.

Parameters:

Name Type Description Default
atlas_name str

The name of the atlas to set. Must match an available atlas.

 required

Raises:

Type Description
ValueError

If the atlas name is not found in the database or if there is an error downloading the atlas data.
Source code in asltk/data/brain_atlas/__init__.py 
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
71
72
73
74
75
76
77
78
79
80
81
82
def set_atlas(self, atlas_name: str):
    """
    Sets the brain atlas to be used for ASLtk operations.
    This method checks if the provided atlas name exists in the available atlas database.
    If found, it loads the corresponding atlas JSON file, downloads the atlas data using the
    URL specified in the JSON (via kagglehub), and updates the atlas data with the local file
    location. The selected atlas data is then stored internally for further use.

    Notes:
    The atlas name should match one of the available atlases in the ASLtk database.
    To see all the available atlases, you can use the `list_atlas` method.

    Args:
        atlas_name (str): The name of the atlas to set. Must match an available atlas.

    Raises:
        ValueError: If the atlas name is not found in the database or if there is an error
                    downloading the atlas data.
    """
    if atlas_name not in self.list_atlas():
        raise ValueError(f'Atlas {atlas_name} not found in the database.')

    atlas_path = os.path.join(self.ATLAS_JSON_PATH, f'{atlas_name}.json')
    with open(atlas_path, 'r') as f:
        atlas_data = json.load(f)

    # Apply rate limiting before API call
    self._respect_rate_limits()

    # Add the current atlas file location in the atlas data
    try:
        path = kagglehub.dataset_download(
            atlas_data.get('dataset_url', None)
        )
        # Update the last API call timestamp after successful download
        BrainAtlas._last_api_call = datetime.now()
    except Exception as e:
        raise ValueError(f'Error downloading the atlas: {e}')

    # Assuming the atlas_data is a dictionary, we can add the path to it
    atlas_data['atlas_file_location'] = path
    # Assuming the atlas data contains a key for T1-weighted and Label image data
    atlas_data['resolution'] = self._resolution
    atlas_data['t1_data'] = os.path.join(path, self._collect_t1(path))
    atlas_data['label_data'] = os.path.join(
        path, self._collect_label(path)
    )

    self._chosen_atlas = atlas_data