A package for working with brain atlases.

For examples and tutorials on using the IBL atlas package, see https://docs.internationalbrainlab.org/atlas_examples.html


There are many terms used somewhat incoherently within this API and the community at large. Below are some definitions of the most common terms.

  • Atlas - A set of serial sections along different anatomical planes of a brain where each relevant brain structure is assigned a number of coordinates to define its outline or volume. An atlas essentially comprises a set of images, annotations, and a coordinate system.

  • Annotation - A set of identifiers assigned to different atlas regions.

  • Mapping - A function that maps one ordered list of brain region IDs to another, allowing one to control annotation granularity and brain region hierarchy, or to translate brain region names from one atlas to another. The default mapping is identity.

  • Coordinate framework - The way in which an atlas translates image coordinates (e.g. Cartesian or sperical coordinates) to real-world anatomical coordinates in (typically physical distance from a given landmark such as bregma, along three axes, ML-AP-DV).

  • Reference space - The coordinate system and annotations used by a given atlas. It is sometimes useful to compare anatomy between atlases, which requires expressing one atlas in another’s reference space.

  • Structure tree - The hirarchy of brain regions, handled by the BrainRegions class.

  • Scaling - Atlases typically comprise images averaged over a number of brains. Scaling allows one to account for any consistent and measurable imgaging or tissue distortion, or to better align to an individual brain of a specific size. The default scaling is identity.

  • Flat map - An annotated projection of the 3D brain to 2D.

  • Slice - A 2D section of a brain atlas volume. Typically these are coronal (cut along the medio-lateral axis), sagittal (along the dorso-ventral axis) or transverse a.k.a. axial, horizontal (along the rostro-caudal a.k.a. anterio-posterior axis).


There are two principal mouse brain atlases in this module:

  1. The Allen Common Coordinate Framework (CCF) [1].

  2. The Mouse Brain in Stereotaxic Coordinates (MBSC) 4th Edition, by Paxinos G, and Franklin KBJ [2], matched to to the Allen Common Coordiante Framework by Chon et al. [3].

The latter is referred to here as the ‘Franklin-Paxinos atlas’. These atlases comprise a 3D array of voxels and their associated brain region identifiers (labels) at a given resolution. The Allen Atlas can be instantiated in 10um, 25um or 50um resolution. The Franklin-Paxinos atlas has a resolution of 10um in the ML and DV axis, and 100um in the AP axis. TODO Mention flat maps.


Additionally there are two further atlases that apply some form of scaling to the Allen CCF atlas to account for distortion that occurs during the imaging and tissue fixation process:

  1. The Needles atlas - 40 C57BL/6J (p84) mice underwnt MRI imaging post-mortem while the brain was still in the skull, followed by conventional Nissl histology [4]. These mouse brain atlas images combined with segmentation (known as DSURQE) were manually transformed onto the Allen CCF atlas to determine the scaling.

  2. The MRI Toronto - 12 p65 mice MRI images were taken in vivo then averaged and transformed on the Allen CCF atlas to determine the scaling [5].

All scaling is currently linear. Scaling of this kind can be applied arbitrarily to better represent a specific mouse age and sex [5]. NB: In addition to distortions, the Allen CFF atlas is pitched down by about 5 degrees relative to a flat skull (where bregma and lambda are at the same DV height) [6], however this is not currently accounted for.

Brain Regions Mappings

The Allen CCF ontology regroups brain regions in a hierarchical manner, with up to 9 levels of parcellation. The labels volumes provided by the Allen Institute are at the finest level of parcellation, ie. leaf nodes. However it is often useful to regroup regions at higher levels of the hierarchy for aggregation purposes. The mappings represent the correspondence between the leaf nodes and their grouping for given analysis purposes. This is useful for:

  1. control the granularity particular brain regions;

  2. support differing anatomical sub-devisions or nomenclature.

The two Allen atlas mappings below were created by Nick Steinmetz to aid in neural analysis:

  1. Beryl - brain atlas annotations without layer sub-divisions or certain ganglial/nucleus sub-devisisions (e.g. the core/shell sub-division of the lateral geniculate nucleus). Fibre tracts, pia, etc. are also absent. The choice of which areas to combine was guided partially by the computed volume of each area. This mapping is used in the brainwide map and prior papers [7], [8] .

  2. Cosmos - coarse brain atlas annotations, dividing the atlas into 10 broad areas: isocortex, olfactory areas, cortical subplate, cerebral nuclei, thalamus, hypothalamus, midbrain, hindbrain, cerebellum and hippocampal formation.

