Atlas#

class brainrender.atlas.Atlas(atlas_name=None, check_latest=True)[source]#

Bases: BrainGlobeAtlas

Subclass of BrainGlobeAtlas with helpers for rendering.

Parameters:

atlas_name (str | None) – Falls back to settings.DEFAULT_ATLAS if None.
check_latest (bool) – Check for the latest atlas version. Default True.

Methods

`check_latest_version`([print_warning])	Check if the local version is the latest available and prompts the user to update if not.
`download`()	Download and extract the atlas files from remote storage.
`get_plane`([pos, norm, plane, sx, sy, color, ...])	Returns a plane going through a point at pos, oriented orthogonally to the `norm` vector and of width and height sx, sy.
`get_region`(*regions[, alpha, color])	Get brain regions meshes as Actors.
`get_structure_ancestors`(structure)	Return a list of acronyms for all ancestors of a given structure.
`get_structure_descendants`(structure)	Return a list of acronyms for all descendants of a given structure.
`get_structure_mask`(structure)	Return binary uint8 mask for the given structure.
`get_structures_at_hierarchy_level`(structure)	Get structures at a specific hierarchy level within the subgraph of nodes connected to the given structure.
`hemisphere_from_coords`(coords[, microns, ...])	Get the hemisphere from a coordinate triplet.
`mesh_from_structure`(structure)	Retrieve the mesh associated with a given structure.
`meshfile_from_structure`(structure)	Retrieve the path to the mesh file associated with a given structure.
`root_mesh`()	Retrieve the mesh for the root structure.
`root_meshfile`()	Retrieve the path to the mesh file for the root structure.
`structure_from_coords`(coords[, microns, ...])	Get the structure from a coordinate triplet.

Attributes

`annotation`	Return the annotation image data.
`hemispheres`	Returns a stack with the hemisphere information.
`hierarchy`	Returns a Treelib.tree object with structures hierarchy.
`left_hemisphere_value`
`local_full_name`	Returns the local full path to the manifest.json file of the atlas.
`local_version`	If atlas is local, return actual version of the downloaded files.
`lookup_df`	Returns a dataframe with id, acronym and name for each structure.
`orientation`	Make orientation more accessible from class.
`reference`	Return the template image data.
`remote_version`	Reads remote version from s3 bucket.
`resolution`	Make resolution more accessible from class.
`right_hemisphere_value`
`shape`	Make shape more accessible from class.
`shape_um`	Make shape more accessible from class.
`template`	Return the template image data.
`zoom`	Return a reasonable camera zoom given the atlas resolution.

property annotation: ndarray[tuple[Any, ...], dtype[uint32]]#: Return the annotation image data. Loads it if not already loaded.

check_latest_version(print_warning=True)#

Check if the local version is the latest available and prompts the user to update if not.

Parameters:: print_warning (bool, optional) – If True, prints a message if the local version is not the latest, by default True. Useful to turn off, e.g. when the user is updating the atlas
Returns:: Returns False if the local version is not the latest, True if it is, and None if we are offline.
Return type:: Optional[bool]

download()#

Download and extract the atlas files from remote storage.

The manifest file is removed if any error occurs during the download to ensure that incomplete downloads are retried.

get_plane(pos=None, norm=None, plane=None, sx=None, sy=None, color='lightgray', alpha=0.25, **kwargs)[source]#

Returns a plane going through a point at pos, oriented orthogonally to the norm vector and of width and height sx, sy.

Parameters:

pos (TypeAliasType | None) – (x, y, z) the plane passes through. Defaults to root centre of mass.
norm (TypeAliasType | None) – Normal vector. Derived from plane if not given.
plane (str | None) – "sagittal", "horizontal", or "frontal".
sx (float | None) – Width. Inferred from root bounds if None.
sy (float | None) – Height. Inferred from root bounds if None.
color (str) – Default "lightgray".
alpha (float) – Default 0.25.

Return type:

Actor

Raises:

ValueError – If plane has no matching normal in the atlas space.

get_region(*regions, alpha=1, color=None)[source]#

Get brain regions meshes as Actors.

Parameters:

*regions (str | int) – Region acronyms or IDs.
alpha (float) – Mesh transparency. Default 1.
color (str | list[float] | None) – Uses atlas RGB colour if None.

Return type:

Actor or list of Actor or None

get_structure_ancestors(structure)[source]#

Return a list of acronyms for all ancestors of a given structure.

Parameters:: structure (str or int) – Structure id or acronym
Returns:: List of descendants acronyms
Return type:: list

get_structure_descendants(structure)[source]#

Return a list of acronyms for all descendants of a given structure.

Parameters:: structure (str or int) – Structure id or acronym
Returns:: List of descendants acronyms
Return type:: list

get_structure_mask(structure)[source]#

Return binary uint8 mask for the given structure.

Reads directly from the pre-built 4D annotation masks array.

Parameters:

structure (str or int) – Structure acronym or id.

Returns:

