Skip to content

cuisto.atlas

atlas module, part of cuisto.

Contains functions to generate atlas outlines in sagittal, cornal and horizontal views, with each regions of the Allen Brain Atlas in a single HDF5 file.

check_outlines_file(filename, atlas_name) #

Check if the outline file exists, if not, attempt to download it.

Parameters:

Name Type Description Default
filename str

Full path to the file to check.

 required
atlas_name str

Brainglobe atlas name.

 required

Returns:

Name Type Description
file_not_found bool

True if the file does not exist and could not be downloaded.
Source code in cuisto/atlas.py 
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
def check_outlines_file(filename: str, atlas_name: str) -> bool:
    """
    Check if the outline file exists, if not, attempt to download it.

    Parameters
    ----------
    filename : str
        Full path to the file to check.
    atlas_name : str
        Brainglobe atlas name.

    Returns
    -------
    file_not_found : bool
        True if the file does not exist and could not be downloaded.

    """
    if not filename:
        # empty file name, check the default one
        filename = get_default_filename(atlas_name)

    if not os.path.isfile(filename):
        print("The outlines file does not exist, attempting to download it...")
        result = download_outline(filename, atlas_name)
        if result:
            # :)
            print(f"Outlines file downloaded at {filename}.")
            file_not_found = False
        else:
            # we already said it was not downloaded (not available or request failed)
            file_not_found = True
    else:
        # file exists
        file_not_found = False

    return file_not_found, filename

download_file(url, filename) #

Download a file.

Parameters:

Name Type Description Default
url str

Full URL to address the HTTP request.

 required
filename str

Path to the destination file.

 required

Returns:

Name Type Description
tf bool

True if the file was downloaded, False otherwise.
Source code in cuisto/atlas.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
def download_file(url: str, filename: str) -> bool:
    """
    Download a file.

    Parameters
    ----------
    url : str
        Full URL to address the HTTP request.
    filename : str
        Path to the destination file.

    Returns
    -------
    tf : bool
        True if the file was downloaded, False otherwise.

    """

    response = requests.get(url)
    if response.ok:
        with open(filename, "wb") as fid:
            fid.write(response.content)
        return True
    else:
        print("The outlines file could not be downloaded.")
        return False

download_outline(filename, atlas_name) #

Download outline file if available.

Parameters:

Name Type Description Default
filename str

Full path to the destination file.

 required
atlas_name str

Brainglobe atlas name.

 required

Returns:

Name Type Description
result bool

True if the file was downloaded, False otherwise.
Source code in cuisto/atlas.py 
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
218
219
220
221
222
def download_outline(filename: str, atlas_name: str) -> bool:
    """
    Download outline file if available.

    Parameters
    ----------
    filename : str
        Full path to the destination file.
    atlas_name : str
        Brainglobe atlas name.

    Returns
    -------
    result : bool
        True if the file was downloaded, False otherwise.

    """
    # check the outlines is available
    if atlas_name not in AVAILABLE_ATLAS:
        print(
            f"Unfortunately, the structures outlines for {atlas_name} was not"
            " pre-generated."
        )
        return False

    # check filename
    if not filename:
        # empty filename, set the default one
        filename = get_default_filename(atlas_name)

    # build URL
    url = URL_BASE + atlas_name + "_outlines.h5"
    result = download_file(url, filename)

    return result

generate_outlines(atlas_name, output_file=None) #

Generate brain regions contours outlines from Brainglobe atlases masks.

Parameters:

Name Type Description Default
atlas_name str

Name of Brainglobe atlas.

 required
output_file str

Destination file. If it exists already, nothing is done. If None, the file is created at $HOME/.cuisto/{atlas_name}.h5.

 None
Source code in cuisto/atlas.py 
 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
