Skip to content

Templates and atlases

In the following, we describe how the outcomes of analyses that produce templates and atlases are organized as BIDS-Derivatives.

Important

For outcomes of analyses corresponding to individual subjects that derive from atlases and may refer to spaces other than the original subject's space, please refer to the Derivatives from atlases subsection.

Derived templates

Many analyses include spatial standardization to pull individuals' data into a common spatial frame. For example, creating an atlas will most likely require the creation of a new template or the integration of existing ones to define a stereotactic space.

For derivatives of template-generating pipelines, which typically aggregate several sessions and/or subjects, the derivatives-specific tpl-<label> entity indicates that the spatial frame of analysis is not defined by a single brain image but an aggregation thereof.

Recommendation

The selected <label> in the tpl-<label> entity is RECOMMENDED for the space-<label> entity in downstream derivatives from this particular template (see previous section Derivatives from atlases).

Template:

<pipeline_name>/
    tpl-<label>/
        [cohort-<label>/]
           [<datatype>/]
               tpl-<label>[_cohort-<label>][_<entities>]_<suffix>.<extension>

where suffix is any valid BIDS suffix such as T1w or PET; and extension is a valid BIDS extension such as nii[.gz], dscalar.nii[.gz], dlabel.nii[.gz], label.gii, tsv, or json. Templates and atlases do not establish new suffixes or extensions, but any valid BIDS/BIDS Derivatives filename is permitted in a template directory, substituting tpl for sub and cohort for ses.

The <datatype>/ directory MAY be omitted in the case only one data type (such as anat/) is stored under the tpl-<label>/ directory.

The cohort-<label> directory and entity MUST be specified for templates with several cohorts.

Dataset structure

In templates/atlases the tpl-<label> and cohort-<label> entities are structurally analogous to the sub-<label> and ses-<label> entities, appearing as both directories and entities. The cohort-<label> entity is used to track mappings of arbitrary subject/session pairs.

In BIDS, a template is considered any aggregation of data and the tpl- entity replaces the subject-level sub- entity when aggregating data across subjects. The tpl- entity and sub- entity are mutually exclusive in a given file. When the tpl- entity is used without the atlas- entity, as in the following examples, the imaging data serves as an instantiation of a space. When the tpl- entity is used in conjunction with the atlas- entity, the intention is to describe aggregations of data in a particular space, as described in the Derived atlases section, below. For uses of the atlas- entity without the tpl- entity, see Imaging derivatives - Derivatives from atlases.

Example: Single-cohort template

For the pipeline that generated MNI152NLin2009cAsym, the outputs could look like the following example:

└─ mni152nlin2009casym-pipeline/
   └─ tpl-MNI152NLin2009cAsym/
      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz 
      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.json 
      ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz 
      ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.json 
      ├─ tpl-MNI152NLin2009cAsym_res-1_probseg.nii.gz 
      ├─ tpl-MNI152NLin2009cAsym_res-1_probseg.json 
      ├─ tpl-MNI152NLin2009cAsym_res-2_T1w.nii.gz 
      ├─ tpl-MNI152NLin2009cAsym_res-2_T1w.json 
      ├─ tpl-MNI152NLin2009cAsym_res-2_label-brain_mask.nii.gz 
      ├─ tpl-MNI152NLin2009cAsym_res-2_label-brain_mask.json 
      ├─ tpl-MNI152NLin2009cAsym_res-2_probseg.nii.gz 
      └─ tpl-MNI152NLin2009cAsym_res-2_probseg.json

Example: Multi-cohort template

In the case that the template-generating pipeline derives several cohorts, the file structure must employ the cohort-<label> directory and entity.

