Merge pull request #1856 from oesteban/bep038-review

Alternative proposal to BEP038

Author: effigies

mkdocs.yml

@@ -24,8 +24,8 @@ 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
-      - Atlases: atlas.md
       - Glossary: glossary.md
       - BIDS Extension Proposals: extensions.md
       - Appendix:

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/atlas.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),
+the subject (`sub-<label>`) and session (`ses-<label>`) entities MAY map onto
+the template (`tpl-<label>`) and cohort (`cohort-<label>`) entities
+as described in the [corresponding section](derivatives/atlas.md) of this specification.
+
 ### Other top level directories
 
 In addition to the subject directories, the root directory of a BIDS dataset
@@ -340,6 +346,16 @@ field in `dataset_description.json` of each subdirectory of `derivatives` to:
     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/`.
+Any artifacts deriving from atlases, or the creation of new templates and atlases MUST
+follow the [corresponding specification](derivatives/atlas.md) and stored under the
+`derivatives/` directory, and follow the general specifications for derivatives regarding
+storage and distribution, as described in the next section.
+
 ### Storage of derived datasets
 
 Derivatives can be stored/distributed in two ways:
@@ -375,6 +391,15 @@ Derivatives can be stored/distributed in two ways:
     <dataset>/derivatives/spm-stats/sub-0001
     ```
 
+    Example of an atlas-generating pipeline with outputs for individual subjects
+    and the aggregation in an atlas defined with respect to the widely-used
+    [`MNI152NLin2009cAsym` standard space](appendices/coordinate-systems.md):
+
+    ```Plain
+    <dataset>/derivatives/atlas-generator/sub-0001
+    <dataset>/derivatives/atlas-generator/tpl-MNI152NLin2009cAsym
+    ```
+
     Example of a pipeline with nested derivative directories:
 
     ```Plain
@@ -427,11 +452,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