Usage

0. Creating a BrainGlobeAtlas object and list availabe options
To instantiate a BrainGlobeAtlas object, we need to instantiate it with the atlas name. The first time we use it, a version of this atlas files will be downloaded from the remote GIN repository and stored on your local machine (by default, in .../Users/username/.brainglobe):
from bg_atlasapi import BrainGlobeAtlas
from pprint import pprint
​
bg_atlas = BrainGlobeAtlas("allen_mouse_100um", check_latest=False)
To know what atlases are available through BrainGlobe, we can use the show_atlases function (we need to be online):
from bg_atlasapi import show_atlases
show_atlases()
1. Using a BrainGlobe atlas
A BrainGlobe atlas is a convenient API for interacting with an anatomical atlas. BrainGlobe atlases contain:
Metadata
Reference anatomical stack
Region annotation stack
Hemisphere annotation stack
Description of the region hierarchy
Meshes for the regions
1.0 Metadata
All atlases have a standard set of metatata describing their source, species, resolution, etc:
bg_atlas.metadata
1.1 Anatomical, annotation and hemispheres stack
from matplotlib import pyplot as plt
Anatomical reference:
stack = bg_atlas.reference
Annotations stack:
stack = bg_atlas.annotation
Hemisheres stack:
stack = bg_atlas.hemispheres
1.2 Regions hierarchy
The atlas comes with the description of a hierarchy of brain structures. To have an overview:
bg_atlas.structures
The structures attribute is a custom dictionary that can be queried by region number or acronym, and contains all the information for a given structure:
bg_atlas.structures["root"]
In particular, the structure_id_path key contains a list description of the path in the hierarchy up to a particular region, and can be used for queries on the hierarchy.
bg_atlas.structures["CH"]["structure_id_path"]
We can use the bg_atlas.get_structure_descendants and bg_atlas.get_structure_ancestors methods to explore the hierarchy:
bg_atlas.get_structure_descendants("VISC")
bg_atlas.get_structure_ancestors("VISC6a")
NOTE: the levels of the hierarchy depends on the underlying atlas, so we cannot ensure the goodness and consistency of their hierarchy three.
There is an higher level description of the structures hierarchy that is built using the treelib package, and is available as:
bg_atlas.structures.tree
For most applications though the methods described above and the list path of each region should be enough to query the hierarchy without additional layers of complication.
1.3 Region masks
Sometimes, we might want to have the mask for a region that is not labelled in the annotation stack as all its voxels have the number of some lower level parcellation in the hierarchy (concretely, if the brain is divided in hindbrain, midbrain, and forebrain, annotation == root_id will be all False).
To get the mask for a region, simply type:
stack = bg_atlas.get_structure_mask(997)
1.3 Regions meshes
If we need to access the structure meshes, we can either query for the file (e.g., if we need to load the file through some library like vedo):
bg_atlas.meshfile_from_structure("CH")
Or directly obtain the mesh, as a mesh object of the meshio library:
bg_atlas.mesh_from_structure("CH")
2 Query the BrainGlobeAtlas
2.0 Query for structures
A very convenient feature of the BrainGlobeAtlas API is the simplicity of querying for the identity of the structure or the hemisphere at a given location, either from stack indexes or space coordinates, and even cutting the hierarchy at some higher level:
# Ask for identity of some indexes in the stack:
bg_atlas.structure_from_coords((50, 40, 30), as_acronym=True)
​
# Now give coordinates in microns:
bg_atlas.structure_from_coords((5000, 4000, 3000), as_acronym=True, 
                               microns=True)
​
# Now cut hierarchy at some level:
bg_atlas.structure_from_coords((5000, 4000, 3000), as_acronym=True,
                               microns=True,  hierarchy_lev=2)
2.1 Query for hemispheres
A very similar method can be used for hemispheres. 0 correspond to outside the brain, a,d 1 and 2 to left and right hemispheres - but we can just ask for the side name instead of the number:
# Ask for identity of some indexes in the stack:
bg_atlas.hemisphere_from_coords((50, 40, 30))
​
# Now give coordinates in microns
bg_atlas.hemisphere_from_coords((5000, 4000, 3000), microns=True)
​
# Now print side string
bg_atlas.hemisphere_from_coords((5000, 4000, 3000), microns=True)