Annotation

Module to handle label and annotation info from Allen Brain Atlas (v2).

Notes

• The files containing annotation information is assumed to be in the path stored in atlas_path, which defaults to the resource path ClearMap.Settings.resources_path.

References

• Allen Brain Atlas

class Annotation(atlas_base_name, slicing, orientation, label_source, target_directory=None, extra_label=None)

Bases: object

Class that holds information of the annotated regions.

static prepare_annotation_files(slicing, orientation, directory=None, annotation_file=None, hemispheres_file=None, reference_file=None, distance_to_surface_file=None, overwrite=False, verbose=False)

Crop the annotation, reference and distance files to match the data.

Arguments

slicingtuple or None

The slice specification after reorienting.

orientationtuple, str or None.

The orientation specification. Strings can be ‘left’ or ‘right’, for the two hemispheres.

directorystr or None

The target directory. If None, use ClearMap resources folder.

annotation_filestr or None

The annotation file to use.

hemispheres_filestr or None

The hemispheres annotation file to use. “hemispheres” must be set to True

reference_filestr or None

The reference file to use.

distance_to_surface_filestr or None

The distance file to use.

overwritebool

If True, overwrite existing files.

verbosebool

Whether to print verbose output.

Returns

annotation_filestr

The cropped annotation file.

reference_filestr

The cropped reference file.

distance_to_surface_filestr

The distance cropped file.

add_data(name, data)

color_map(color_ids=None, alpha=True, as_int=False, int_type='uint8')

Generates a color map from color ids to rgb

Arguments

color_ids: list

The list of ids to generate the color map for. e.g. a rgb tuple, color name from matplotlib or vispy, hex code

alphabool

If True return a color map with alpha values.

as_intbool

If True return a color map with integer values in the range 0-255.

int_typestr

The integer type to use for the output, e.g. ‘uint8’, ‘uint16’.

Returns

color_maparray

An array of rgb colors for each label.

common_parent(label, key='id', value=None)

convert_label(label, key='id', value='order', level=None, method='map', node=None)

create_color_annotation(annotation_file_path='', dest_path='')

Creates a rgb image from the atlas color data.

Arguments

annotation_file_pathstr

File name of the atlas annotation.

dest_pathstr

The path to the file where the color atlas should be written. If empty, the color atlas is only returned as an array.

Returns

filenamestr

The name of the file to which the color atlas was written.

enrich_df(df)

find(label, key='id', value=None, node=None, level=None)

get_atlas_paths()

get_children(structure_ids)

get_colors_rgba(alpha=1)

get_columns(coordinates_transformed, atlas_resolution, ids=None)

get_dict(from_='id', to='acronym')

get_dict_children_to_parents(parents_ids=None, including_parents=False)

get_dict_parents_to_children(parents_ids=None, including_parents=False)

get_dictionary(key, value, node=None, level=None, ordered=False, with_parents=False, max_depth=None, min_level=None)

get_hierarchical_dictionary(node=None)

get_lateralised_volume_map(atlas_scale, hemispheres_file_path=None)

get_list(key=None, node=None, level=None)

get_map(key, value, node=None, level=None)

get_map_to_parent(parent_ids)

uses annotation graph to map all possible children structures to its parent in parent_ids

get_names_map()

ids_to_acronyms(ids)

ids_to_names(ids)

initialize(annotation_file_path=None, hemispheres_file_path=None, distance_to_surface_file_path=None, reference_file_path=None, label_file_path=None, extra_label=None)

initialize_tree(root, parent=None, level=0)

label_points(points, annotation_file_path=None, key='id', level=None, invalid=0, d_type=<class 'numpy.uint64'>)

Label points using the annotation file (atlas with ids as voxels).

Parameters:

• points (array-like) – The points to label.

• annotation_file_path (str | Path | None) – The path to the annotation file. If None, use the atlas attribute.

• key (str) – The key (in the ontology file) to use for the label conversion. The default is ‘id’. If key != ‘id’, the label will be converted to the specified key.

• level (None | int) – The level in the hierarchy to use for the label conversion. The default is None. (see convert_label for details)

• invalid (float | int) – The default value for points outside the atlas. The default is 0.

• d_type (np.dtype) – data type of the labels (typically ids). The default is np.uint64 because the default

