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.

• The annotation file is assumed to be ‘annotation_25_full.nrrd’ but can be set via default_annotation_file.

• The mapping between labels and brain area information is assumed to be in the ‘annotation.json’ file but the location can be set via default_label_file.

References

• Allen Brain Atlas

class Annotation(label_file=None, extra_label=None, annotation_file=None)

Bases: object

Class that holds information of the annotated regions.

add_data(name, data)

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

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

enrich_df(df)

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

get_children(structure_ids)

get_colors_rgba(alpha=1)

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)

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

ids_to_acronyms(ids)

ids_to_names(ids)

initialize(label_file=None, extra_label=None, annotation_file=None)

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

label_points(points)

Parameters:

points (array representing coordinates (floats) of n points, shape (n_points, 3))

Returns

array of structure ids, of shape (n_points,)

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

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

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)

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

Generates a color map from color ids to rgb

Arguments

alphabool

If True return a color map with alpha values.

Returns

color_maparray

An array of rgb colors for each label.

colorize(array, key='id')

convert_array(array, key='id', value='order')

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

Convert label using the atlas annotation data.

Arguments

labelarray

List of labels to convert.

keystr

The key corresponding to the label. #TODO list possible keys

valuestr

The key to convert the label to. #TODO list possible values

levelnt or None

Convert at this level of the hierarchy. If None use full hierarchy.

method‘map’ or ‘dictionary’

Convert labels using a mapping array or a dictionary. Depending on the keys either can be faster for large data sets.

Returns

labelarray

List of converted labels.

create_singleton()

decompress_atlases(atlas_base_name)

get_names_map()

initialize(label_file=None, extra_label=None, annotation_file=None)

label_points(points, annotation_file=None, invalid=0, key='order', level=None)

Label points according to the annotation in the labeled image file.

Arguments

pointsarray

Array of ndim point coordinates to be labeled.

annotation_filestr

File name of the atlas annotation.

invalidint

Label for invalid points.

keystr

The key of the label, by default the order of the labels.

levelint

The level of the hierarchy to use.

Returns

labelarray

Label of the points corresponding to the given key.

prepare_annotation_files(slicing=None, orientation=None, directory=None, postfix=None, annotation_file=None, hemispheres_file=None, reference_file=None, distance_to_surface_file=None, hemispheres=False, 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.

postfixstr or None

Use this postfix for the cropped annotation file. If None and automatic label is chosen.

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.

hemispheresbool

Whether to return the hemispheres annotation

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.

set_annotation_file(annotation_file)

set_label_file(label_file, extra_label=None)

default_annotation_file = '/home/crousseau/code/icm/ClearMap2-lf003/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/crousseau/code/icm/ClearMap2-lf003/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/crousseau/code/icm/ClearMap2-lf003/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/crousseau/code/icm/ClearMap2-lf003/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/crousseau/code/icm/ClearMap2-lf003/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