Spaces, templates, and atlas alignment

Unlike a preprocessing pipeline, BDT and BAT do not resample data into a list of user-requested output spaces. Instead, they apply atlases to data that is already in some space, and the central spatial concern is bringing an atlas and the data it is applied to into a shared coordinate space.

  • BDT parcellates a derivative (BOLD, CBF, a scalar map, a tractogram, a diffusion model) using an atlas. The atlas and the data must be aligned first; see Aligning atlases and data below and Processing pipeline details for the transform system.

  • BAT combines atlases with atlas algebra. All inputs to a given BAT operation must share the same template (tpl-) space, and the output inherits that space (see Outputs of BDT and BAT).

Every atlas-derived output carries a space- entity recording the coordinate system the parcellation ran in; it is REQUIRED (see Outputs of BDT and BAT).

TemplateFlow

TemplateFlow is a software library and a repository of neuroimaging templates and atlases that lets applications such as BDT flexibly query and pull template and atlas information. It is how BDT accesses standard template spaces and the standard-to-standard transforms used to move atlases between them, and it is where custom templates can be registered (see below). For more general information about TemplateFlow, visit TemplateFlow.org.

Standard spaces

Standard, stereotactic template spaces are identified by the same space-/tpl- identifiers used throughout BIDS and TemplateFlow — for example MNI152NLin6Asym, MNI152NLin2009cAsym, or a surface space such as fsLR or fsaverage. Valid identifiers come from the TemplateFlow repository.

Atlases in a BIDS Atlas dataset live in a template space (tpl-), and derivatives carry a space- entity for the space they were resampled to upstream. BDT uses the transform graph (below) to reconcile the two.

Nonstandard spaces

Derivatives are not always in a standard template space. BDT treats subject-native and intermediate spaces as ordinary nodes in its transform graph, including, for example:

  • T1w / anat — the individual’s anatomical reference.

  • fsnative — the individual’s FreeSurfer surface reconstruction.

  • boldref / sbref — a BOLD run’s own reference grid.

  • ACPC / native diffusion space — common for QSIRecon tractography and diffusion-model outputs.

BDT does not require these to be pre-aligned to the atlas; it only requires that a transform path exists between the data’s space and the atlas’s space (see below).

Aligning atlases and data

BDT discovers transforms automatically from the *_xfm.* files in the provided derivative datasets and supplements them with TemplateFlow standard-to-standard transforms, assembling a graph whose nodes are spaces and whose edges are transforms. The direction in which data and atlases are moved depends on the geometry of the data:

  • Grid data (volumetric NIfTI, CIFTI dense) — the atlas is warped into the data’s grid once, so signal is never re-interpolated.

  • Point data (GIFTI vertices, TRX/TCK streamlines) — the points (or atlas vertices) are warped, which is lossless.

  • Diffusion-model grid (SH/ODF/fixels) — resampled like grid data, plus SH reorientation.

See Processing pipeline details for the full description of the geometry-aware transform system and per-format dispatch.

Note

BDT is strict rather than heuristic about alignment: if no transform path exists between an atlas’s space and the data’s space, it raises an explicit error naming both spaces and listing the spaces available in the graph, rather than guessing.

Custom standard spaces

To make a custom template or atlas space visible to BDT, store it under TemplateFlow’s home directory. The default is $HOME/.cache/templateflow, which can be changed by setting the $TEMPLATEFLOW_HOME environment variable. A minimal example of the files needed for a template called MyCustom follows:

$TEMPLATEFLOW_HOME/
    tpl-MyCustom/
        template_description.json
        tpl-MyCustom_res-1_T1w.nii.gz
        tpl-MyCustom_res-1_desc-brain_mask.nii.gz
        tpl-MyCustom_res-2_T1w.nii.gz
        tpl-MyCustom_res-2_desc-brain_mask.nii.gz

For further information about how custom templates must be organized and named, please check the TemplateFlow tutorials.

Note

The res- (resolution) entity of TemplateFlow is an index, not a voxel size: res-2 does not necessarily mean 2 mm3. The mapping from index to physical resolution is defined per template in its template_description.json.