• Stars
    star
    125
  • Rank 286,335 (Top 6 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created over 4 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A lightweight python module to interact with atlases for systems neuroscience

brainglobe-atlasapi

Python Version PyPI Wheel Development Status Downloads Tests codecov Code style: black Imports: isort pre-commit DOI License Contributions Website Twitter

The brainglobe atlas API (brainglobe-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:

Installation

brainglobe-atlasapi works with Python >3.6, and can be installed from PyPI with:

pip install brainglobe-atlasapi

Usage

Full information can be found in the documentation

Python API

List of atlases

To see a list of atlases use brainglobe_atlasapi.show_atlases

from brainglobe_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 brainglobe_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 brainglobe-atlasapi

Working with both image coordinates and cartesian coordinates in the same space can be confusing! In brainglobe-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 brainglobe-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 brainglobe-atlasapi, you might find the brainglobe-space package helpful.

Contributing to brainglobe-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 brainglobe-atlasapi (or any of the downstream tools like brainrender etc.) please get in touch by opening a new issue or pull request on GitHub. Please also see the developers guide.

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

Citation

If you find the BrainGlobe Atlas API useful, please cite the paper in your work:

Claudi, F., Petrucco, L., Tyson, A. L., Branco, T., Margrie, T. W. and Portugues, R. (2020). BrainGlobe Atlas API: a common interface for neuroanatomical atlases. Journal of Open Source Software, 5(54), 2668, https://doi.org/10.21105/joss.02668

Don't forget to cite the developers of the atlas that you used!


Atlas Generation and Adding a New Atlas

For full instructions to add a new BrainGlobe atlas, please see here.

The brainglobe_atlasapi.atlas_generation submodule contains code for the generation of cleaned-up data, for the main brainglobe_atlasapi module. This code was previously the bg-atlasgen module.

To contribute

  1. Fork this repo
  2. Clone your repo
  3. Run git clone https://github.com/brainglobe/brainglobe-atlasapi
  4. Install an editable version of the package; by running pip install -e . within the cloned directory
  5. Create a script to package your atlas, and place into brainglobe_atlasapi/atlas_generation/atlas_scripts. Please see other scripts for examples.

Your script should contain everything required to run. The raw data should be hosted on a publicly accessible repository so that anyone can run the script to recreate the atlas.

If you need to add any dependencies, please add them as an extra in the pyproject.toml file, e.g.:

[project.optional-dependencies]
allenmouse = ["allensdk"]
newatlas = ["dependency_1", "dependency_2"]

More Repositories

1

brainrender

a python based software for visualization of neuroanatomical and morphological data.
Python
540
star
2

cellfinder

Automated 3D cell detection in very large images
Python
179
star
3

brainreg

Automated 3D brain registration with support for multiple species and atlases.
Python
121
star
4

slicereg

A 2D-3D histological brain slice registration application for mouse, rat, zebrafish brains.
Python
37
star
5

brainglobe-heatmap

Rendering anatomical heatmaps with brainrender and matplotlib
Python
34
star
6

brainglobe-segmentation

Segmentation of anatomical structures in a common coordinate space
Python
28
star
7

cellfinder-napari

Efficient cell detection in large images using cellfinder in napari
Python
24
star
8

cellfinder-core

Standalone cellfinder cell detection algorithm
Python
19
star
9

brainrender-napari

A napari plugin to render BrainGlobe atlases and associated data as layers.
Python
19
star
10

morphapi

A lightweight python package to download neuronal morphologies
Python
17
star
11

brainreg-napari

Automated 3D brain registration in napari with support for multiple species and atlases.
Python
14
star
12

brainglobe-napari-io

Read and write files from the BrainGlobe neuroanatomy suite
Python
13
star
13

brainglobe-registration

Registration to BrainGlobe atlases in napari using Elastix
Python
13
star
14

bg-brainrender-gui

A GUI built on brainrender: visualise brain regions, neurons and labelled cells.
Python
12
star
15

bg-atlasgen

Tools for packaging atlases for use with BrainGlobe
Python
12
star
16

brainglobe-utils

Shared general purpose tools for the BrainGlobe project
Python
11
star
17

brainrender_paper

Code for recreating the figures in the brainrender paper (Claudi et al. 2020)
Python
11
star
18

probeplanner

Helps plan where to put things in brains
Python
10
star
19

BrainGlobe

General information, resources and dicussions for the BrainGlobe project.
10
star
20

brainglobe-meta

(Meta-)package repository for BrainGlobe's Python tools for computational neuroanatomy.
Python
10
star
21

brainglobe.github.io

brainglobe.info website
Python
10
star
22

imio

Loading and saving of image data.
Python
10
star
23

napari-brainreg

Visualise brainreg registration output
Python
10
star
24

cellfinder-visualize

Python
9
star
25

bgviewer

Visualisation and exploration of brain atlases
Python
9
star
26

brainrender-docs

CSS
9
star
27

brainglobe-workflows

Workflows that utilise BrainGlobe tools to perform data analysis and visualisation.
Python
9
star
28

brainglobe-template-builder

Build unbiased anatomical templates from individual images
Python
8
star
29

napari-cellfinder

Python
8
star
30

brainglobe-space

Anatomical space conventions made easy.
Python
8
star
31

bg-gitbook

Mirror of the brainglobe GitBook page
7
star
32

napari-brainreg-standard

Visualise brainreg registration output in standard space
Python
7
star
33

actions

Re-usable GitHub Action scripts
6
star
34

brainglobe-web

brainglobe.info website
HTML
6
star
35

brainglobe-stitch

A napari plugin for stitching large tiled 3D imaging datasets
Python
6
star
36

.github

Common templates for BrainGlobe repositories.
6
star
37

course-dec-2023

Materials for the BrainGlobe & napari course at the Sainsbury Wellcome Centre
JavaScript
6
star
38

slides-roadmap-oct-2023

SCSS
4
star
39

napari-experimental

Python
2
star
40

micrometa

Parsing of whole-brain microscopy metadata
Python
1
star