Binary uint8 array; 1 where the structure (or a descendant) has a voxel, 0 elsewhere.

Return type:

np.ndarray

Raises:

FileNotFoundError – If this atlas does not have a 4D mask array on disk.
KeyError – If the structure is not present in the annotation mapping.

get_structures_at_hierarchy_level(structure, hierarchy_level=None, as_acronym=False)[source]#

Get structures at a specific hierarchy level within the subgraph of nodes connected to the given structure.

For a given brain structure, this method finds all leaf nodes (terminal structures with no children) in its subtree, then extracts the structures at the specified hierarchy level from their paths.

Parameters:

structure (str or int) – Structure ID or acronym to query.
hierarchy_level (int or None, optional) – The hierarchy level to extract (0-indexed, where 0 is root). If None, returns all structures in the paths to all leaves in anatomical order (breadth-first traversal).
as_acronym (bool, optional) – If True, return acronyms instead of IDs. Default is False.

Returns:

List of structure IDs (if as_acronym=False) or acronyms (if as_acronym=True) at the specified hierarchy level.

Return type:

list

Raises:

ValueError – If hierarchy_level is not an integer or None. If the structure has no descendants at the specified level.

Examples

>>> atlas = BrainGlobeAtlas("allen_mouse_25um")
>>> # Get all level-3 structures under cortex
>>> ids = atlas.get_structures_at_hierarchy_level("CTX", 3)
>>> # Get as acronyms instead
>>> acronyms = atlas.get_structures_at_hierarchy_level(
...     "CTX", 3, as_acronym=True
... )

hemisphere_from_coords(coords, microns=False, as_string=False)[source]#

Get the hemisphere from a coordinate triplet.

Parameters:

coords (tuple or list or numpy array) – Triplet of coordinates. Default in voxels, can be microns if microns=True
microns (bool) – If true, coordinates are interpreted in microns.
as_string (bool) – If true, returns “left” or “right”.

Returns:

Hemisphere label.

Return type:

int or string

property hemispheres#

Returns a stack with the hemisphere information. 1 - left, 2 - right.

If a symmetric reference is used, the hemisphere information is generated by splitting the reference in half along the frontal axis. If the reference has an odd number of voxels along the frontal axis, the middle plane is assigned to the left hemisphere.

property hierarchy#: Returns a Treelib.tree object with structures hierarchy.

property local_full_name#

Returns the local full path to the manifest.json file of the atlas.

This will return either the path to the requested version if it is found locally, or the latest version found locally.

If not found, returns None.

property local_version: Tuple[int, ...] | None#: If atlas is local, return actual version of the downloaded files.

property lookup_df#: Returns a dataframe with id, acronym and name for each structure.

mesh_from_structure(structure)[source]#

Retrieve the mesh associated with a given structure.

Parameters:: structure (int or str or list of int/str) – The ID or acronym of the structure for which to retrieve the mesh. If a list of IDs/acronyms is passed, a list of meshes will be returned.
Returns:: The mesh data (e.g., a Mesh object) associated with the structure(s).
Return type:: meshio.Mesh or list of meshio.Mesh

meshfile_from_structure(structure)[source]#

Retrieve the path to the mesh file associated with a given structure.

Parameters:: structure (int or str) – The ID or acronym of the structure for which to retrieve the mesh file path. If a list of IDs/acronyms is passed, a list of paths will be returned.
Returns:: The path(s) to the mesh file(s) for the structure(s).
Return type:: Path or list of Path

property orientation#: Make orientation more accessible from class.

property reference#

Return the template image data.

Warning: this is a deprecated alias for template, and will be removed in future versions. Use atlas.template instead.

property remote_version: tuple[int, ...] | None#

Reads remote version from s3 bucket.

Unless a version was requested, the latest version is the one listed in the remote last_versions.conf. If we are offline or using a custom atlas, return None.

property resolution#: Make resolution more accessible from class.

root_mesh()[source]#

Retrieve the mesh for the root structure.

Returns:: The mesh data for the root structure.

root_meshfile()[source]#

Retrieve the path to the mesh file for the root structure.

Returns:: str: The path to the mesh file for the root structure.

property shape#: Make shape more accessible from class.

property shape_um#: Make shape more accessible from class.

structure_from_coords(coords, microns=False, as_acronym=False, hierarchy_lev=None, key_error_string='Outside atlas')[source]#

Get the structure from a coordinate triplet.

Parameters:

coords (tuple or list or numpy array) – Triplet of coordinates.
microns (bool) – If true, coordinates are interpreted in microns.
as_acronym (bool) – If true, the region acronym is returned. If outside atlas (structure gives key error), return “Outside atlas”
hierarchy_lev (int or None) – If specified, return parent node at thi hierarchy level.

Returns:

Structure containing the coordinates.

Return type:

int or string

property template: ndarray[tuple[Any, ...], dtype[uint16]]#: Return the template image data. Loads it if not already loaded.

property zoom: float#: Return a reasonable camera zoom given the atlas resolution.