Skip to main content

A lightweight python module to interact with atlases for systems neuroscience

Project description


Python Version PyPI Wheel Development Status Tests Coverage Status Code style: black DOI License


The brainglobe atlas API (BG-AtlasAPI) provides a common interface for programmers to download and process brain atlas data from multiple sources.

Atlases available

A number of atlases are in development, but those available currently are:


BG-AtlasAPI works with Python >3.6, and can be installed from PyPI with:

pip install bg-atlasapi


Full information can be found in the documentation

Python API

List of atlases

To see a list of atlases use bg_atlasapi.show_atlases

from bg_atlasapi import show_atlases
#                                Brainglobe Atlases                               
# ╭──────────────────────────────────┬────────────┬───────────────┬──────────────╮
# │ Name                             │ Downloaded │ Local version │    Latest    │
# │                                  │            │               │   version    │
# ├──────────────────────────────────┼────────────┼───────────────┼──────────────┤
# │ allen_human_500um                │     ✔      │      0.1      │     0.1      │
# │ mpin_zfish_1um                   │     ✔      │      0.3      │     0.3      │
# │ allen_mouse_50um                 │     ✔      │      0.3      │     0.3      │
# │ kim_unified_25um                 │     ✔      │      0.1      │     0.1      │
# │ allen_mouse_25um                 │     ✔      │      0.3      │     0.3      │
# │ allen_mouse_10um                 │     ✔      │      0.3      │     0.3      │
# │ example_mouse_100um              │    ---     │      ---      │     0.3      │
# ╰──────────────────────────────────┴────────────┴───────────────┴──────────────╯

Using the atlases

All the features of each atlas can be accessed via the BrainGlobeAtlas class.

e.g. for the 25um Allen Mouse Brain Atlas:

from bg_atlasapi.bg_atlas import BrainGlobeAtlas
atlas = BrainGlobeAtlas("allen_mouse_25um")

The various files associated with the atlas can then be accessed as attributes of the class:

# reference image
reference_image = atlas.reference
# (528, 320, 456)

# annotation image
annotation_image = atlas.annotation
# (528, 320, 456)

# a hemispheres image (value 1 in left hemisphere, 2 in right) can be generated
hemispheres_image = atlas.hemispheres
# (528, 320, 456)

Brain regions

There are multiple ways to work with individual brain regions. To see a dataframe of each brain region, with it's unique ID, acronym and full name, use atlas.lookup_df:

#      acronym         id                           name
# 0       root        997                           root
# 1       grey          8  Basic cell groups and regions
# 2         CH        567                       Cerebrum
# 3        CTX        688                Cerebral cortex
# 4      CTXpl        695                 Cortical plate
# 5  Isocortex        315                      Isocortex
# 6        FRP        184  Frontal pole, cerebral cortex
# 7       FRP1         68          Frontal pole, layer 1

Each brain region can also be access by the acronym, e.g. for primary visual cortex (VISp):

from pprint import pprint
VISp = atlas.structures["VISp"]
# {'acronym': 'VISp',
#  'id': 385,
#  'mesh': None,
#  'mesh_filename': PosixPath('/home/user/.brainglobe/allen_mouse_25um_v0.3/meshes/385.obj'),
#  'name': 'Primary visual area',
#  'rgb_triplet': [8, 133, 140],
#  'structure_id_path': [997, 8, 567, 688, 695, 315, 669, 385]}

Note on coordinates in bg-atlasapi

Working with both image coordinates and cartesian coordinates in the same space can be confusing! In bg-atlasapi, the origin is always assumed to be in the upper left corner of the image (sectioning along the first dimension), the "ij" convention. This means that when plotting meshes and points using cartesian systems, you might encounter confusing behaviors coming from the fact that in cartesian plots one axis is inverted with respect to ij coordinates (vertical axis increases going up, image row indexes increase going down). To make things as consistent as possible, in bg-atlasapi the 0 of the meshes coordinates is assumed to coincide with the 0 index of the images stack, and meshes coordinates increase following the direction stack indexes increase. To deal with transformations between your data space and bg-atlasapi, you might find helpful the bg-space package.

Contributing to bg-atlasapi

Contributors to bg-atlaspi are absolutely encouraged, whether you want to fix bugs, add/request new features or simply ask questions.

If you would like to contribute to bg-atlasapi (or any of the downstream tools like brainrender etc.) please get in touch by opening a new issue or pull request on GitHub.

Someone might have already asked a question you might have, so if you're not sure where to start, check out the issues (and the issues of the other repositories)

The BrainGlobe project is generously supported by the Sainsbury Wellcome Centre and the Institute of Neuroscience, Technical University of Munich, with funding from Wellcome, the Gatsby Charitable Foundation and the Munich Cluster for Systems Neurology - Synergy.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bg-atlasapi-1.0.2.tar.gz (206.3 kB view hashes)

Uploaded source

Built Distribution

bg_atlasapi-1.0.2-py3-none-any.whl (197.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page