def generate_outlines(atlas_name: str, output_file: str | None = None):
    """
    Generate brain regions contours outlines from Brainglobe atlases masks.

    Parameters
    ----------
    atlas_name : str
        Name of Brainglobe atlas.
    output_file : str, optional
        Destination file. If it exists already, nothing is done. If None, the file is
        created at $HOME/.cuisto/{atlas_name}.h5.

    """
    if not output_file:
        output_file = get_default_filename(atlas_name)

    if os.path.isfile(output_file):
        print(f"{output_file} already exists, outlines will not be re-generated.")
        return

    atlas = BrainGlobeAtlas(atlas_name)

    with h5py.File(output_file, "w") as f:
        # create groups
        grp_sagittal = f.create_group("sagittal")
        grp_coronal = f.create_group("coronal")
        grp_top = f.create_group("top")

        # loop through structures
        pbar = tqdm(atlas.structures_list)
        for structure in pbar:
            pbar.set_description(structure["acronym"])

            mask = atlas.get_structure_mask(structure["id"])

            # sagittal
            outlines = get_structure_contour(mask, axis=2)
            res = atlas.resolution[1], atlas.resolution[0]  # d-v, r-c
            outlines_to_group(
                grp_sagittal, structure["acronym"], outlines, resolution=res
            )

            # coronal
            outlines = get_structure_contour(mask, axis=0)
            res = atlas.resolution[1], atlas.resolution[2]  # d-v, l-r
            outlines_to_group(
                grp_coronal, structure["acronym"], outlines, resolution=res, fliplr=True
            )

            # top
            outlines = get_structure_contour(mask, axis=1)
            res = atlas.resolution[2], atlas.resolution[0]  # l-r, a-p
            outlines_to_group(grp_top, structure["acronym"], outlines, resolution=res)

get_default_filename(atlas_name) #

Get the file name $HOME/.cuisto/{atlas_name}.h5

Parameters:

Name Type Description Default
atlas_name str

Name of a Brainglobe atlas.

 required

Returns:

Name Type Description
filename str

Path to the default file location.
Source code in cuisto/atlas.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def get_default_filename(atlas_name: str) -> str:
    """
    Get the file name $HOME/.cuisto/{atlas_name}.h5

    Parameters
    ----------
    atlas_name : str
        Name of a Brainglobe atlas.

    Returns
    -------
    filename : str
        Path to the default file location.

    """
    from pathlib import Path

    local_dir = Path.home() / ".cuisto"
    if not local_dir.exists():
        print(f"[Info] Outline file not specified, creating the {local_dir} directory.")
        local_dir.mkdir()
    return str(local_dir / (atlas_name + "_outlines.h5"))

get_structure_contour(mask, axis=2) #

Get structure contour.

Parameters:

Name Type Description Default
mask ndarray

3D mask of structure.

 required
axis int

Axis, determines the projection. 2 is sagittal. Default is 2.

 2

Returns:

Name Type Description
contour list

List of 2D array with contours (in pixels).
Source code in cuisto/atlas.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def get_structure_contour(mask: np.ndarray, axis: int = 2) -> list:
    """
    Get structure contour.

    Parameters
    ----------
    mask : np.ndarray
        3D mask of structure.
    axis : int, optional
        Axis, determines the projection. 2 is sagittal. Default is 2.

    Returns
    -------
    contour : list
        List of 2D array with contours (in pixels).

    """
    return measure.find_contours(np.max(mask, axis=axis))

outlines_to_group(grp, acronym, outlines, resolution=(10, 10), fliplr=False) #

Write arrays to hdf5 group.

Parameters:

Name Type Description Default
grp h5py group

Group in hdf5 file

 required
acronym str

Subgroup name

 required
outlines list

List of 2D ndarrays

 required
resolution tuple

Resolution (row, columns) in the 2D projection, before flipping. Default is (10, 10).

 (10, 10)
fliplr bool, Defaults to False
False
Source code in cuisto/atlas.py 
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
def outlines_to_group(
    grp, acronym: str, outlines: list, resolution: tuple = (10, 10), fliplr=False
):
    """
    Write arrays to hdf5 group.

    Parameters
    ----------
    grp : h5py group
        Group in hdf5 file
    acronym : str
        Subgroup name
    outlines : list
        List of 2D ndarrays
    resolution : tuple, optional
        Resolution (row, columns) in the 2D projection, before flipping. Default is
        (10, 10).
    fliplr : bool, Defaults to False

    """
    grp_structure = grp.create_group(acronym)
    c = 0
    for outline in outlines:
        outline *= resolution
        if fliplr:
            outline = np.fliplr(outline)
        grp_structure.create_dataset(f"{c}", data=outline)
        c += 1