└─ mnipediatricasym-pipeline/
   └─ tpl-MNIPediatricAsym/
      ├─ cohort-1/
      │  ├─ tpl-MNIPediatricAsym_cohort-1_T1w.nii.gz 
      │  ├─ tpl-MNIPediatricAsym_cohort-1_T2w.nii.gz 
      │  ├─ tpl-MNIPediatricAsym_cohort-1_PDw.nii.gz 
      │  ├─ tpl-MNIPediatricAsym_cohort-1_desc-brain_mask.nii.gz 
      │  ├─ tpl-MNIPediatricAsym_cohort-1_probseg.nii.gz 
      │  └─ tpl-MNIPediatricAsym_cohort-1_probseg.json 
      ├─ ... 
      └─ cohort-6/
         ├─ tpl-MNIPediatricAsym_cohort-6_T1w.nii.gz 
         ├─ tpl-MNIPediatricAsym_cohort-6_T2w.nii.gz 
         ├─ tpl-MNIPediatricAsym_cohort-6_PDw.nii.gz 
         ├─ tpl-MNIPediatricAsym_cohort-6_desc-brain_mask.nii.gz 
         ├─ tpl-MNIPediatricAsym_cohort-6_probseg.nii.gz 
         └─ tpl-MNIPediatricAsym_cohort-6_probseg.json

Example: Subject-level and template derivatives

Both subject-level and template-level results MAY coexist in a single derivatives dataset. For example, it is possible to share the subject-level results used to generate the template alongside the template:

└─ mni152nlin2009casym-pipeline/
   ├─ sub-001/
   │  └─ anat/
   │     ├─ sub-001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 
   │     ├─ sub-001_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-001_T1w.nii.gz 
   ├─ ... 
   ├─ sub-152/
   │  └─ anat/
   │     ├─ sub-152_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 
   │     ├─ sub-152_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-152_T1w.nii.gz 
   └─ tpl-MNI152NLin2009cAsym/
      ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz 
      ├─ ... 
      └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json

Warning

Please note that the specification for spatial transforms (BEP 014) is currently under development, and therefore, the specification of transforms files (xfm suffix above) may change in the future.

Derived atlases

An atlas is structured neuroanatomical or neurofunctional information expressed as spatial annotations, such as anatomical landmarks, segmentations, parcellations, probabilistic maps, or feature maps, typically defined in relation to a space engendered by a specific template. Within BIDS, atlases provide standardized spatially-organized knowledge to label, localize, and interpret data features. Atlases often rely on or embed templates as their reference framework. In BIDS, templates establish the spatial coordinate frames for atlases, independently of whether or not they are considered part of specific atlases' outcomes.

Template:

<pipeline_name>/
    atlas-<label>_description.json
    tpl-<label>/
        [cohort-<label>/]
           [<datatype>/]
               tpl-<label>[_cohort-<label>][_<entities>]_<suffix>.<extension>

Atlas identification and metadata

The atlas-<label>_description.json file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators. Atlases MUST include atlas-<label>_description.json files corresponding to the atlas or atlases in the structure.

Recommendation

The selected <label> in the atlas-<label>_description.json file is RECOMMENDED for the atlas-<label> entity in downstream derivatives from this particular atlas (see previous section Derivatives from atlases).

Atlas metadata fields:

Key name Requirement Level Data type Description
Name REQUIRED string Name of the atlas.
License REQUIRED string The license for the dataset. The use of license name abbreviations is RECOMMENDED for specifying a license (see Licenses). The corresponding full license text MAY be specified in an additional LICENSE file.
SampleSize REQUIRED number Number of items (typically, independent participants, although it could also refer, for example, to sessions) that employed to create the corresponding atlas.
Description RECOMMENDED string Free-form natural language description.
Authors RECOMMENDED array of strings List of individuals who contributed to the creation/curation of the dataset.
Curators OPTIONAL array of strings List of curators who helped make the atlas accessible in a database or dataset.
Funding OPTIONAL array of strings List of sources of funding (grant numbers).
ReferencesAndLinks OPTIONAL array of strings List of references to publications that contain information on the dataset. A reference may be textual or a URI.
Species OPTIONAL string The species the atlas was derived from. For example, could be Human, Macaque, Rat, or Mouse.
DerivedFrom OPTIONAL string Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
LevelType OPTIONAL string Indicate what analysis level the atlas was derived from, for example, "group", "individual".
RRID OPTIONAL string Research Resource Identifier of the file, dataset or atlas being described.

