Atlas Asset Organization¶

Note

Status: DRAFT

This document provides a detailed overview of how brain atlas data assets are organized within an S3 bucket (s3://allen-atlas-assets). It describes directory structure, naming conventions, data access patterns, and governance.

See also

For a history of changes to this specification, see the Changelog.

Core Concepts¶

Atlas¶

A parcellation atlas is a versioned release reference used to guide experiments or deal with the spatial relationship between objects or the location of objects within the context of some anatomical structure. An atlas is minimally defined by a notion of space (either implicit or explicit) and an annotation set. Reference atlases usually have additional parts that make them more useful in certain situations, such as a well-defined coordinate system, delineations indicating the boundaries of various regions or cell populations, landmarks, and labels and names to make it easier to communicate about well-known and useful locations.

Also Known As: parcellation atlas, reference atlas

Practically: a versioned list of references (manifest) to:

One coordinate space
One terminology
One annotation set

For implementation details (structure, naming, manifest schema) see Atlas.

Coordinate Space¶

An anatomical space is versioned release of a mathematical space with a defined mapping between the anatomical axes and the mathematical axes. An anatomical space may be defined by a reference image chosen as the biological reference for an anatomical structure of interest derived from a single or multiple specimens.

Also Known As: anatomical space

Practically: an anatomical origin and physical voxel spacing, usually with a reference image (e.g. the tissuecyte template) that defines it. The defining feature of an anatomical space is its coordinate system. Any images that are at least affine-aligned are in the same anatomical space. The anatomical template that defines the anatomical space can change, resulting in a new version of the anatomical space. Changing the coordinate system (e.g. moving the origin) defines a new space (not a new version of a space).

For implementation details (definition, naming, validation) see Coordinate Space.

Template¶

A reference image that defines or is aligned to a Coordinate Space.

Also Known As: average template, anatomical template

Practically: A reference image. Whether a template is a new revision of an existing template or a new template entirely is primarily about lineage and ease of co-registration. If the measurable differences are local/nonlinear, likely it should be a new revision. If you have to apply a nonlinear transformation, it’s a new template.

For implementation details (files, validation, versioning) see Template.

Annotation Set¶

An anatomical annotation set is a versioned release of a set of anatomical annotations anchored in the same anatomical space that divides the space into distinct segments following some annotation criteria or parcellation scheme. For example, the anatomical annotation set of 3D image based reference atlases (e.g. Allen Mouse CCF) can be expressed as a set of label indices of single multi-valued image annotations or as a set of segmentation masks.

Also Known As: anatomical annotation set, structure masks, structure meshes

Practically: a versioned set of masks and/or meshes that parcellate a specific version of an anatomical space using a specific version of a parcellation terminology. Versions indicate lineage – improvements, additions, or corrections to a previous version of an annotation set.

For implementation details (files, naming, versioning) see Annotation Set.

Terminology¶

A parcellation terminology is a versioned release of a set of terms that can be used to label annotations in an atlas, providing human readability and context and enabling communication about brain locations and structural properties. Typically, a terminology is a set of descriptive anatomical terms following a specific naming convention and/or organizational approach. The terminology may be a flat list (controlled vocabulary), a taxonomy and partonomy, or an ontology (ref: ILX:0777107, RRID:SCR_023499).

Also Known As: parcellation terminology, ontology, structures.csv

Practically: a taxonomy/hierarchy of names and abbreviations that may have corresponding anatomical annotations.

For implementation details (directory layout, file schema, validation rules) see Terminology.

Coordinate Transform¶

One or more concatenated mathematical operations that convert the physical coordinates of one template to another.

Note

This is not part of the existing BICAN data model.

Practically: transforms, including nonlinear warps, defined specifically enough that we can map coordinates between anatomical spaces without secret code.

For implementation details (naming, files, validation rules) see Coordinate Transform.

File Organization¶

The S3 bucket structure is organized as follows:

s3://allen-atlas-assets/
├── atlases/
│   └── <atlas_name>/
│       └── <version>/
│           ├── data_description.json (REQUIRED)
│           └── manifest.json (REQUIRED)
│
├── templates/
│   └── <template_name>/
│       └── <version>/
│           ├── data_description.json (REQUIRED)
│           ├── processing.json (REQUIRED IF COMPUTED)
│           ├── template.ome.zarr (REQUIRED)
│           └── template.nii.gz (OPTIONAL)
│
├── annotation-sets/
│   └── <annotation_set_name>/
│       └── <version>/
│           ├── data_description.json (REQUIRED)
│           ├── masks.ome.zarr (REQUIRED)
│           ├── masks_flat.ome.zarr (OPTIONAL)
│           ├── masks_flat.nii.gz (OPTIONAL)
│           ├── meshes.precomputed (REQUIRED)
│           ├── meshes_smooth.precomputed (OPTIONAL)
│           └── parcellation_volumes.csv (OPTIONAL)
│
├── terminologies/
│   └── <terminology_name>/
│       └── <version>/
│           ├── data_description.json (REQUIRED)
│           ├── terminology.parquet (OPTIONAL)
│           └── terminology.csv (REQUIRED)
│
└── coordinate-transforms/
    └── <template>-<version>_to_<template>-<version>/
        └── <version>/
            ├── data_description.json (REQUIRED)
            ├── processing.json (REQUIRED if computed)
            ├── manifest.json (REQUIRED)
            ├── coordinate_transforms.ome.zarr (OPTIONAL)
            └── <ANTs files> (OPTIONAL)

Metadata¶

All data assets must have a data_description.json file in the top level of the asset folder that is valid according to aind-data-schema.

All computed assets (e.g. some templates) must have a processing.json in the top level of the asset folder that is valid according to aind-data-schema.

See also

For examples of actual atlas assets and their naming, see Example Atlas Assets.