A lightweight python module to interact with atlases for systems neuroscience
Project description
BG-atlasAPI
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:
- The Allen Mouse Brain Atlas at 10, 25 and 50 micron resolutions
- The Allen Human Brain Atlas at 100 micron resolution
- The Max Planck Zebrafish Brain Atlas at 1 micron resolution
- The Enhanced and Unified Mouse Brain Atlas at 25 micron resolution
Installation
BG-AtlasAPI works with Python >3.6, and can be installed from PyPI with:
pip install bg-atlasapi
Usage
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
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
print(reference_image.shape)
# (528, 320, 456)
# annotation image
annotation_image = atlas.annotation
print(annotation_image.shape)
# (528, 320, 456)
# a hemispheres image (value 1 in left hemisphere, 2 in right) can be generated
hemispheres_image = atlas.hemispheres
print(hemispheres_image.shape)
# (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
:
atlas.lookup_df.head(8)
# 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"]
pprint(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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for bg_atlasapi-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fd9fbfb53870b94d07b107d7b72680aa450b34936885516b0b116fae898807f8 |
|
MD5 | 7a1412f2bae55e89f8379c0799eebe5e |
|
BLAKE2b-256 | c986e9bcc8784499ae3bb0fcb4328b7a01ff47eaf6951b3fc365f2ef1fbe60f1 |