The names of these two mappings appear to be without meaning.

Non-Allen mappings:

  1. Swanson - the brain atlas annotations from the Swansan rat brain flat map [9], mapped to the Allen atlas manually by Olivier Winter. See Fixtures for details.

Each mapping includes both a lateralized (suffix ‘-lr’) and non-laterized version. The lateralized mappings assign a different ID to structures in the right side of the brain. The Allen atlas IDs are kept intact but lateralized as follows: labels are duplicated and IDs multiplied by -1, with the understanding that left hemisphere regions have negative IDs. There is currently no mapping between Franklin & Paxinos and the Allen atlases.


The Allen atlas and the CCF annotations have different release dates and versions [10]. The annotations used by IBL are the 2017 version (CCFv2).

The IBL uses the following conventions:

  • All atlas images have dimensions (AP, ML, DV). With C-ordering this makes coronal slicing most efficient. The origin is the top left corner of the image.

  • Coordinates are provided in the order (ML AP DV) and are in meters relative to bregma.

  • Left hemisphere ML coordinates are -ve; right, +ve.

  • AP coordinates anterior to bregma are +ve; posterior, -ve.

  • DV coordinates ventral to bregma are -ve; ventral +ve.

  • Bregma was determined by asking five experimentalists to pick the voxel containing bregma on the Allen atlas and taking the average. NB: The midline appears slightly off-center in the Allen atlas image volume.

  • All left hemisphere regions have negative region IDs in all lateralized mappings.


Below are some brief API examples. For in depth tutorials on using the IBL atlas package, see https://docs.internationalbrainlab.org/atlas_examples.html.

Find bregma position in indices * resolution in um

>>> ba = AllenAtlas()
>>> bregma_index = ALLEN_CCF_LANDMARKS_MLAPDV_UM['bregma'] / ba.res_um

Find bregma position in xyz in m (expect this to be 0 0 0)

>>> bregma_xyz = ba.bc.i2xyz(bregma_index)


Local files

  • allen_structure_tree.csv - TODO Document. Where does this come from? Is it modified from either structure_tree_safe.csv or structure_tree_safe_2017.csv?

  • franklin_paxinos_structure_tree.csv - Obtained from Supplementary Data 2 in reference [10].

  • beryl.npy - A 306 x 1 int32 array of Allen CCF brain region IDs generated in MATLAB [*]. See more information see `Mappings`_.

  • cosmos.npy - A 10 x 1 int32 array of Allen CCF brain region IDs generated in MATLAB []. See more information see `Mappings`_.

  • swanson_regions.npy - A 1D array of length 323 containing the Allen CCF brain region IDs

  • mappings.pqt - A table of mappings. Each column defines a mapping, with the ‘-lr’ suffix indicating a lateralized version. The rows contain the correspondence of each mapping to the int64 index of the lateralized Allen structure tree. The table is generated by iblatlas.regions.BrainRegions._compute_mappings.

Remote files

  • annotation_<res_um>.nrrd - A 3D volume containing indicies of the regions in the associated structure tree. res_um indicates the isometric spacing in microns. These uint16 indicies are known as the region ‘index’ in the structure tree, i.e. the position of the region in the flattened tree.

  • average_template_<res_um>.nrrd - TODO Document

  • annotation_<res_um>_lut_<LUT_VERSION>.npz - TODO Document

  • FranklinPaxinons/annotation_<res_um>.npz - A 3D volume containing indices of the regions associated with the Franklin- Paxinos structure tree.

  • FranklinPaxinons/average_template_<res_um>.npz - A 3D volume containing the Allen dwi image slices corresponding to the slices in the annotation volume [*] .

  • swansonpaths.json - The paths of a vectorized Swanson flatmap image [*]. The vectorized version was generated from the Swanson bitmap image using the matlab contour function to find the paths for each region. The paths for each region were then simplified using the Ramer Douglas Peucker algorithm

  • swanson2allen.npz - TODO Document who made this, its contents, purpose and data type

  • <flatmap_name>_<res_um>.nrrd - TODO Document who made this, its contents, purpose and data type



Classes for manipulating brain atlases, insertions, and coordinates.


Techniques to project the brain volume onto 2D images for visualisation purposes.


A package for working with Allen genomics datasets: AGEA and MERFISH.


Module that has convenience plotting functions for 2D atlas slices and flatmaps.


Brain region mappings.