Package: brainglobe-atlasapi
brainglobe-atlasapiThe brainglobe atlas API (brainglobe-atlasapi) provides a common interface for programmers to download and process brain atlas data from multiple sources.Atlases availableA number of atlases are in development, but those available currently are:Allen Mouse Brain Atlasat 10, 25, 50 and 100 micron resolutionsAllen Human Brain Atlasat 100 micron resolutionMax Planck Zebrafish Brain Atlasat 1 micron resolutionEnhanced and Unified Mouse Brain Atlasat 10, 25, 50 and 100 micron resolutionsSmoothed version of the Kim et al. mouse reference atlasat 10, 25, 50 and 100 micron resolutionsGubra's LSFM mouse brain atlasat 20 micron resolution3D version of the Allen mouse spinal cord atlasat 20 x 10 x 10 micron resolutionAZBA: A 3D Adult Zebrafish Brain Atlasat 4 micron resolutionWaxholm Space atlas of the Sprague Dawley rat brainat 39 micron resolution3D Edge-Aware Refined Atlases Derived from the Allen Developing Mouse Brain Atlases(E13, E15, E18, P4, P14, P28 & P56)Princeton Mouse Brain Atlasat 20 micron resolutionKim Lab Developmental CCF (P56)at 10 micron resolution with 8 reference images - STP, LSFM (iDISCO) and MRI (a0, adc, dwo, fa, MTR, T2)Installationbrainglobe-atlasapi works with Python >3.6, and can be installed from PyPI with:pipinstallbrainglobe-atlasapiUsageFull information can be found in thedocumentationPython APIList of atlasesTo see a list of atlases usebrainglobe_atlasapi.show_atlasesfrombrainglobe_atlasapiimportshow_atlasesshow_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 atlasesAll the features of each atlas can be accessed via theBrainGlobeAtlasclass.e.g. for the 25um Allen Mouse Brain Atlas:frombrainglobe_atlasapi.bg_atlasimportBrainGlobeAtlasatlas=BrainGlobeAtlas("allen_mouse_25um")The various files associated with the atlas can then be accessed as attributes of the class:# reference imagereference_image=atlas.referenceprint(reference_image.shape)# (528, 320, 456)# annotation imageannotation_image=atlas.annotationprint(annotation_image.shape)# (528, 320, 456)# a hemispheres image (value 1 in left hemisphere, 2 in right) can be generatedhemispheres_image=atlas.hemispheresprint(hemispheres_image.shape)# (528, 320, 456)Brain regionsThere 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, useatlas.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 1Each brain region can also be access by the acronym, e.g. for primary visual cortex (VISp):frompprintimportpprintVISp=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 inbrainglobe-atlasapiWorking with both image coordinates and cartesian coordinates in the same space can be confusing!
Inbrainglobe-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, inbrainglobe-atlasapithe 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 andbrainglobe-atlasapi, you might find thebrainglobe-spacepackage helpful.Contributing to brainglobe-atlasapiContributors 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 tobrainglobe-atlasapi(or any of the downstream tools likebrainrenderetc.) please get in touch by opening a new issue or pull request onGitHub.
Please also see thedevelopers guide.Someone might have already asked a question you might have, so if you're not sure where to start, check out theissues(and the issues of the other repositories).CitationIf 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.02668Don't forget to cite the developers of the atlas that you used!Atlas Generation and Adding a New AtlasFor full instructions to add a new BrainGlobe atlas, please seehere.Thebrainglobe_atlasapi.atlas_generationsubmodule contains code for the generation of cleaned-up data, for the mainbrainglobe_atlasapimodule.
This code was previously thebg-atlasgenmodule.To contributeFork this repoClone your repoRungit clone https://github.com/brainglobe/brainglobe-atlasapiInstall an editable version of the package; by runningpip install -e .within the cloned directoryCreate a script to package your atlas, and place intobrainglobe_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 thepyproject.tomlfile, e.g.:[project.optional-dependencies]allenmouse=["allensdk"]newatlas=["dependency_1","dependency_2"]