BEP-038: Atlases (#1714)

Co-authored-by: melanieganz <[email protected]>
Co-authored-by: PeerHerholz <[email protected]>
Co-authored-by: Cyril Pernet <[email protected]>
Co-authored-by: Oscar Esteban <[email protected]>
Co-authored-by: James Kent <[email protected]>
Co-authored-by: melanieganz <[email protected]>
Co-authored-by: Paul Wighton <[email protected]>
Co-authored-by: mnoergaard <[email protected]>
Co-authored-by: Taylor Salo <[email protected]>
Co-authored-by: Mathieu Guay-Paquet <[email protected]>
Co-authored-by: Mark Mikkelsen <[email protected]>
Co-authored-by: Yaroslav Halchenko <[email protected]>

Author: 12 people

mkdocs.yml

@@ -29,6 +29,7 @@ nav:
           - BIDS Derivatives: derivatives/introduction.md
           - Common data types and metadata: derivatives/common-data-types.md
           - Imaging data types: derivatives/imaging.md
+          - Templates and atlases: derivatives/atlas.md
       - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md
       - Glossary: glossary.md
       - BIDS Extension Proposals: extensions.md

src/appendices/coordinate-systems.md

@@ -225,6 +225,13 @@ However, their use is [DEPRECATED][deprecated].
 | fsaverage\[3\|4\|5\|6\|sym\]        | Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image, and registered to an fsaverage template                        | fsaverage\[Sym\]                       |
 | UNCInfant\[0\|1\|2\]V\[21\|22\|23\] | Infant Brain Atlases from Neonates to 1- and 2-year-olds. [https://www.nitrc.org/projects/pediatricatlas](https://www.nitrc.org/projects/pediatricatlas) | UNCInfant                              |
 
+!!! note "Important"
+
+    Please note that the template identifiers starting with `MNI` (for example `MNI305`)
+    are typically referred to with the umbrella term of *MNI Space*.
+    The [Common Principles](../common-principles.md#definitions) deliver a more precise definitions
+    of template, space, and atlas.
+
 ### Nonstandard coordinate system identifiers
 
 The following template identifiers are RECOMMENDED for individual- and study-specific reference

src/common-principles.md

@@ -128,6 +128,12 @@ data type as defined above.
 A data type directory SHOULD NOT be defined if there are no files to be placed
 in that directory.
 
+**Specific structure of derived data**.
+In the case of [storing derived data (see below)](#source-vs-raw-vs-derived-data),
+template (`tpl-<label>`) directories may be found at the root of the dataset,
+and these may include cohort (`cohort-<label>`) subdirectories.
+These directories are described in [Templates and atlases](derivatives/atlas.md).
+
 ### Other top level directories
 
 In addition to the subject directories, the root directory of a BIDS dataset
@@ -297,6 +303,15 @@ However, in the case that these data are to be included:
     through the `sourcedata/` directory mechanism.
     In the case of source data, these aspects are likely more stringent.
 
+**Templates and atlases as derived data.**
+Templates and atlases are key neuroscientific tools to carry out group-level inferences
+and also employed in many atlas-based methodologies (such as atlas-based segmentation).
+Original templates and atlases employed as primary data to the analysis MAY be stored
+within the `sourcedata/atlases/` directory.
+Atlases and artifacts derived from atlases are considered derived data
+and MUST be stored as derivative datasets,
+as described in the next section.
+
 ### Storage of derived datasets
 
 Derivatives can be stored/distributed in two ways:
@@ -332,6 +347,15 @@ Derivatives can be stored/distributed in two ways:
     <dataset>/derivatives/spm-stats/sub-0001
     ```
 
+    Example of an atlas-generating pipeline, including outputs for individual subjects
+    prior to aggregation in the
+    [`MNI152NLin2009cAsym` standard space](appendices/coordinate-systems.md):
+
+    ```Plain
+    <dataset>/derivatives/atlasgenerator/sub-0001
+    <dataset>/derivatives/atlasgenerator/tpl-MNI152NLin2009cAsym
+    ```
+
     Example of a pipeline with nested derivative directories:
 
     ```Plain
@@ -386,11 +410,14 @@ Case 2.
 In both cases, every derivatives dataset is considered a BIDS dataset and must
 include a `dataset_description.json` file at the root level (see
 [Dataset description][dataset-description]).
-Consequently, files should be organized to comply with BIDS to the full extent
+Consequently, files SHOULD be organized to comply with BIDS to the full extent
 possible (that is, unless explicitly contradicted for derivatives).
-Any subject-specific derivatives should be housed within each subject's directory;
-if session-specific derivatives are generated, they should be deposited under a
+Any subject-specific derivatives SHOULD be housed within each subject's directory;
+if session-specific derivatives are generated, they SHOULD be deposited under a
 session subdirectory within the corresponding subject directory; and so on.
+Likewise, any template-specific derivatives SHOULD be housed within each template's directory;
+if cohort-specific derivatives are generated, they SHOULD be deposited under a
+cohort subdirectory within the corresponding template directory; and so on.
 
 ### Non-compliant derivatives