• uint64. (atlas is)

Returns

point_labels: array-like

The labels for each point. (shape = len(points))

label_points_hemispheres(points, key='id', level=None, invalid=-1)

Label points using the hemispheres annotation file (atlas with hemisphere id as voxels).

Parameters:

• points (array-like) – The points to label.

• key (str) – The key (in the ontology file) to use for the label conversion. The default is ‘id’. If key != ‘id’, the label will be converted to the specified key. See label_points for details

• level (None | int) – The level in the hierarchy to use for the label conversion. The default is None. (see convert_label for details)

• invalid – The default value for points outside the atlas. The default is 0.

Returns

point_labels: array-like

label_to_color(label, key='id', level=None, alpha=True, as_int=False, int_type='uint8')

parents(label, key='id', value=None)

set_annotation_file(annotation_file_path)

set_label_file(label_file_path)

write_color_palette(file_path='')

Creates a pal or lut file for Imaris or Imagej based on label colors of atlas.

Arguments

file_pathstr | Path

The name of the color palette file.

Returns

filenamestr

The name of the file to which the color palette was written.

property map_volume

property max_level

property n_structures

class Label(data, children=None, parent=None, level=0)

Bases: object

Class holding information of an individual Atlas label.

color(*args, **kwargs)

info(with_children=True, indent=None)

parent_list(max_depth=None, min_level=None)

write(with_children=True, indent=None)

property id

property level

property name

property order

annotation_to_distance_file(annotation_file_path)

decompress_atlases(atlas_base_name)

get_atlas_filepath(filename, directory=None, orientation=None, slicing=None)

Formats the annotation filename given orientation and slicing.

default_annotation_file = '/home/charly.rousseau/code/icm/ClearMap2/ClearMap/Resources/Atlas/ABA_25um_annotation.tif'

Note

This file is by default the Allen brain annotated mouse atlas with 25um isotropic resolution.

Includes the

• Default volumetric annotated image file.

• Default hemispheres annotated image file

• Default reference (grayscale) image file

• Corresponding distance to surface file

default_distance_to_surface_file = '/home/charly.rousseau/code/icm/ClearMap2/ClearMap/Resources/Atlas/ABA_25um_distance_to_surface.tif'

Note

This file is by default the Allen brain annotated mouse atlas with 25um isotropic resolution.

Includes the

• Default volumetric annotated image file.

• Default hemispheres annotated image file

• Default reference (grayscale) image file

• Corresponding distance to surface file

default_extra_label = [(182305696, 453, 'No label', 'NoL'), (182305712, 453, 'No label', 'NoL'), (312782560, 315, 'No label', 'NoL'), (312782592, 453, 'No label', 'NoL'), (312782656, 315, 'No label', 'NoL'), (526157184, 993, 'No label', 'NoL'), (526322272, 500, 'No label', 'NoL'), (527696992, 315, 'No label', 'NoL')]

Additional label not in the Allen Brain Atlas label but in the atlas image.

Warning

This is required for the older version of the Allen Brain Atlas. There are no more labels missing in the current version (2017+ with 2022+ json file).

Note

The form is a list of tuples, each tuple has the form (atlas id, parent id, name, acronym).

default_hemispheres_file = '/home/charly.rousseau/code/icm/ClearMap2/ClearMap/Resources/Atlas/ABA_25um_hemispheres.tif'

Note

This file is by default the Allen brain annotated mouse atlas with 25um isotropic resolution.

Includes the

• Default volumetric annotated image file.

• Default hemispheres annotated image file

• Default reference (grayscale) image file

• Corresponding distance to surface file

default_label_file = '/home/charly.rousseau/code/icm/ClearMap2/ClearMap/Resources/Atlas/ABA_annotation.json'

Default list of labels and region names in the annotated image.

Note

This file is by default the labels for the Allen brain annotated mouse atlas with 25um isotropic resolution.

default_reference_file = '/home/charly.rousseau/code/icm/ClearMap2/ClearMap/Resources/Atlas/ABA_25um_reference.tif'

Note

This file is by default the Allen brain annotated mouse atlas with 25um isotropic resolution.

Includes the

• Default volumetric annotated image file.

• Default hemispheres annotated image file

• Default reference (grayscale) image file

• Corresponding distance to surface file