Example atlas-MyAtlas2025_description.json:

{
  "Name": "A new atlas of the human brain",
  "Authors": [
    "Jane Doe",
    "John Doe"
  ],
  "License": "CC0",
  "RRID": "SCR_002823",
  "Species": "Human"
}

Atlas spatial reference

Atlases are often aligned to a common spatial reference to allow for the ready application of atlas data. A file may indicate the spatial reference to which it has been aligned using the tpl entity and/or the SpatialReference metadata.

The tpl entity may take any value in Image-Based Coordinate Systems.

If the tpl entity is not in the Standard template identifiers table, then the SpatialReference metadata is REQUIRED for files with that entity.

Example: Deriving templates and atlases

A common use-case of brain templates is establishing stereotaxy for the creation of atlases. For example, the Spatially Unbiased Infratentorial Template (SUIT; Diedrichsen, 2006), presents an atlas template of the human cerebellum and brainstem based on the anatomy of 20 young healthy individuals.

The authors first developed a template of the cerebellum and brainstem, which is spatially standardized in MNI space. This could be the organization of the template part:

└─ suit-pipeline/
   └─ tpl-SUIT/
      └─ anat/
         ├─ tpl-SUIT_T1w.nii.gz 
         └─ tpl-SUIT_T1w.json

Where tpl-SUIT_T1w.json contains (at minimum):

{
  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz"
}

Once the standard space of analysis was prepared, a first atlas was developed in 2009, integrating some segmentations and parcellations:

└─ suit-pipeline/
   ├─ atlas-Diedrichsen2009_description.json 
   └─ tpl-SUIT/
      └─ anat/
         ├─ tpl-SUIT_T1w.nii.gz 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.json 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.nii.gz 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.tsv 
         └─ tpl-SUIT_atlas-Diedrichsen2009_probseg.nii.gz

where atlas-Diedrichsen2009_description.json could contain:

{
  "Name": "A probabilistic MR atlas of the human cerebellum",
  "Authors": [
     "Jörn Diedrichsen",
     "Joshua H Balsters",
     "Jonathan Flavell",
     "Emma Cussans",
     "Narender Ramnani"
  ],
  "SampleSize": 20,
  "License": "LICENSE file",
  "ReferencesAndLinks": [
     "https://doi.org/10.1016/j.neuroimage.2009.01.045",
     "https://github.com/jdiedrichsen/suit"
  ],
  "Species": "Human"
}

Later, in 2011 a second atlas was developed integrating new segmentations, so the template dataset can be updated to contain a second atlas:

└─ suit-pipeline/
   ├─ atlas-Buckner2011_description.json 
   ├─ atlas-Diedrichsen2009_description.json 
   └─ tpl-SUIT/
      └─ anat/
         ├─ tpl-SUIT_T1w.nii.gz 
         ├─ tpl-SUIT_atlas-Buckner2011_dseg.json 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.nii.gz 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.tsv 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-17n_desc-confidence_probseg.nii.gz 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-7n_dseg.nii.gz 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-7n_dseg.tsv 
         ├─ tpl-SUIT_atlas-Buckner2011_seg-7n_desc-confidence_probseg.nii.gz 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.json 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.nii.gz 
         ├─ tpl-SUIT_atlas-Diedrichsen2009_dseg.tsv 
         └─ tpl-SUIT_atlas-Diedrichsen2009_probseg.nii.gz

where atlas-Diedrichsen2009_description.json remains as above, and atlas-Buckner2011_description.json could contain:

{
  "Name": "Atlas of the human cerebellum estimated by intrinsic functional connectivity",
  "Authors": [
     "Randy L Buckner",
     "Fenna M Krienen",
     "Angela Castellanos",
     "Julio C Diaz",
     "B T Thomas Yeo"
  ],
  "SampleSize": 1000,
  "License": "LICENSE file",
  "ReferencesAndLinks": [
     "https://doi.org/10.1152/jn.00339.2011",
     "https://github.com/jdiedrichsen/suit"
  ],
  "Species": "Human"
}

