BrainGlobeAtlas#

class brainglobe_atlasapi.bg_atlas.BrainGlobeAtlas(atlas_name, brainglobe_dir=None, interm_download_dir=None, check_latest=True, config_dir=None, fn_update=None)[source]#

Bases: Atlas

Add remote atlas fetching and version comparison functionalities to the core Atlas class.

Parameters:

atlas_name (str) – Name of the atlas to be used.
brainglobe_dir (str or Path object) – Default folder for brainglobe downloads.
interm_download_dir (str or Path object) – Folder to download the compressed file for extraction.
check_latest (bool (optional)) – If true, check if we have the most recent atlas (default=True). Set this to False to avoid waiting for remote server response on atlas instantiation and to suppress warnings.
print_authors (bool (optional)) – If true, disable default listing of the atlas reference.
fn_update (Callable) – Handler function to update during download. Takes completed and total bytes.

Methods

`check_latest_version`([print_warning])	Check if the local version is the latest available and prompts the user to update if not.
`download_extract_file`()	Download and extract atlas from remote url.
`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 a stack with the mask for a specific structure (including all sub-structures).
`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.
`atlas_name`
`hemispheres`	Returns a stack with the hemisphere information.
`hierarchy`	Returns a Treelib.tree object with structures hierarchy.
`left_hemisphere_value`
`local_full_name`	As we can't know the local version a priori, search candidate dirs using name and not version number.
`local_version`	If atlas is local, return actual version of the downloaded files; Else, return none.
`lookup_df`	Returns a dataframe with id, acronym and name for each structure.
`orientation`	Make orientation more accessible from class.
`reference`	Return the reference image data.
`remote_url`	Format complete url for download.
`remote_version`	Remote version read from GIN conf file.
`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.

property annotation#: Return the annotation image data. Loads it if not already loaded.

check_latest_version(print_warning: bool = True) → bool | None[source]#

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_extract_file()[source]#: Download and extract atlas from remote url.

get_structure_ancestors(structure)#

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)#

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)#

Return a stack with the mask for a specific structure (including all sub-structures).

This function might take a few seconds for structures with many children.

Parameters:: structure (str or int) – Structure id or acronym
Returns:: stack containing the mask array.
Return type:: np.array

hemisphere_from_coords(coords, microns=False, as_string=False)#

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#: As we can’t know the local version a priori, search candidate dirs using name and not version number. If none is found, return None.

property local_version#: If atlas is local, return actual version of the downloaded files; Else, return none.

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

mesh_from_structure(structure)#

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)#

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 reference image data. Loads it if not already loaded.

property remote_url#: Format complete url for download.

property remote_version#: Remote version read from GIN conf file. If we are offline, return None.

property resolution#: Make resolution more accessible from class.

root_mesh()#

Retrieve the mesh for the root structure.

Return type:: The mesh data for the root structure.

root_meshfile()#

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

Returns:: str
Return type:: 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')#

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