atlannot.region_meta module

Implementation of the RegionMeta class.

class atlannot.region_meta.RegionMeta(background_id=0, background_color='000000')[source]

Bases: object

Class holding the hierarchical region metadata.

Typically, such information would be parsed from a brain_regions.json file.

Parameters:

• background_id (int, optional) – Override the default ID for the background.

• background_color (str, optional) – Override the default color for the background. Should be a string of length 6 with RGB values in hexadecimal form.

acronym(id_)[source]

Get the acronym of a region.

Parameters:

id – A region ID.

Return type:

The acronym a the given region.

ancestors(ids, include_background=False)[source]

Find all ancestors of given regions.

The result is inclusive, i.e. the input region IDs will be included in the result.

Parameters:

• ids (int or iterable of int) – A region ID or a collection of region IDs to collect ancestors for.

• include_background (bool) – If True the background region ID will be included in the result.

Returns:

All ancestor region IDs of the given regions, including the input regions themselves.

Return type:

set

children(region_id)[source]

Get all child region IDs of a given region.

Note that by children we mean only the direct children, much like by parent we only mean the direct parent. The cumulative quantities that span all generations are called ancestors and descendants.

Parameters:

region_id (int) – The region ID in question.

Yields:

int – The region ID of a child region.

property color_map

Map region IDs to RGB colors.

Returns:

color_map – The color map. Keys are regions IDs, and values are tuples with three integers between 0 and 255 representing the RGB colors.

Return type:

dict

property depth

Find the depth of the region hierarchy.

The background region is not taken into account.

Returns:

The depth of the region hierarchy.

Return type:

int

descendants(ids)[source]

Find all descendants of given regions.

The result is inclusive, i.e. the input region IDs will be included in the result.

Parameters:

ids (int or iterable of int) – A region ID or a collection of region IDs to collect descendants for.

Returns:

All descendant region IDs of the given regions, including the input regions themselves.

Return type:

set

find_by_acronym(acronym)[source]

Find the region ID given its acronym.

Parameters:

acronym (str) – The acronym of a region ID

Returns:

The region ID if a region is found, otherwise None

Return type:

int or None

find_by_name(name)[source]

Find the region ID given its name.

Parameters:

name (str) – The name of a region ID

Returns:

The region ID if a region is found, otherwise None

Return type:

int or None

classmethod from_dict(region_hierarchy, warn_raw_response=True)[source]

Construct an instance from the region hierarchy.

Parameters:

• region_hierarchy (dict) – The dictionary of the region hierarchy. Should have the format as usually provided by the AIBS.

• warn_raw_response (bool) – If True and a raw AIBS response (containing the “msg” key) is used, then a warning will be logged.

Returns:

region_meta – The initialized instance of this class.

Return type:

RegionMeta

ids_at_level(level)[source]

Region IDs at a given hierarchy level.

Finds all region IDs at the given level and yields them one by one.

Yields:

region_id (int) – A region ID at the given level

in_region_like(region_name_regex, region_id)[source]

Check if region belongs to a region with a given name pattern.

Note that providing a simple string without any special characters is equivalent to a substring test.

Parameters:

• region_name_regex (str) – A regex to match the region name.

• region_id (int) – A region ID.

Returns:

Whether or not the region with the given ID is in a region with the given name part. All parent regions are also checked.

Return type:

bool

is_leaf(region_id)[source]

Check if the given region is a leaf region.

Parameters:

region_id (int) – The region ID in question.

Returns:

Whether or not the given region is a leaf region.

Return type:

bool

is_valid_id(id_)[source]

Check whether the given region ID is part of the structure graph.

Parameters:

id (int) – The region ID in question.

Returns:

Whether the given region ID is part of the structure graph

Return type:

bool

classmethod load_json(json_path)[source]

Load the structure graph from a JSON file and create an instance.

Parameters:

json_path (str or pathlib.Path) –

Returns:

The initialized instance of this class.

Return type:

RegionMeta

name(id_)[source]

Get the name of a region.

Parameters:

id – A region ID.

Returns:

The name of the given region.

Return type:

str

parent(region_id)[source]

Get the parent region ID of a region.

Parameters:

region_id – The region ID in question.

Returns:

The region ID of the parent. If there’s no parent then None is returned.

Return type:

int or None

print_regions(root_id=None, max_depth=-1, acronym=False)[source]

Print the region hierarchy tree to stdout.

Parameters:

• root_id (int, optional) – The ID that shall be at the top of the printed hierarchy tree. Defaults to the true hierarchy root region if none is provided.

• max_depth (int, default -1) – If a non-negative integer then the hierarchy will be printed only up to the given depth. Otherwise the whole hierarchy will be printed.

• acronym (bool, default False) – If true then instead of the full region name its acronym will be used.

property size

Find the number of regions in the structure graph.

Returns:

The number of regions in the structure graph

Return type:

int

to_dict(root_id=None)[source]

Serialise the region structure data to a dictionary.

This is exactly the inverse of the from_dict method.

Parameters:

root_id (int or None, optional) – Which region ID to start with. This will be the new top of the serialised structure graph. If none is provided then to real root region is used and as a consequence the complete structure graph is serialised.

Returns:

The serialised region structure data.

Return type:

dict