Example: Deriving a new atlas referenced in an existing template

For example, the MIAL67ThalamicNuclei (Najdenovska et al., 2018) atlas-generation pipeline could display the following structure:

└─ mial67thalamicnuclei-pipeline/
   ├─ atlas-MIAL67ThalamicNuclei_description.json 
   ├─ sub-01/
   │  └─ anat/
   │     ├─ sub-01_seg-ThalamicNuclei_dseg.json 
   │     ├─ sub-01_seg-ThalamicNuclei_dseg.tsv 
   │     ├─ sub-01_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-01_T1w.nii.gz 
   ├─ ... 
   ├─ sub-67/
   │  └─ anat/
   │     ├─ sub-67_seg-ThalamicNuclei_dseg.json 
   │     ├─ sub-67_seg-ThalamicNuclei_dseg.tsv 
   │     ├─ sub-67_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-67_T1w.nii.gz 
   └─ tpl-MNI152NLin2009cAsym/
      └─ anat/
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.json 
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv 
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz 
         └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz

where the derivatives of anatomical processing of the 67 subjects that were employed to generate the atlas coexist with the template structure.

The inheritance principle applies uniformly, allowing the segmentation metadata be stored only once at the root of the pipeline directory and apply to all the individual subject segmentations:

└─ mial67thalamicnuclei-pipeline/
   ├─ atlas-MIAL67ThalamicNuclei_description.json 
   ├─ seg-ThalamicNuclei_dseg.json 
   ├─ seg-ThalamicNuclei_dseg.tsv 
   ├─ sub-01/
   │  └─ anat/
   │     ├─ sub-01_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-01_T1w.nii.gz 
   ├─ ... 
   ├─ sub-67/
   │  └─ anat/
   │     ├─ sub-67_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-67_T1w.nii.gz 
   └─ tpl-MNI152NLin2009cAsym/
      └─ anat/
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.json 
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv 
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz 
         └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz

In the case the pipeline generated atlas-based segmentations of the original subjects in their native T1w space (for example, to compare with the original segmentation given by seg-ThalamicNuclei), the above example translates into:

└─ mial67thalamicnuclei-pipeline/
   ├─ atlas-MIAL67ThalamicNuclei_description.json 
   ├─ atlas-MIAL67ThalamicNuclei_dseg.json 
   ├─ atlas-MIAL67ThalamicNuclei_dseg.tsv 
   ├─ seg-ThalamicNuclei_dseg.json 
   ├─ seg-ThalamicNuclei_dseg.tsv 
   ├─ sub-01/
   │  └─ anat/
   │     ├─ sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-01_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-01_T1w.nii.gz 
   ├─ ... 
   ├─ sub-67/
   │  └─ anat/
   │     ├─ sub-67_atlas-MIAL67ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-67_seg-ThalamicNuclei_dseg.nii.gz 
   │     ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz 
   │     └─ sub-67_T1w.nii.gz 
   └─ tpl-MNI152NLin2009cAsym/
      └─ anat/
         ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz 
         └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz

Example: Distributing one atlas aligned to two or more existing templates

This directory structure can be generally applied when the atlas is derived into several template spaces, for example:

└─ mial67thalamicnuclei-pipeline/
   ├─ atlas-MIAL67ThalamicNuclei_description.json 
   ├─ atlas-MIAL67ThalamicNuclei_dseg.json 
   ├─ atlas-MIAL67ThalamicNuclei_dseg.tsv 
   ├─ atlas-MIAL67ThalamicNuclei_probseg.json 
   ├─ tpl-MNI152NLin2009cAsym/
   │  └─ anat/
   │     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz 
   │     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz 
   └─ tpl-MNI152NLin6Asym/
      └─ anat/
         ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz 
         └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz