From 9390602bd9498957134780ac9e8711e1a7486a91 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 11:32:26 +0200
Subject: [PATCH] enh: address some of @effigies' comments

---
 src/common-principles.md                  | 34 ++++++++++++--
 src/schema/objects/common_principles.yaml | 32 +++++++++++++
 src/schema/objects/entities.yaml          | 55 +++++++++++++++++++----
 src/schema/rules/common_principles.yaml   |  3 ++
 src/schema/rules/directories.yaml         | 13 ++++++
 src/schema/rules/entities.yaml            |  3 ++
 6 files changed, 128 insertions(+), 12 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index f56f420c08..89f007269c 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -122,6 +122,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
@@ -305,6 +311,16 @@ field in `dataset_description.json` of each subdirectory of `derivatives` to:
 }
 ```
 
+**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/` folder, 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:
@@ -340,6 +356,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
@@ -391,11 +416,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
 
diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index 7e669efb52..ec752db4fb 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -3,6 +3,22 @@
 # WARNING: The terms are presented here in alphabetical order!
 # The order in which these terms are presented in the specification is defined in `rules/common_principles.yaml`,
 # rather than this file (`objects/common_principles.yaml`).
+atlas:
+  display_name: Atlas
+  description: |
+    Knowledge about the brain, generally formalized with reference to a standard space (see the *Template* definition)
+    by means of spatiotemporal annotations such as landmarks, segmentations, parcellations, or probability maps.
+
+        The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
+        or quantitative aspects) and metadata (tables, or textual matter).
+        Within BIDS, atlases are broadly defined as a mapping between locations in a spatial coordinate systems
+        and descriptions associated with those locations.
+        Atlases are often built after *registering many subjects or maps into a space defined by a template*.
+        By analogy with geographical atlases, brain atlases can map brain locations to either discrete labels like a map
+        of countries does, or to continuous quantities like a topographic map does.
+
+        One prominent manuscript regarding the specific aspects of atlases, such as their *regional resolution*
+        is ([Bijsterbosch et al., 2020](https://doi.org/10.1038/s41593-020-00726-z)).
 data_acquisition:
   display_name: Data acquisition
   description: |
@@ -133,6 +149,12 @@ session:
     often in the case of some intervention between sessions (for example, training).
     In the [PET](SPEC_ROOT/modality-specific-files/positron-emission-tomography.md) context,
     a session may also indicate a group of related scans, taken in one or more visits.
+space:
+  display_name: Space
+  description: |
+    A reference [coordinate system](appendices/coordinate-systems.md) of analysis
+    engendered by the spatiotemporal distribution of neuroimaging features such as
+    those given by subjects' and templates' data.
 suffix:
   display_name: suffix
   description: |
@@ -154,3 +176,13 @@ task:
     In the context of brain scanning, a task is always tied to one data acquisition.
     Therefore, even if during one acquisition the subject performed multiple conceptually different behaviors
     (with different sets of instructions) they will be considered one (combined) task.
+template:
+  display_name: Template
+  description: |
+    An average feature map obtained by aggregation of subjects and/or sessions that allows the
+    spatial location of brain anatomy and function of the templated cohort.
+    Templates operationalize the concept of *standardized spatial frame of analysis*,
+    a common *Space* in which subjects' data can be spatially-normalized into for group inference.
+    Like subjects' feature maps generate a *native* spatial frame of reference for analyses,
+    templates engender a *generic* or *standard* space of analysis were subjects can be spatiotemporally
+    aligned into.
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index d46bc6b084..cecaf723ba 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -29,14 +29,7 @@ atlas:
   name: atlas
   display_name: Atlas
   description: |
-    The definition of atlas per Merriam-Webster is ‘a bound collection of maps (i.e. labeled brain regions
-    or quantitative aspects) and metadata (tables, or textual matter). Within BIDS, atlases are broadly
-    defined as a mapping between locations in a spatial coordinate systems and descriptions associated with
-    those locations. Atlases are often build from registering many subjects or maps to a template. By analogy
-    with geographical atlases, brain atlases can map brain locations to either discrete labels like a map
-    of countries does, or to continuous quantities like a topographic map does.
-
-    This comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
+    Atlas comprises all possible types of atlases, specifically deterministic, probabilistic, and mask/voxel-based
     ones, and quantitative maps from various modalities including but not limited to structural features (e.g.
     myelination, cytoarchitecture), functional features (e.g. resting-state networks, localizers) and such based on
     multimodal data integration (e.g. gene expression, receptors). Furthermore, it covers both volume/voxel and
@@ -53,6 +46,14 @@ ceagent:
     `"ContrastBolusIngredient"` MAY also be added in the JSON file, with the same label.
   type: string
   format: label
+cohort:
+  name: cohort
+  display_name: Cohort
+  description: |
+    A subset of a defined template space, for instance, for a longitudinal template of brain development
+    where infants were participants were averaged at three, six, and twelve months old.
+  type: string
+  format: label
 chunk:
   name: chunk
   display_name: Chunk
@@ -300,7 +301,33 @@ segmentation:
   display_name: Segmentation
   description: |
     The `seg-<label>` key/value pair corresponds to a custom label the user
-    MAY use to distinguish different segmentations.
+    MAY use to distinguish different segmentations or parcellations.
+
+    For atlases, `seg-<label>` distinguish different realizations of a given
+    segmentation or parcellation.
+    For example, for the [Yeo 2011 atlas](https://doi.org/10.1152/jn.00338.2011)
+    distributed within *FreeSurfer* with two different parcellations
+    (*7 networks* and *17 networks*).
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
+scale:
+  name: scale
+  display_name: Scale
+  description: |
+    The `scale-<label>` key/value pair corresponds to a custom label the user
+    MAY use to distinguish segmentations that entail different levels of
+    *regional resolution* (scales), often indicated by the number of ROIs.
+    See ([Bijsterbosch et al., 2020](https://doi.org/10.1038/s41593-020-00726-z))
+    for further details on *regional resolution* or, as defined by the authors of
+    the manuscript, the *brain units*.
+
+    For example, the [Schaefer 2018 atlas](https://doi.org/10.1093/cercor/bhx179)
+    is distributed within *FreeSurfer* with ten different scales
+    (100, 200, 300, 400, 500, 600, 700, 800, 900, and 1000 regions) for each of
+    its three different parcellations (*7 networks*, *17 networks*, and
+    *Kong's variation of 17 networks*).
 
     This entity is only applicable to derivative data.
   type: string
@@ -412,6 +439,16 @@ task:
     the `task` label for resting state files (for example, `task-rest`).
   type: string
   format: label
+template:
+  name: tpl
+  display_name: Template
+  description: |
+    An standardized space of analysis specified or engendered by one or more average of features
+    with respect to which group-level and atlas-derived results are provided.
+    The `<label>` MAY be taken from one of the modality specific lists in the
+    [Coordinate Systems Appendix](SPEC_ROOT/appendices/coordinate-systems.md).
+  type: string
+  format: label
 tracer:
   name: trc
   display_name: Tracer
diff --git a/src/schema/rules/common_principles.yaml b/src/schema/rules/common_principles.yaml
index 8fac3a813d..2b403817f7 100644
--- a/src/schema/rules/common_principles.yaml
+++ b/src/schema/rules/common_principles.yaml
@@ -11,6 +11,9 @@
 - task
 - event
 - run
+- template
+- atlas
+- space
 - index
 - label
 - suffix
diff --git a/src/schema/rules/directories.yaml b/src/schema/rules/directories.yaml
index db3db194fe..c3c7f943c0 100644
--- a/src/schema/rules/directories.yaml
+++ b/src/schema/rules/directories.yaml
@@ -77,6 +77,12 @@ derivative:
     name: code
     level: optional
     opaque: true
+  cohort:
+    entity: cohort
+    level: optional
+    opaque: false
+    subdirs:
+      - datatype
   derivatives:
     name: derivatives
     level: optional
@@ -106,6 +112,13 @@ derivative:
     opaque: false
     subdirs:
       - datatype
+  template:
+    entity: template
+    level: optional
+    opaque: false
+    subdirs:
+      - cohort
+      - datatype
   datatype:
     value: datatype
     level: optional
diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index 2194a61a92..92f074b2a4 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -2,7 +2,9 @@
 # This file simply defines the order in which entities should appear within filenames.
 # Entity definitions appear in the `objects/entities.yaml` file.
 - subject
+- template
 - session
+- cohort
 - sample
 - task
 - tracksys
@@ -26,6 +28,7 @@
 - recording
 - chunk
 - segmentation
+- scale
 - resolution
 - density
 - label