From 4fa15e57eed2b243b71c6d16d2b2a02fdfa7ff12 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 12 Jun 2024 17:06:12 -0400
Subject: [PATCH 01/47] first iteration of the alternative proposal

---
 mkdocs.yml                           |   2 +-
 src/atlas.md                         | 672 ---------------------------
 src/derivatives/atlas.md             | 477 +++++++++++++++++++
 src/derivatives/common-data-types.md |   2 +-
 src/derivatives/imaging.md           |   2 +-
 5 files changed, 480 insertions(+), 675 deletions(-)
 delete mode 100644 src/atlas.md
 create mode 100644 src/derivatives/atlas.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 339a3d5a57..5a4fb2c150 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,8 +23,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:
diff --git a/src/atlas.md b/src/atlas.md
deleted file mode 100644
index 6a2297b97f..0000000000
--- a/src/atlas.md
+++ /dev/null
@@ -1,672 +0,0 @@
-# BIDS-Atlas
-
-In the following we describe how an [atlas](schema/objects/entities.yaml#atlas) can be shared within BIDS.
-We describe a broad set of atlases and use cases thereof.
-
-More specifically, this entails providing and referring to existing atlas datasets,
-describing atlases that were newly derived within an analysis,
-and providing information for derivatives that were obtained through them.
-The first would comprise (publicly) available atlases, for example,
-Destrieux et al. ([doi.org/10.1016/j.neuroimage.2010.06.010](https://doi.org/10.1016/j.neuroimage.2010.06.010)),
-AAL ([doi.org/10.1006/nimg.2001.0978](https://doi.org/10.1006/nimg.2001.0978)),
-Yeo ([doi.org/10.1152/jn.00338.2011](https://doi.org/10.1152/jn.00338.2011))
-and JHU DTI-based white-matter atlases
-([eBook ISBN: 9780080456164](https://shop.elsevier.com/books/mri-atlas-of-human-white-matter/mori/978-0-444-51741-8)
-and [doi.org/10.1016/j.neuroimage.2007.07.053](https://doi.org/10.1016/j.neuroimage.2007.07.053)),
-while the second would include atlases obtained through analyses within a dataset at hand,
-for example, resting-state networks and functional localizers.
-Importantly, the latter can also be utilized as existing atlases if made available.
-The third would entail referencing an atlas and its properties used to derive,
-for example, a parcellated time series or a connectivity matrix.
-
-## Atlas as new DatasetType
-Here we introduce an additional value to the `DatasetType field` of `dataset_description.json`.
-If a dataset declares its DatasetType to be [atlas](schema/objects/entities.yaml#atlas),
-the top-level directories MUST be `atlas-` instead of `sub-`.
-This will allow sharing existing atlases as stand-alone datasets,
-validating them via the [BIDS validator](https://github.com/bids-standard/bids-validator) and enabling their integration as sub-datasets of other BIDS datasets.
-
-## File formats for the raw data
-BIDS-Atlas aims to describe brain atlases via three REQUIRED files.
-They entail the atlas itself (for example, in .nii, .nii.gz, .gii, or .tsv),
-a file indexing/labeling each node in the atlas (in .tsv) and a file containing exhaustive meta-data about the atlas (in .json).
-
-The usage of [_desc-](schema/objects/entities.yaml#desc) is generally discouraged but should be evaluated on a case by case basis in order to keep this identifier available for necessary cases.
-Specifically, this refers to the atlas at hand and potential different versions thereof.
-As a rule of thumb, BIDS-Atlas proposed to evaluate and consider how many versions across how many levels of versions an atlas is (commonly) provided and used in.
-If there is only one version, as in "release", of an atlas
-and no sub-versions, as in "different parcel numbers" (or comparable),
-[_desc-](schema/objects/entities.yaml#desc) is most likely not expected and/or required.
-An example for [_desc-](schema/objects/entities.yaml#desc) in such a use case would be
-to indicate a subset of parcels and would entail the addition of
-the [_mask-](schema/objects/entities.yaml#mask) extension,
-for example, providing/using the "postcentral gyrus" region of the [Destrieux atlas](doi:10.1093/cercor/bhg087.) would result in the following file name:
-`atlas-Destrieux_space-MNI152NLin6Asym_res-2_desc-PostCentralGyrus_mask.nii.gz`.
-Similar to the above case, if there are multiple versions, as in "release",
-of an atlas and no sub-versions, as in "different parcel numbers" (or comparable),
-[_desc-](schema/objects/entities.yaml#desc) is also most likely not expected and/or required,
-as the version(s) (release(s)) should be indicated via `atlas-`.
-For example, the different versions of the [AAL parcellation](http://www.gin.cnrs.fr/AAL-217?lang=en)
-would result in the following file names:
-`atlas-AAL1_space-MNI152NLin6Asym_res-2.nii.gz`, `atlas-AAL2_space-MNI152NLin6Asym_res-2.nii.gz` and `atlas-AAL3_space-MNI152NLin6Asym_res-2.nii.gz`.
-Given an atlas has only one version, as in "release", and multiple sub-versions
-as in "different parcel numbers" (or comparable)
-[_desc-](schema/objects/entities.yaml#desc) is considered appropriate.
-For example, when indicating information pertaining to the probabilistic nature of an atlas
-such as the [_probseg](schema/objects/entities.yaml#probseg) version of
-the [Harvard-Oxford parcellation](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases):
-`atlas-HarvardOxford_res-2_desc-th25_probseg.nii.gz`.
-In cases where an atlas has multiple versions, as in "release", and sub-versions,
-as in "different parcel numbers" (or comparable),
-the version(s) (release(s)) should be indicated via `atlas-` as outlined above and the sub-versions should be indicated via [_desc-](schema/objects/entities.yaml#desc).
-For example, different versions and sub-versions of the [Schaefer parcellation](https://github.com/ThomasYeoLab/CBIG/blob/master/stable_projects/brain_parcellation/Schaefer2018_LocalGlobal/Parcellations/Updates/Update_20190916_README.md) would be denoted as follows:
-`atlas-Schaefer2018_space-MNI152NLin6Asym_res-2_desc-400Parcels7Networks.nii.gz`,
-`atlas-Schaefer2018_space-MNI152NLin6Asym_res-2_desc-400Parcels17Networks.nii.gz`,
-`atlas-Schaefer2022_space-MNI152NLin6Asym_res-2_desc-800Parcels7Networks.nii.gz`
-and `atlas-Schaefer2022_space-MNI152NLin6Asym_res-2_desc-800Parcels17Networks.nii.gz`.
-
-Importantly, already existing BIDS entities should be used to indicate certain aspects of an atlas,
-instead of [_desc-](schema/objects/entities.yaml#desc), for example,
-[hemi](schema/objects/entities.yaml#hemi) to denote a given hemisphere
-and [_dseg](schema/objects/entities.yaml#dseg)/[_probseg](schema/objects/entities.yaml#probseg)
-to denote deterministic and probabilistic atlases respectively.
-
-However, as mentioned above, these are general guidelines and the exact implementation should be evaluated on a case by case basis, with deviations following common BIDS principles being permitted.
-
-## Directory Structure
-BIDS-Atlas focuses on the utilization of atlases while also allowing their sharing.
-Thus, atlases are either stored within a dedicated `atlas` directory at the BIDS root directory
-(comparable to the `code` directory),
-such files are the non-altered/original atlases or within a given directory under `derivatives`.
-In the second case, atlases are altered,
-derived or applied and thus multiple use cases have to be distinguished as indicated further below.
-
-### Representing an atlas as a dataset
-
-The first option refers to atlases that were not altered, for example,
-via spatial transformations and/or resampling or applied to data
-and thus their initial inclusion/utilization in a given dataset.
-If there is only this form of atlases (that is, the tool used),
-they are always shared at the root directory and everything else is under derivatives.
-This allows validating any
-
-```Text
-<dataset>/atlas/
-```
-
-using the  [BIDS validator](https://github.com/bids-standard/bids-validator).
-Importantly, only this case follows the same directory structure as
-[sub](schema/objects/entities.yaml#sub), that is, one dedicated directory for each atlas within a given dataset.
-The default way of storage of the non-altered atlas at the root directory looks like this:
-
-```Text
-<dataset>/atlas/atlas-<label>/
-  atlas-<label>_space-<label>[_desc-<label>]_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
-```
-
-### Representing an atlas within a dataset
-
-Besides this default and required storage of the non-altered atlas at the root directory, the second use case provides three sub-cases to store atlases that were either altered, applied, or derived within a given dataset.
-While case 1 uses the [atlas](schema/objects/entities.yaml#atlas) identifier, case 2 and 3 use the [seg](schema/objects/entities.yaml#seg) identifier.
-The difference between the use of [atlas](schema/objects/entities.yaml#atlas) and [seg](schema/objects/entities.yaml#seg) identifier is that in the first case an existing atlas is changed, for example, transformed, but still remains an atlas.
-In the other case, the atlas is used to define a segmentation, for example, the AAL atlas is used to define a cortical parcellation, that then is applied to a subjects other content, for example, a cortical thickness or binding potential map.
-
-#### Case 1
-
-First, a given atlas underwent modifications before its utilization,
-specifically spatial transformations to a template space and is used in this form within a given pipeline.
-In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and the given pipeline directory under `derivatives`.
-Files stored at the BIDS root level will follow the structure outlined in option 1,
-while files stored at the pipeline level will follow the respective naming conventions.
-For example, if an atlas was spatially transformed to a certain MNI template,
-then the BIDS-Atlas files will be stored within the respective pipeline directory and the corresponding [space](schema/objects/entities.yaml#space)-<label> identifier will be adapted accordingly.
-
-```Text
-<dataset>/atlas/atlas-<label>/
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].json
-
-<dataset>/derivatives/<pipeline>/
-  atlas-<label>_space-<label>_res-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|.tsv][.gz]
-  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].tsv
-  atlas-<label>_space-<label>_desc-<label>_[dseg|probseg|mask].json
-```
-
-#### Case 2
-
-Second, a given atlas underwent modifications before its utilization,
-specifically spatial transformations to an individual subject space and is used in this form.
-In this case, the respective BIDS-Atlas files will be stored at both the BIDS root level and at the given subject level under `derivatives`.
-Files stored at the BIDS root level will follow the structure outlined in option 1.
-Files stored at the subject level now use the [seg](schema/objects/entities.yaml#seg) entity with it's value referring to the atlas use on a given file.
-
-```Text
-<dataset>/atlas/atlas-<label>/
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii][.gz]
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-  atlas-<label>_desc-<label>_[dseg|probseg|mask].json
-
-<dataset>/derivatives/
-  sub-01/
-    func/
-      sub-01_space-<label>_seg-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz]
-      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].tsv
-      sub-01_space-<label>_seg-<label>_desc-<label>_[dseg|probseg|mask].json
-```
-
-#### Case 3
-
-Third, a given atlas was derived from the corresponding subject’s data and thus is subject-specific.
-In this case, the `atlas` directory at the root of the dataset does not exist.
-The subject specific atlas filenames are the same as in case 2 at the subject level within the modality directory of the data the atlas was derived from.
-Optionally, a `*_coordsystem.json` file that specifies the
-[Image-based Coordinate System](/appendices/coordinate-systems.md) of the subject-specific atlas can be used for,
-for example, an histological atlas/segmentation.
-Unlike as in the prior use case, the [atlas](schema/objects/entities.yaml#atlas) identifier will be replaced with the [seg](schema/objects/entities.yaml#seg) identifier.
-
-```Text
-<dataset>/derivatives/
-  sub-01/
-    anat/
-      sub-01_atlas-<label>_[dseg|probseg|mask].[nii|dscalar.nii|dlabel.nii|label.gii|tsv][.gz][.ome-tiff|.png]
-      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].tsv
-      sub-01_atlas-<label>_desc-<label>_[dseg|probseg|mask].json
-      sub-01_atlas-<label>_desc-<label>_coordsystem.json
-```
-
-### Representing locations in an atlas file
-
-The `[probseg|dseg|mask].[nii|dlabel.nii|label.gii][.gz]` file represents the location and extent of the nodes/parcels/regions within the atlas.
-Different file types are supported based on the modality and atlas at hand.
-In more detail, this encompasses the following three options:
-
-1. [_dseg](schema/objects/suffixes.yaml#dseg): Each node is labeled with a unique integer corresponding to its row/index in the tsv sidecar.
-1. [_probseg](schema/objects/suffixes.yaml#probseg): Each node is represented along an additional dimension of the file (for example, a 4D NIfTI file where each volume represents a node) and its position in that dimension corresponds to its row/index in the tsv sidecar.
-1. [_mask](schema/objects/suffixes.yaml#mask): Either each voxel represents a node or the entire mask is a single node.
-   How the mask should be interpreted is determined by other specifications.
-   Based on these options, an atlas can take the following forms in the here proposed specification (non-exhaustive list):
-     1.  A 3D NIfTI file with unique integers defining nodes
-     1.  A 4D binary NIfTI file with spatially overlapping nodes in each volume (along the 4th dimension)
-     1.  A 4D NIfTI file with overlapping nodes with continuous values for each voxel within a volume
-
-Examples:
-```Text
-atlas-HarvardOxford_res-2_dseg.nii.gz
-atlas-HarvardOxford_res-2_probseg.nii.gz
-atlas-HarvardOxford_res-2_desc-HeschlGyrus_mask.nii.gz
-```
-
-General Recommendations: This specification relies on the inheritance principle whereby files deeper in the hierarchy inherit from the top-level files.
-If you have atlas files that are transformed to subject-specific space for each subject,
-then excluding the space entity at the top level is a good way to ensure the file inherits information about the original atlas.
-Additionally, the [desc](schema/objects/entities.yaml#desc) label should be avoided as an inherited file.
-One may need to use the [desc](schema/objects/entities.yaml#desc) label to contain information related or unrelated to the atlas.
-
-The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/region within the atlas.
-This file resembles the typical Look Up Table (LUT) often shared with atlases.
-This file will be essential for downstream workflows that generate matrices or other derived files within which node/parcel/region information is required,
-as the index/label fields will be used to reference the original anatomy the index/labels are derived from.
-Additional fields can be added with their respective definition/description in the sidecar json file.
-
-<table>
-  <tr>
-   <td>index (or placeholder in fragment in reference)
-   </td>
-   <td>REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
-   </td>
-  </tr>
-  <tr>
-   <td>label
-   </td>
-   <td>RECOMMENDED. The node name
-   </td>
-  </tr>
-  <tr>
-   <td>network_id
-   </td>
-   <td>OPTIONAL. Network ID the node/parcel belongs to
-   </td>
-  </tr>
-  <tr>
-   <td>network_label
-   </td>
-   <td>OPTIONAL. Label of Network (for example, Dorsal Attention Network)
-   </td>
-  </tr>
-  <tr>
-   <td>coordinate_report_strategy
-   </td>
-   <td>OPTIONAL (RECOMMENDED if x, y, z keys are specified).  The strategy used to assess and report x, y and z coordinates of a given node/parcel/region. For example, "CenterOfMass".
-   </td>
-  </tr>
-  <tr>
-   <td>x
-   </td>
-   <td>OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>y
-   </td>
-   <td>OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>z
-   </td>
-   <td>OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>hemisphere
-   </td>
-   <td>OPTIONAL. MUST BE ONE OF: "left", "right", "bilateral". Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
-   </td>
-  </tr>
-  <tr>
-   <td>color
-   </td>
-   <td>OPTIONAL. RGB color to use for the node.
-   </td>
-  </tr>
-  <tr>
-   <td>seed
-   </td>
-   <td>OPTIONAL. Seed vertex/channel of the node/region
-   </td>
-  </tr>
-  <tr>
-   <td>region
-   </td>
-   <td>OPTIONAL. "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
-   </td>
-  </tr>
-</table>
-
-Example:
-```Text
-index	label	network_label	hemisphere
-1	Heschl's Gyrus	Somatomotor	left
-2	Heschl's Gyrus	Somatomotor	right
-```
-
-The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators.
-Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
-
-<table>
-  <tr>
-   <td>Name
-   </td>
-   <td>REQUIRED. Name of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>Description
-   </td>
-   <td>RECOMMENDED. Longform description of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>SpatialReference
-   </td>
-   <td>RECOMMENDED. Point to an existing atlas in a template space (URL or relative file path where this file is located).
-   </td>
-  </tr>
-  <tr>
-   <td>Resolution
-   </td>
-   <td>RECOMMENDED. Resolution atlas is provided in.
-   </td>
-  </tr>
-  <tr>
-   <td>Dimensions
-   </td>
-   <td>RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
-   </td>
-  </tr>
-  <tr>
-   <td>4thDimension
-   </td>
-   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be "Indices" or   .
-   </td>
-  </tr>
-  <tr>
-   <td>CoordinateReportStrategy
-   </td>
-   <td>OPTIONAL. MUST BE ONE OF: "peak", "center_of_mass", "other". Indicate the method of coordinate reporting in statistically significant clusters. Could be the "peak" statistical coordinate in the cluster or the "center_of_mass" of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
-   </td>
-  </tr>
-  <tr>
-   <td>Authors
-   </td>
-   <td>RECOMMENDED. List of the authors involved in the creation of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>Curators
-   </td>
-   <td>RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
-   </td>
-  </tr>
-  <tr>
-   <td>Funding
-   </td>
-   <td>RECOMMENDED. The funding source(s) involved in the atlas creation
-   </td>
-  </tr>
-  <tr>
-   <td>License
-   </td>
-   <td>RECOMMENDED. The license agreement for using the atlas.
-   </td>
-  </tr>
-  <tr>
-   <td>ReferencesAndLinks
-   </td>
-   <td>RECOMMENDED. A list of relevant references and links pertaining to the atlas.
-   </td>
-  </tr>
-  <tr>
-   <td>Species
-   </td>
-   <td>RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
-   </td>
-  </tr>
-  <tr>
-   <td>DerivedFrom
-   </td>
-   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
-   </td>
-  </tr>
-  <tr>
-   <td>LevelType
-   </td>
-   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, for example, "group", "individual".
-   </td>
-  </tr>
-</table>
-
-
-
-Example:
-
-```JSON
-{
-  "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
-  "Authors": [
-    "David Kennedy",
-    "Christian Haselgrove",
-    "Bruce Fischl",
-    "Janis Breeze",
-    "Jean Frazie",
-    "Larry Seidman",
-    "Jill Goldstein"
-  ],
-  "BIDSVersion": "1.1.0",
-  "Curators": "FSL team",
-  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
-  "Space": "MNI152NLin6Asym",
-  "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
-  "License": "See LICENSE file",
-  "RRID": "SCR_002823",
-  "ReferencesAndLinks": [
-    "https://doi.org/10.1016/j.neuroimage.2012.01.024",
-    "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
-  ],
-  "Species": "Human"
-}
-```
-
-# BIDS-Atlas Example datasets
-Within the following, multiple examples showcasing the proposed extension are provided.
-They include BEP-specific as well as other/general BIDS files.
-
-## Atlas as dataset - single existing atlas in template space
-
-The example below illustrates how a single existing atlas in template space is represented as a dataset according to the atlas BEP.
-Specifically, the example refers to the Harvard-Oxford atlas in MN152NLin6Asym space with a resolution of 2 mm3,
-used without modifications (for example, transformations, subsetting, etc.)
-for all subjects to which the pipeline was applied.
-
-```Text
-my_dataset/atlas-HarvardOxford/
-  atlas-HarvardOxford_res-2_dseg.json
-  atlas-HarvardOxford_res-2_dseg.nii.gz
-  atlas-HarvardOxford_res-2_dseg.tsv
-```
-
-The content of each file is further outlined in the following,
-starting with the .json sidecar file containing meta-data about the atlas at hand.
-
-Example content of the `atlas-HarvardOxford_res-2_dseg.json` file:
-
-```JSON
-{
-  "Authors": [
-    "David Kennedy",
-    "Christian Haselgrove",
-    "Bruce Fischl",
-    "Janis Breeze",
-    "Jean Frazie",
-    "Larry Seidman",
-    "Jill Goldstein"
-  ],
-  "BIDSVersion": "1.1.0",
-  "Curators": "FSL team",
-  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
-  "Space": "MNI152NLin6Asym",
-  "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
-  "License": "See LICENSE file",
-    "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
-  "RRID": "SCR_002823",
-  "ReferencesAndLinks": [
-    "https://doi.org/10.1016/j.neuroimage.2012.01.024",
-    "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
-  ],
-  "Species": "Human"
-}
-```
-
-Next, the content of the tsv files describing the indices and corresponding labels present in the atlas at hand.
-
-Example content of the `atlas-HarvardOxford_res-2_dseg.tsv` file:
-
-```Text
-index	label	hemisphere
-0	Background	bilateral
-1	Frontal Pole	bilateral
-2
-Insular Cortex	bilateral
-3	Superior Frontal Gyrus	bilateral
-4	Middle Frontal Gyrus	bilateral
-5	Inferior Frontal Gyrus, pars triangularis	bilateral
-6	Inferior Frontal Gyrus, pars opercularis	bilateral
-```
-
-## Multiple existing atlases in template space
-The example below illustrates how multiple existing atlases in the same template space are represented according to the atlas BEP.
-Specifically, the example refers to the Harvard-Oxford, Schaefer, Yeo and MSDL atlases,
-all in MN152NLin6Asym space and with a resolution of 2 mm3,
-were utilized without modifications (for example, transformations, subsetting, etc.)
-for all subjects to which the pipeline was applied.
-Importantly, all atlas-related information is indicated via the value of the atlas- key and not via desc- to help prevent inheritance problems in subsequent steps.
-Here, this was used to indicate that the Harvard-Oxford atlas in its version with a maximum probability of 50,
-the Schaefer atlas in its 400 parcel version and the Yeo atlas in its 17 networks version were used.
-The respective information found in each file follows the example outlined in 4.1 as atlases were used independently from one another.
-
-
-```Text
-bids/atlases/
-  atlas-HarvardOxford/
-    atlas-HarvardOxford_dseg.nii.gz
-    atlas-HarvardOxford_dseg.json
-    atlas-HarvardOxford_dseg.tsv
-  atlas-Schaefer400/
-    atlas-Schaefer400_dseg.nii.gz
-    atlas-Schaefer400_dseg.json
-    atlas-Schaefer400_dseg.tsv
-  atlas-Yeo17/
-    atlas-Yeo17_dseg.nii.gz
-    atlas-Yeo17_dseg.json
-    atlas-Yeo17_dseg.tsv
-  atlas-msdl/
-    atlas-msdl_probseg.nii.gz
-    atlas-msdl_probseg.json
-    atlas-msdl_probseg.tsv
-```
- 
-## Single existing atlas transformed to subject space
-The example below illustrates how a single existing atlas transformed into a subject’s native space space is represented according to the atlas BEP.
-Specifically, the example refers to the Harvard-Oxford atlas with a resolution of 2 mm3 that was transformed from the MN152NLin6Asym template space to a given subject’s native T1w space.
-While the original atlas-related files remain as outlined in the use case in template space,
-the spatially transformed version of the nii.gz atlas file will be placed within a given subjects directory.
-The precise location within the latter depends on the modality space to which the atlas was transformed to,
-for example, anat, func or dwi.
-The same location furthermore entails a corresponding json file outlining further information on the source atlas and applied transformation(s).
-
-
-```Text
-bids/atlases/atlas-HarvardOxford/
-  atlas-HarvardOxford_dseg.json
-  atlas-HarvardOxford_dseg.tsv
-  atlas-HavardOxford2_dseg.nii.gz
-bids/derivatives/pipeline-<name>/
-  sub-01/
-    anat/
-      sub-01_T1w.nii.gz
-      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.nii.gz
-      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.json
-      sub-01_space-T1w_seg-HarvardOxfordThr50_res-2_dseg.tsv
-```
-
-The json file accompanying the transformed atlas should include the following information.
-
-Example content of the `sub-01_space-T1w_seg-HarvardOxford_res-2_dseg.json` file:
-
-```JSON
-{
-  "BIDSVersion": "1.1.0",
-  "SpatialReference": "sub-01/anat/sub-01_T1w.nii.gz",
-  "Space": "T1w",
-  "Resolution": "Matched with original resolution in subject T1w space (1x1x1 mm^3)",
-  "Sources": [],
-  "transformation":
-}
-```
-
-##  MyConnectome example
-
-The example below illustrates how two atlases,
-an individual surface-based cortical parcellation in FS_lr space (called Russome),
-and the subcortical regions from a volumetric segmentation provided by the FreeSurfer aseg,
-are represented according to the atlas BEP.
-While the FreeSurfer atlas-related files have two instances,
-one as outlined in the use case in template space and one as outlined in the use case covering subject spaces,
-the individual parcellation in FS_lr space will be placed only within a given subjects directory.
-The same location furthermore entails a corresponding json file outlining further information on the atlas and applied analysis to obtain it.
-
-```Text
-bids/atlases/atlas-FreeSurferASEG/
-  atlas-FreeSurferASEG_dseg.json
-  atlas-FreeSurferASEG_dseg.tsv
-  atlas-FreeSurferASEG_dseg.nii.gz
-
-bids/derivatives/pipeline-<name>/
-  sub-01/
-    anat/
-      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.nii.gz
-      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.json
-      sub-01_space-T1w_seg-FreeSurferASEG_res-2_dseg.tsv
-    func/
-      sub-01_space-FSlr_seg-Russome_res-2_dseg.nii.gz
-      sub-01_space-FSlr_seg-Russome_res-2_dseg.json
-      sub-01_space-FSlr_seg-Russome_res-2_dseg.tsv
-```
-
-The json file accompanying the functionally derived atlas should include the following information.
-
-Example content of the `sub-01_task-rest_atlas.json` file contains top-level metadata about the atlas:
-
-```JSON
-
-"Atlas":
-{
-  "Russome":
-  {
-    "Atlasfile": "/link/to/russome/file",
-    "Extra": "individualized surface parcellation"
-  },
-  "FS_aseg": {
-    "Atlasfile": "/link/to/aseg/file",
-    "Extra": "freesurfer aseg"
-  }
-}
-
-```
-
-## Quantitative atlas examples
-
-The example below is for PET imaging, but this applies to any quantitative mapping (PET or qMRI).
-Compared to anatomical atlases, quantitative atlases give reference values to be compared with.
-Such values can be derived voxel/vertex wise (see case 1) or per region of interest (ROI) (see case 2).
-In the latter case, ROIs are generally derived from an anatomical atlas.
-
-We created a Molecular Imaging Brain Atlases (MIBA) from 16 subjects who underwent a [11C]PS13 PET scan,
-a radioligand that quantifies cyclooxygenase-1 (see [source data](https://openneuro.org/datasets/ds004332/versions/1.0.2)).
-Our atlas consists of mean and standard deviations of PS13 target distribution volumes (VT) computed across the 16 subjects at each voxel, in standard MRI spaces.
-We also project these distribution volumes onto the FreeSurfer cortical surfaces and include these as well.
-The goal is to allow researchers with MRI-only data to correlate their results to the distribution volume of PS13.
-The dataset can be found [here](https://openneuro.org/datasets/ds004401/versions/1.1.0).
-
-### Case 1: voxel/vertex wise analysis
-
-Example directory content for a quantitative atlas that provides values at all voxels and/or vertices:
-
-```Text
-bids/atlas/atlas-ps13/
-    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.json
-    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_mimap.nii.gz
-    atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.json
-    atlas-ps13_space-fsaverage_hemi-R_stat-mean_meas-VT_mimap.nii.gz
-    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.json
-    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_mimap.nii.gz
-    atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.json
-    atlas-ps13_space-fsaverage_hemi-L_stat-std_meas-VT_mimap.nii.gz
-    atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.json
-    atlas-ps13_space-fsaverage_hemi-R_stat-std_meas-VT_mimap.nii.gz
-    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.json
-    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_mimap.nii.gz
-```
-
-### Case 2: regional analysis (voxels/vertices are averaged per regions from dseg/probseg)
-
-Example directory content for a quantitative atlas that provides values for certain ROIs only,
-in this case defined by the AAL atlas:
-
-```Text
-bids/atlas/
-  atlas-mni305/
-    atlas-aparc.DKTatlas+aseg.mgz
-    atlas-aparc.DKTatlas+aseg.tsv
-    atlas-RB_all_2008-03-26.probseg.gca
-    atlas-RB_all_2008-03-26.probseg.tsv
-  atlas-ps13/
-    atlas-ps13_space-fsaverage_hemi-L_stat-mean_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-fsaverage-hemi-L_stat-mean_meas-VT_seg-AAL_mimap.tsv
-    atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-fsaverage-hemi-L_stat-std_meas-VT_seg-AAL_mimap.tsv
-    atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-fsaverage-hemi-R_stat-mean_meas-VT_seg-AAL_mimap.tsv
-    atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-fsaverage-hemi-R_stat-std_meas-VT_seg-AAL_mimap.tsv
-    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-MNI305Lin_res-2_stat-mean_meas-VT_seg-AAL_mimap.tsv
-    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.json
-    atlas-ps13_space-MNI305Lin_res-2_stat-std_meas-VT_seg-AAL_mimap.tsv
-```
-
-Note that there is no image file present in a regional quantitative atlas.
-The json file accompanying the quantitative atlas should include the information as in [Single existing atlas in template space](#_Single_existing_atlas_in_template_space).
diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
new file mode 100644
index 0000000000..538a5c46da
--- /dev/null
+++ b/src/derivatives/atlas.md
@@ -0,0 +1,477 @@
+# Templates and atlases
+
+In the following we describe how the outcomes of analyses that produce new
+templates and [atlases](schema/objects/entities.yaml#atlas) are organized
+as BIDS-Derivatives.
+These outcomes typically involve quantitative maps, feature maps, parcellations,
+segmentations, and other knowledge annotations such as landmarks defined with
+respect to individual or template brains that are supported by spaces
+such as surfaces and regular grids (images).
+Templates and atlases follow BIDS raw and derivatives specifications to store
+these outcomes:
+
+```Text
+<pipeline_name>/
+    sub-<label>/
+        <datatype>/
+            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+```
+
+Template's [`suffix`](schema/objects/entities.yaml#suffix) will generally be existing BIDS raw modalities
+such as `T1w`, while it will normally take `dseg`, `probseg`, or `mask` to encode atlased knowledge.
+In terms of [`extension`](schema/objects/entities.yaml#extension), `nii[.gz]`, `dscalar.nii[.gz]`,
+`dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
+
+The [`atlas-` entity](schema/objects/entities.yaml#atlas) is REQUIRED to encode files belonging in
+the atlas identified by the label.
+Two entities MAY be employed along with `atlas-` to disentangle different realizations and scales
+of a single atlas:
+
+-    [`seg-`](schema/objects/entities.yaml#seg) is REQUIRED when a single atlas has several different
+     realizations (for instance, segmentations and parcellations created with different criteria) that
+     need disambiguation.
+-    [`scale-`](schema/objects/entities.yaml#scale) is REQUIRED to disambiguate different atlas 'scales',
+     when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
+     by regions.
+
+These three atlas-related entities are discussed later in section [#atlas-filenames-specifications].
+
+## Single-subject templates and atlases
+
+Early digital templates and atlases such as MNI's
+'[Colin 27 Average Brain, Stereotaxic Registration Model](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27)'
+([Holmes et al., 1998](https://doi.org/10.1097/00004728-199803000-00032)) were built by examinating single individuals.
+For example, the outputs of the pipeline that generated 'Colin27' would have been organized as follows:
+
+```Text
+colin27-pipeline/
+└─ sub-01/
+   └─ anat/
+      ├─ sub-01_label-brain_mask.nii.gz
+      ├─ sub-01_label-head_mask.nii.gz
+      ├─ sub-01_T1w.nii.gz
+      └─ sub-01_T1w.json
+```
+
+In the presence of conflicting files, for example, when there are several resolutions,
+additional entities MUST be specified:
+
+```Text
+colin27-pipeline/
+└─ sub-01/
+   └─ anat/
+      ├─ sub-01_res-1_label-brain_mask.nii.gz
+      ├─ sub-01_res-1_label-head_mask.nii.gz
+      ├─ sub-01_res-1_T1w.nii.gz
+      ├─ sub-01_res-1_T1w.json
+      ├─ sub-01_res-2_T1w.nii.gz
+      └─ sub-01_res-2_T1w.json
+```
+
+The following example shows how 'Colin27' could have encoded the Automated Anatomical Labeling (AAL)
+atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
+defined on the Colin27 space:
+
+```Text
+colin27-pipeline/
+└─ sub-01/
+   └─ anat/
+      ├─ sub-01_atlas-AAL_dseg.json
+      ├─ sub-01_atlas-AAL_dseg.nii.gz
+      ├─ sub-01_atlas-AAL_dseg.tsv
+      ├─ sub-01_atlas-AAL_probseg.nii.gz
+      ├─ sub-01_label-brain_mask.nii.gz
+      ├─ sub-01_label-head_mask.nii.gz
+      ├─ sub-01_T1w.nii.gz
+      └─ sub-01_T1w.json
+```
+
+As the authors of 'Colin27' indicate, it is aligned with MNI305:
+
+> In 1998, a new atlas with much higher definition than MNI305s was created at the MNI.
+> One individual (CJH) was scanned 27 times and the images linearly registered to create
+> an average with high SNR and structure definition (Holmes et al., 1998).
+> This average was linearly registered to the average 305.
+> Ironically, this dataset was not originally intended for use as a stereotaxic template
+> but as the sub-strate for an ROI parcellation scheme to be used with
+> ANIMAL non-linear spatial normalization (Collins et al., 1995),
+> i.e. it was intended for the purpose of segmentation, NOT stereotaxy.
+> As a single brain atlas, it did not capture anatomical variability and was, to some degree,
+> a reversion to the Talairach approach.
+>
+> However, the high definition proved too attractive to the community and,
+> after non-linear mapping to fit the MNI305 space, it has been adopted
+> by many groups as a stereotaxic template.
+>
+> (from https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27)
+
+Therefore, this pipeline potentially could have produced outputs in the realigned T1w space
+before alignment to the MNI305 template.
+To disambiguate in this case, we employ the [`space-`](schema/objects/entities.yaml#space) entity:
+
+```Text
+colin27-pipeline/
+└─ sub-01/
+   └─ anat/
+      ├─ sub-01_space-MNI305_atlas-AAL_dseg.json
+      ├─ sub-01_space-MNI305_atlas-AAL_dseg.nii.gz
+      ├─ sub-01_space-MNI305_atlas-AAL_dseg.tsv
+      ├─ sub-01_space-MNI305_atlas-AAL_probseg.nii.gz
+      ├─ sub-01_space-MNI305_label-brain_mask.nii.gz
+      ├─ sub-01_space-MNI305_label-head_mask.nii.gz
+      ├─ sub-01_space-MNI305_T1w.nii.gz
+      ├─ sub-01_space-MNI305_T1w.json
+      ├─ sub-01_space-T1w_label-brain_mask.nii.gz
+      ├─ sub-01_space-T1w_label-head_mask.nii.gz
+      ├─ sub-01_space-T1w_T1w.nii.gz
+      └─ sub-01_space-T1w_T1w.json
+```
+
+## Multi-subject template and atlases and deriving an existing template/atlas
+
+Atlasing multiple individual brains is a higher-than-first-level analysis,
+as it requires first generating derivatives for the individuals (for example,
+a transformation to align them into a standardized space) and later aggregate
+and distill the sample-pooled knowledge and feature maps.
+Similarly, deriving from an existing template and atlases is also
+a higher-than-first-level analysis as it builds on a previous analysis.
+
+**Multi-subject templates and atlases**.
+While at the subject level analysis it is the individual brain that establishes
+stereotaxy.
+At higher-than-first-level stereotaxy is supported by templates.
+For the pipeline that generated the MNI152NLin2009cAsym, the outputs would look
+like the following example:
+
+```Text
+mni152nlin2009casym-pipeline/
+└─ tpl-MNI152NLin2009cAsym/
+   └─ anat/
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-eye_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-face_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-head_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-CSF_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-GM_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_label-WM_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.json
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-brain_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-eye_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-face_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-head_mask.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-CSF_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-GM_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_label-WM_probseg.nii.gz
+      ├─ tpl-MNI152NLin2009cAsym_res-2_T1w.nii.gz
+      └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json
+```
+
+**Deriving from an existing template/atlas**.
+For example, the MIAL67ThalamicNuclei
+([Najdenovska et al., 2018](https://doi.org/10.1038/sdata.2018.270))
+atlas-generation pipeline could display the following structure:
+
+```Text
+MIAL67ThalamicNuclei-pipeline/
+├─ 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
+├─ sub-01
+│  └─ anat/
+│     ├─ sub-01_label-ThalamicNuclei_dseg.json
+│     ├─ sub-01_label-ThalamicNuclei_dseg.tsv
+│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
+│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
+│     └─ sub-01_T1w.nii.gz
+┇
+└─ sub-67
+   └─ anat/
+      ├─ sub-67_label-ThalamicNuclei_dseg.json
+      ├─ sub-67_label-ThalamicNuclei_dseg.tsv
+      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
+      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
+      └─ sub-67_T1w.nii.gz
+```
+
+where the derivatives of anatomical processing of the 67 subjects that were
+employed to generate the atlas co-exist with the template structure.
+
+The inheritance principle applies uniformly, allowing the segmentation
+metadata be stored only once at the root of the pipeline folder and
+apply to all the individual subject segmentations:
+
+```Text
+MIAL67ThalamicNuclei-pipeline/
+├─ label-ThalamicNuclei_dseg.json
+├─ label-ThalamicNuclei_dseg.tsv
+├─ 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
+├─ sub-01
+│  └─ anat/
+│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
+│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
+│     └─ sub-01_T1w.nii.gz
+┇
+└─ sub-67
+   └─ anat/
+      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
+      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
+      └─ sub-67_T1w.nii.gz
+```
+
+## Filenames of derivatives with atlases in their provenance
+
+Like for the [`space-` entity](schema/objects/entities.yaml#space), outputs derived from atlases
+MUST employ `atlas-`, `seg-`, and `scale-` when necessary:
+
+```Text
+bold-pipeline/
+├─ atlas-Schaefer2018_dseg.json
+├─ atlas-Schaefer2018_seg-7n_scale-100_dseg.tsv
+├─ atlas-Schaefer2018_seg-7n_scale-200_dseg.tsv
+├─ atlas-Schaefer2018_seg-7n_scale-300_dseg.tsv
+├─ atlas-Schaefer2018_seg-17n_scale-100_dseg.tsv
+├─ atlas-Schaefer2018_seg-17n_scale-200_dseg.tsv
+├─ atlas-Schaefer2018_seg-17n_scale-300_dseg.tsv
+├─ atlas-Schaefer2018_seg-kong17n_scale-100_dseg.tsv
+├─ atlas-Schaefer2018_seg-kong17n_scale-200_dseg.tsv
+├─ atlas-Schaefer2018_seg-kong17n_scale-300_dseg.tsv
+└─ sub-01/
+   ├─ anat/
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-100_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-200_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-300_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-100_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-200_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-300_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-100_den-164k_dseg.label.gii
+   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-200_den-164k_dseg.label.gii
+   │  └─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-300_den-164k_dseg.label.gii
+   └─ func/
+      └─ sub-01_task-rest_hemi-L_den-164k_bold.func.gii
+```
+
+## Tabular data
+
+The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/region within the atlas.
+This file resembles the typical Look Up Table (LUT) often shared with atlases.
+This file will be essential for downstream workflows that generate matrices or other derived files within which node/parcel/region information is required,
+as the index/label fields will be used to reference the original anatomy the index/labels are derived from.
+Additional fields can be added with their respective definition/description in the sidecar json file.
+
+<table>
+  <tr>
+   <td>index (or placeholder in fragment in reference)
+   </td>
+   <td>REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
+   </td>
+  </tr>
+  <tr>
+   <td>label
+   </td>
+   <td>RECOMMENDED. The node name
+   </td>
+  </tr>
+  <tr>
+   <td>network_id
+   </td>
+   <td>OPTIONAL. Network ID the node/parcel belongs to
+   </td>
+  </tr>
+  <tr>
+   <td>network_label
+   </td>
+   <td>OPTIONAL. Label of Network (for example, Dorsal Attention Network)
+   </td>
+  </tr>
+  <tr>
+   <td>coordinate_report_strategy
+   </td>
+   <td>OPTIONAL (RECOMMENDED if x, y, z keys are specified).  The strategy used to assess and report x, y and z coordinates of a given node/parcel/region. For example, "CenterOfMass".
+   </td>
+  </tr>
+  <tr>
+   <td>x
+   </td>
+   <td>OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>y
+   </td>
+   <td>OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>z
+   </td>
+   <td>OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
+   </td>
+  </tr>
+  <tr>
+   <td>hemisphere
+   </td>
+   <td>OPTIONAL. MUST BE ONE OF: "left", "right", "bilateral". Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
+   </td>
+  </tr>
+  <tr>
+   <td>color
+   </td>
+   <td>OPTIONAL. RGB color to use for the node.
+   </td>
+  </tr>
+  <tr>
+   <td>seed
+   </td>
+   <td>OPTIONAL. Seed vertex/channel of the node/region
+   </td>
+  </tr>
+  <tr>
+   <td>region
+   </td>
+   <td>OPTIONAL. "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
+   </td>
+  </tr>
+</table>
+
+Example:
+```Text
+index	label	network_label	hemisphere
+1	Heschl's Gyrus	Somatomotor	left
+2	Heschl's Gyrus	Somatomotor	right
+```
+
+## Atlas metadata
+
+The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators.
+Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
+
+<table>
+  <tr>
+   <td>Name
+   </td>
+   <td>REQUIRED. Name of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>Description
+   </td>
+   <td>RECOMMENDED. Longform description of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>SpatialReference
+   </td>
+   <td>RECOMMENDED. Point to an existing atlas in a template space (URL or relative file path where this file is located).
+   </td>
+  </tr>
+  <tr>
+   <td>Resolution
+   </td>
+   <td>RECOMMENDED. Resolution atlas is provided in.
+   </td>
+  </tr>
+  <tr>
+   <td>Dimensions
+   </td>
+   <td>RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
+   </td>
+  </tr>
+  <tr>
+   <td>4thDimension
+   </td>
+   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be "Indices" or   .
+   </td>
+  </tr>
+  <tr>
+   <td>CoordinateReportStrategy
+   </td>
+   <td>OPTIONAL. MUST BE ONE OF: "peak", "center_of_mass", "other". Indicate the method of coordinate reporting in statistically significant clusters. Could be the "peak" statistical coordinate in the cluster or the "center_of_mass" of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
+   </td>
+  </tr>
+  <tr>
+   <td>Authors
+   </td>
+   <td>RECOMMENDED. List of the authors involved in the creation of the atlas
+   </td>
+  </tr>
+  <tr>
+   <td>Curators
+   </td>
+   <td>RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
+   </td>
+  </tr>
+  <tr>
+   <td>Funding
+   </td>
+   <td>RECOMMENDED. The funding source(s) involved in the atlas creation
+   </td>
+  </tr>
+  <tr>
+   <td>License
+   </td>
+   <td>RECOMMENDED. The license agreement for using the atlas.
+   </td>
+  </tr>
+  <tr>
+   <td>ReferencesAndLinks
+   </td>
+   <td>RECOMMENDED. A list of relevant references and links pertaining to the atlas.
+   </td>
+  </tr>
+  <tr>
+   <td>Species
+   </td>
+   <td>RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
+   </td>
+  </tr>
+  <tr>
+   <td>DerivedFrom
+   </td>
+   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
+   </td>
+  </tr>
+  <tr>
+   <td>LevelType
+   </td>
+   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, for example, "group", "individual".
+   </td>
+  </tr>
+</table>
+
+Example:
+
+```JSON
+{
+  "Name": "FSL's MNI ICBM 152 non-linear 6th Generation Asymmetric Average Brain Stereotaxic Registration Model",
+  "Authors": [
+    "David Kennedy",
+    "Christian Haselgrove",
+    "Bruce Fischl",
+    "Janis Breeze",
+    "Jean Frazie",
+    "Larry Seidman",
+    "Jill Goldstein"
+  ],
+  "BIDSVersion": "1.1.0",
+  "Curators": "FSL team",
+  "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
+  "Space": "MNI152NLin6Asym",
+  "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
+  "License": "See LICENSE file",
+  "RRID": "SCR_002823",
+  "ReferencesAndLinks": [
+    "https://doi.org/10.1016/j.neuroimage.2012.01.024",
+    "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases"
+  ],
+  "Species": "Human"
+}
+```
diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index 55ad6e3bf1..eddb0a7c8e 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -181,7 +181,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_desc-<label>]_<suffix>.<extension>
+            <source_entities>[_space-<space>][_atlas-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Data is considered to be *preprocessed* or *cleaned* if the data type of the input,
diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
index aea21dbaad..d8a3022a01 100644
--- a/src/derivatives/imaging.md
+++ b/src/derivatives/imaging.md
@@ -11,7 +11,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+            <source_entities>[_space-<space>][_atlas-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 Volumetric preprocessing does not modify the number of dimensions, and so

From 0180e3badea82dbcaa286ee3be920f1f1c5548d2 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 12 Jun 2024 19:23:39 -0400
Subject: [PATCH 02/47] STY: codespell

---
 src/derivatives/atlas.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 538a5c46da..7a5df71336 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -40,7 +40,7 @@ These three atlas-related entities are discussed later in section [#atlas-filena
 
 Early digital templates and atlases such as MNI's
 '[Colin 27 Average Brain, Stereotaxic Registration Model](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27)'
-([Holmes et al., 1998](https://doi.org/10.1097/00004728-199803000-00032)) were built by examinating single individuals.
+([Holmes et al., 1998](https://doi.org/10.1097/00004728-199803000-00032)) were built by examining single individuals.
 For example, the outputs of the pipeline that generated 'Colin27' would have been organized as follows:
 
 ```Text
@@ -201,7 +201,7 @@ where the derivatives of anatomical processing of the 67 subjects that were
 employed to generate the atlas co-exist with the template structure.
 
 The inheritance principle applies uniformly, allowing the segmentation
-metadata be stored only once at the root of the pipeline folder and
+metadata be stored only once at the root of the pipeline directory and
 apply to all the individual subject segmentations:
 
 ```Text

From bba4159b0250fc6472fddae600dcb5b812e8d128 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 12 Jun 2024 19:23:44 -0400
Subject: [PATCH 03/47] Replace links to the schema with links to the glossary

---
 src/derivatives/atlas.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 7a5df71336..477c8285a6 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -1,7 +1,7 @@
 # Templates and atlases
 
 In the following we describe how the outcomes of analyses that produce new
-templates and [atlases](schema/objects/entities.yaml#atlas) are organized
+templates and [atlases](../glossary.md#atlas-entities) are organized
 as BIDS-Derivatives.
 These outcomes typically involve quantitative maps, feature maps, parcellations,
 segmentations, and other knowledge annotations such as landmarks defined with
@@ -17,20 +17,20 @@ these outcomes:
             <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
-Template's [`suffix`](schema/objects/entities.yaml#suffix) will generally be existing BIDS raw modalities
+Template's [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
 such as `T1w`, while it will normally take `dseg`, `probseg`, or `mask` to encode atlased knowledge.
-In terms of [`extension`](schema/objects/entities.yaml#extension), `nii[.gz]`, `dscalar.nii[.gz]`,
+In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
 `dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
 
-The [`atlas-` entity](schema/objects/entities.yaml#atlas) is REQUIRED to encode files belonging in
+The [`atlas-` entity](../glossary.md#atlas-entities) is REQUIRED to encode files belonging in
 the atlas identified by the label.
 Two entities MAY be employed along with `atlas-` to disentangle different realizations and scales
 of a single atlas:
 
--    [`seg-`](schema/objects/entities.yaml#seg) is REQUIRED when a single atlas has several different
+-    [`seg-`](../glossary.md#seg-entities) is REQUIRED when a single atlas has several different
      realizations (for instance, segmentations and parcellations created with different criteria) that
      need disambiguation.
--    [`scale-`](schema/objects/entities.yaml#scale) is REQUIRED to disambiguate different atlas 'scales',
+-    [`scale-`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
      when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
      by regions.
 
@@ -107,7 +107,7 @@ As the authors of 'Colin27' indicate, it is aligned with MNI305:
 
 Therefore, this pipeline potentially could have produced outputs in the realigned T1w space
 before alignment to the MNI305 template.
-To disambiguate in this case, we employ the [`space-`](schema/objects/entities.yaml#space) entity:
+To disambiguate in this case, we employ the [`space-`](../glossary.md#space-entities) entity:
 
 ```Text
 colin27-pipeline/
@@ -229,7 +229,7 @@ MIAL67ThalamicNuclei-pipeline/
 
 ## Filenames of derivatives with atlases in their provenance
 
-Like for the [`space-` entity](schema/objects/entities.yaml#space), outputs derived from atlases
+Like for the [`space-` entity](../glossary.md#space-entities), outputs derived from atlases
 MUST employ `atlas-`, `seg-`, and `scale-` when necessary:
 
 ```Text

From f159e61317c6a4ae2a318391b6c40d4b709df606 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 09:57:39 +0200
Subject: [PATCH 04/47] enh: generalization of atlas metadata cc/ @jdkent

---
 src/derivatives/atlas.md | 65 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 477c8285a6..57d097387c 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -227,6 +227,71 @@ MIAL67ThalamicNuclei-pipeline/
       └─ sub-67_T1w.nii.gz
 ```
 
+This folder structure can be generally applied when the atlas is derived into several
+template spaces, for example:
+
+```Text
+MIAL67ThalamicNuclei-pipeline/
+├─ atlas-MIAL67ThalamicNuclei_dseg.json
+├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
+├─ label-ThalamicNuclei_dseg.json
+├─ label-ThalamicNuclei_dseg.tsv
+├─ tpl-MNI152NLin6Asym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ tpl-MNI152NLin2009cAsym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ sub-01
+│  └─ anat/
+│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
+│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
+│     └─ sub-01_T1w.nii.gz
+┇
+└─ sub-67
+   └─ anat/
+      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
+      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
+      └─ sub-67_T1w.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
+`label-ThalamicNuclei`), the above example translates into:
+
+```Text
+MIAL67ThalamicNuclei-pipeline/
+├─ atlas-MIAL67ThalamicNuclei_dseg.json
+├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
+├─ label-ThalamicNuclei_dseg.json
+├─ label-ThalamicNuclei_dseg.tsv
+├─ tpl-MNI152NLin6Asym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ tpl-MNI152NLin2009cAsym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ sub-01
+│  └─ anat/
+│     ├─ sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz
+│     ├─ sub-01_label-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_label-ThalamicNuclei_dseg.nii.gz
+      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
+      └─ sub-67_T1w.nii.gz
+```
+
+The next subsection describes this latter use-case in further depth.
+
 ## Filenames of derivatives with atlases in their provenance
 
 Like for the [`space-` entity](../glossary.md#space-entities), outputs derived from atlases

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 05/47] 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

From 3f8c2106c65ac54447dcf125fd21bb01a943d00b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 11:47:26 +0200
Subject: [PATCH 06/47] enh: reference entities from glossary

---
 src/derivatives/atlas.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 57d097387c..b97d911a2c 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -27,7 +27,7 @@ the atlas identified by the label.
 Two entities MAY be employed along with `atlas-` to disentangle different realizations and scales
 of a single atlas:
 
--    [`seg-`](../glossary.md#seg-entities) is REQUIRED when a single atlas has several different
+-    [`seg-`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
      realizations (for instance, segmentations and parcellations created with different criteria) that
      need disambiguation.
 -    [`scale-`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
@@ -68,6 +68,9 @@ colin27-pipeline/
       └─ sub-01_res-2_T1w.json
 ```
 
+Often, templates are necessary to bring or project information from/to an atlas.
+Derivatives provenant from an atlas MUST be encoded with the
+[`atlas-<label>` entity](glossary.md#atlas-entities).
 The following example shows how 'Colin27' could have encoded the Automated Anatomical Labeling (AAL)
 atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
 defined on the Colin27 space:
@@ -139,7 +142,8 @@ a higher-than-first-level analysis as it builds on a previous analysis.
 **Multi-subject templates and atlases**.
 While at the subject level analysis it is the individual brain that establishes
 stereotaxy.
-At higher-than-first-level stereotaxy is supported by templates.
+At higher-than-first-level stereotaxy is supported by templates, which are
+encoded through the [`tpl-<label>` entity](glossary.md#template-entities).
 For the pipeline that generated the MNI152NLin2009cAsym, the outputs would look
 like the following example:
 

From 927335cc3cd9a77c7e13483a4148020f0261ce00 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 11:49:19 +0200
Subject: [PATCH 07/47] fix: folder => directory

---
 src/common-principles.md | 2 +-
 src/derivatives/atlas.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 89f007269c..d850de5b72 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -318,7 +318,7 @@ Original templates and atlases employed as primary data to the analysis MAY be s
 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
+`derivatives/` directory, and follow the general specifications for derivatives regarding
 storage and distribution, as described in the next section.
 
 ### Storage of derived datasets
diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index b97d911a2c..8620fd3adc 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -231,7 +231,7 @@ MIAL67ThalamicNuclei-pipeline/
       └─ sub-67_T1w.nii.gz
 ```
 
-This folder structure can be generally applied when the atlas is derived into several
+This directory structure can be generally applied when the atlas is derived into several
 template spaces, for example:
 
 ```Text

From 6a3dcc799cba4d8ecddbb0a86bf08aa06db9fbb1 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 12:04:42 +0200
Subject: [PATCH 08/47] fix: resolving issues with/within entities

---
 src/derivatives/atlas.md         | 17 ++++++++---------
 src/schema/objects/entities.yaml |  4 ++--
 2 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 8620fd3adc..7b9f416927 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -22,15 +22,15 @@ such as `T1w`, while it will normally take `dseg`, `probseg`, or `mask` to encod
 In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
 `dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
 
-The [`atlas-` entity](../glossary.md#atlas-entities) is REQUIRED to encode files belonging in
+The [`atlas-<label>` entity](../glossary.md#atlas-entities) is REQUIRED to encode files belonging in
 the atlas identified by the label.
 Two entities MAY be employed along with `atlas-` to disentangle different realizations and scales
 of a single atlas:
 
--    [`seg-`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
+-    [`seg-<label>`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
      realizations (for instance, segmentations and parcellations created with different criteria) that
      need disambiguation.
--    [`scale-`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
+-    [`scale-<label>`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
      when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
      by regions.
 
@@ -70,7 +70,7 @@ colin27-pipeline/
 
 Often, templates are necessary to bring or project information from/to an atlas.
 Derivatives provenant from an atlas MUST be encoded with the
-[`atlas-<label>` entity](glossary.md#atlas-entities).
+[`atlas-<label>` entity](../glossary.md#atlas-entities).
 The following example shows how 'Colin27' could have encoded the Automated Anatomical Labeling (AAL)
 atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
 defined on the Colin27 space:
@@ -89,7 +89,8 @@ colin27-pipeline/
       └─ sub-01_T1w.json
 ```
 
-As the authors of 'Colin27' indicate, it is aligned with MNI305:
+As [the authors of 'Colin27' indicate](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27),
+it is aligned with MNI305:
 
 > In 1998, a new atlas with much higher definition than MNI305s was created at the MNI.
 > One individual (CJH) was scanned 27 times and the images linearly registered to create
@@ -105,12 +106,10 @@ As the authors of 'Colin27' indicate, it is aligned with MNI305:
 > However, the high definition proved too attractive to the community and,
 > after non-linear mapping to fit the MNI305 space, it has been adopted
 > by many groups as a stereotaxic template.
->
-> (from https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27)
 
 Therefore, this pipeline potentially could have produced outputs in the realigned T1w space
 before alignment to the MNI305 template.
-To disambiguate in this case, we employ the [`space-`](../glossary.md#space-entities) entity:
+To disambiguate in this case, we employ the [`space-<label>` entity](../glossary.md#space-entities):
 
 ```Text
 colin27-pipeline/
@@ -143,7 +142,7 @@ a higher-than-first-level analysis as it builds on a previous analysis.
 While at the subject level analysis it is the individual brain that establishes
 stereotaxy.
 At higher-than-first-level stereotaxy is supported by templates, which are
-encoded through the [`tpl-<label>` entity](glossary.md#template-entities).
+encoded through the [`tpl-<label>` entity](../glossary.md#template-entities).
 For the pipeline that generated the MNI152NLin2009cAsym, the outputs would look
 like the following example:
 
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index cecaf723ba..6340e9ff37 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -305,8 +305,8 @@ segmentation:
 
     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
+    For example, the [Yeo 2011 atlas](https://doi.org/10.1152/jn.00338.2011)
+    is distributed within *FreeSurfer* with two different parcellations
     (*7 networks* and *17 networks*).
 
     This entity is only applicable to derivative data.

From f7e906d21d9c9d57a584e3581474615468fc0316 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 12:21:28 +0200
Subject: [PATCH 09/47] enh: add mention to transforms files cc/ @peerherholz

---
 src/derivatives/atlas.md | 71 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 7b9f416927..f0a9108779 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -170,6 +170,36 @@ mni152nlin2009casym-pipeline/
       └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json
 ```
 
+Since multi-subject templates and atlas involve the spatial normalization of
+subjects by means of image registration processes, it is RECOMMENDED to store
+the resulting transforms for each of the subjects employed to create the
+output.
+Please note that the specification for spatial transforms (BEP 014) is currently
+under development, and therefore, the specification of transforms files may
+change in the future.
+As these are subject-wise results, they follow the standard derivatives conventions
+with a `sub-<label>` directory to house these derivatives:
+
+```Text
+mni152nlin2009casym-pipeline/
+├─ tpl-MNI152NLin2009cAsym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz
+│     ├─ ...
+│     └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json
+├─ 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
+```
+
 **Deriving from an existing template/atlas**.
 For example, the MIAL67ThalamicNuclei
 ([Najdenovska et al., 2018](https://doi.org/10.1038/sdata.2018.270))
@@ -183,7 +213,7 @@ MIAL67ThalamicNuclei-pipeline/
 │     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_dseg.tsv
 │     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
 │     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ sub-01
+├─ sub-01/
 │  └─ anat/
 │     ├─ sub-01_label-ThalamicNuclei_dseg.json
 │     ├─ sub-01_label-ThalamicNuclei_dseg.tsv
@@ -191,7 +221,7 @@ MIAL67ThalamicNuclei-pipeline/
 │     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
 │     └─ sub-01_T1w.nii.gz
 ┇
-└─ sub-67
+└─ sub-67/
    └─ anat/
       ├─ sub-67_label-ThalamicNuclei_dseg.json
       ├─ sub-67_label-ThalamicNuclei_dseg.tsv
@@ -293,6 +323,43 @@ MIAL67ThalamicNuclei-pipeline/
       └─ sub-67_T1w.nii.gz
 ```
 
+Without any loss in generality, we can store subjects' spatially normalizing
+transforms, as well as transforms between template spaces:
+
+```Text
+MIAL67ThalamicNuclei-pipeline/
+├─ atlas-MIAL67ThalamicNuclei_dseg.json
+├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
+├─ label-ThalamicNuclei_dseg.json
+├─ label-ThalamicNuclei_dseg.tsv
+├─ tpl-MNI152NLin6Asym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ tpl-MNI152NLin2009cAsym/
+│  └─ anat/
+│     ├─ tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5
+│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
+│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
+├─ sub-01
+│  └─ anat/
+│     ├─ sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz
+│     ├─ sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
+│     ├─ sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
+│     ├─ sub-01_label-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_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
+      ├─ sub-67_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
+      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
+      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
+      └─ sub-67_T1w.nii.gz
+```
+
 The next subsection describes this latter use-case in further depth.
 
 ## Filenames of derivatives with atlases in their provenance

From 57160cd8e0783dee9bb2488bae700fbb786dfd62 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 12:31:03 +0200
Subject: [PATCH 10/47] fix: revise more glossary links

---
 src/derivatives/atlas.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index f0a9108779..e67dd626c4 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -1,7 +1,7 @@
 # Templates and atlases
 
 In the following we describe how the outcomes of analyses that produce new
-templates and [atlases](../glossary.md#atlas-entities) are organized
+[templates and atlases](../common-principles.md#definitions) are organized
 as BIDS-Derivatives.
 These outcomes typically involve quantitative maps, feature maps, parcellations,
 segmentations, and other knowledge annotations such as landmarks defined with
@@ -364,8 +364,11 @@ The next subsection describes this latter use-case in further depth.
 
 ## Filenames of derivatives with atlases in their provenance
 
-Like for the [`space-` entity](../glossary.md#space-entities), outputs derived from atlases
-MUST employ `atlas-`, `seg-`, and `scale-` when necessary:
+Like for the [`space-<label>` entity](../glossary.md#space-entities),
+outputs derived from atlases MUST employ
+[`atlas-<label>`](../glossary.md#atlas-entities),
+[`seg-<label>`](../glossary.md#segmentation-entities), and
+[`scale-<label>`](../glossary.md#scale-entities) when necessary:
 
 ```Text
 bold-pipeline/

From 1db3fd4717ab5bffc005e7eda1928cb726393848 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 21:52:37 +0200
Subject: [PATCH 11/47] enh: move all filetree examples to macros

---
 src/derivatives/atlas.md | 628 +++++++++++++++++++++++----------------
 1 file changed, 377 insertions(+), 251 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index e67dd626c4..6252ab3018 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -43,30 +43,46 @@ Early digital templates and atlases such as MNI's
 ([Holmes et al., 1998](https://doi.org/10.1097/00004728-199803000-00032)) were built by examining single individuals.
 For example, the outputs of the pipeline that generated 'Colin27' would have been organized as follows:
 
-```Text
-colin27-pipeline/
-└─ sub-01/
-   └─ anat/
-      ├─ sub-01_label-brain_mask.nii.gz
-      ├─ sub-01_label-head_mask.nii.gz
-      ├─ sub-01_T1w.nii.gz
-      └─ sub-01_T1w.json
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_label-brain_mask.nii.gz": "",
+            "sub-01_label-head_mask.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+            "sub-01_T1w.json": "",
+         },
+      },
+   }
+})
+}}
 
 In the presence of conflicting files, for example, when there are several resolutions,
 additional entities MUST be specified:
 
-```Text
-colin27-pipeline/
-└─ sub-01/
-   └─ anat/
-      ├─ sub-01_res-1_label-brain_mask.nii.gz
-      ├─ sub-01_res-1_label-head_mask.nii.gz
-      ├─ sub-01_res-1_T1w.nii.gz
-      ├─ sub-01_res-1_T1w.json
-      ├─ sub-01_res-2_T1w.nii.gz
-      └─ sub-01_res-2_T1w.json
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_res-1_label-brain_mask.nii.gz": "",
+            "sub-01_res-1_label-head_mask.nii.gz": "",
+            "sub-01_res-1_T1w.nii.gz": "",
+            "sub-01_res-1_T1w.json": "",
+            "sub-01_res-2_T1w.nii.gz": "",
+            "sub-01_res-2_T1w.json": "",
+         },
+      },
+   }
+})
+}}
 
 Often, templates are necessary to bring or project information from/to an atlas.
 Derivatives provenant from an atlas MUST be encoded with the
@@ -75,19 +91,27 @@ The following example shows how 'Colin27' could have encoded the Automated Anato
 atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
 defined on the Colin27 space:
 
-```Text
-colin27-pipeline/
-└─ sub-01/
-   └─ anat/
-      ├─ sub-01_atlas-AAL_dseg.json
-      ├─ sub-01_atlas-AAL_dseg.nii.gz
-      ├─ sub-01_atlas-AAL_dseg.tsv
-      ├─ sub-01_atlas-AAL_probseg.nii.gz
-      ├─ sub-01_label-brain_mask.nii.gz
-      ├─ sub-01_label-head_mask.nii.gz
-      ├─ sub-01_T1w.nii.gz
-      └─ sub-01_T1w.json
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_atlas-AAL_dseg.json": "",
+            "sub-01_atlas-AAL_dseg.nii.gz": "",
+            "sub-01_atlas-AAL_dseg.tsv": "",
+            "sub-01_atlas-AAL_probseg.nii.gz": "",
+            "sub-01_label-brain_mask.nii.gz": "",
+            "sub-01_label-head_mask.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+            "sub-01_T1w.json": "",
+         },
+      },
+   }
+})
+}}
 
 As [the authors of 'Colin27' indicate](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27),
 it is aligned with MNI305:
@@ -111,23 +135,31 @@ Therefore, this pipeline potentially could have produced outputs in the realigne
 before alignment to the MNI305 template.
 To disambiguate in this case, we employ the [`space-<label>` entity](../glossary.md#space-entities):
 
-```Text
-colin27-pipeline/
-└─ sub-01/
-   └─ anat/
-      ├─ sub-01_space-MNI305_atlas-AAL_dseg.json
-      ├─ sub-01_space-MNI305_atlas-AAL_dseg.nii.gz
-      ├─ sub-01_space-MNI305_atlas-AAL_dseg.tsv
-      ├─ sub-01_space-MNI305_atlas-AAL_probseg.nii.gz
-      ├─ sub-01_space-MNI305_label-brain_mask.nii.gz
-      ├─ sub-01_space-MNI305_label-head_mask.nii.gz
-      ├─ sub-01_space-MNI305_T1w.nii.gz
-      ├─ sub-01_space-MNI305_T1w.json
-      ├─ sub-01_space-T1w_label-brain_mask.nii.gz
-      ├─ sub-01_space-T1w_label-head_mask.nii.gz
-      ├─ sub-01_space-T1w_T1w.nii.gz
-      └─ sub-01_space-T1w_T1w.json
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_space-MNI305_atlas-AAL_dseg.json": "",
+            "sub-01_space-MNI305_atlas-AAL_dseg.nii.gz": "",
+            "sub-01_space-MNI305_atlas-AAL_dseg.tsv": "",
+            "sub-01_space-MNI305_atlas-AAL_probseg.nii.gz": "",
+            "sub-01_space-MNI305_label-brain_mask.nii.gz": "",
+            "sub-01_space-MNI305_label-head_mask.nii.gz": "",
+            "sub-01_space-MNI305_T1w.nii.gz": "",
+            "sub-01_space-MNI305_T1w.json": "",
+            "sub-01_space-T1w_label-brain_mask.nii.gz": "",
+            "sub-01_space-T1w_label-head_mask.nii.gz": "",
+            "sub-01_space-T1w_T1w.nii.gz": "",
+            "sub-01_space-T1w_T1w.json": "",
+         },
+      },
+   }
+})
+}}
 
 ## Multi-subject template and atlases and deriving an existing template/atlas
 
@@ -146,29 +178,37 @@ encoded through the [`tpl-<label>` entity](../glossary.md#template-entities).
 For the pipeline that generated the MNI152NLin2009cAsym, the outputs would look
 like the following example:
 
-```Text
-mni152nlin2009casym-pipeline/
-└─ tpl-MNI152NLin2009cAsym/
-   └─ anat/
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-eye_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-face_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-head_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-CSF_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-GM_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_label-WM_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-1_T1w.json
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-brain_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-eye_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-face_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-head_mask.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-CSF_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-GM_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_label-WM_probseg.nii.gz
-      ├─ tpl-MNI152NLin2009cAsym_res-2_T1w.nii.gz
-      └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mni152nlin2009casym-pipeline": {
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-eye_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-face_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-head_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-CSF_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-GM_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_label-WM_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-1_T1w.json": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-brain_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-eye_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-face_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-head_mask.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-CSF_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-GM_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_label-WM_probseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_T1w.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_res-2_T1w.json": "",
+         },
+      },
+   }
+})
+}}
 
 Since multi-subject templates and atlas involve the spatial normalization of
 subjects by means of image registration processes, it is RECOMMENDED to store
@@ -180,55 +220,79 @@ change in the future.
 As these are subject-wise results, they follow the standard derivatives conventions
 with a `sub-<label>` directory to house these derivatives:
 
-```Text
-mni152nlin2009casym-pipeline/
-├─ tpl-MNI152NLin2009cAsym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz
-│     ├─ ...
-│     └─ tpl-MNI152NLin2009cAsym_res-2_T1w.json
-├─ 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
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mni152nlin2009casym-pipeline": {
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz": "",
+            "...": "",
+            "tpl-MNI152NLin2009cAsym_res-2_T1w.json": "",
+         },
+      },
+      "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": "",
+         },
+      },
+   }
+})
+}}
 
 **Deriving from an existing template/atlas**.
 For example, the MIAL67ThalamicNuclei
 ([Najdenovska et al., 2018](https://doi.org/10.1038/sdata.2018.270))
 atlas-generation pipeline could display the following structure:
 
-```Text
-MIAL67ThalamicNuclei-pipeline/
-├─ 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
-├─ sub-01/
-│  └─ anat/
-│     ├─ sub-01_label-ThalamicNuclei_dseg.json
-│     ├─ sub-01_label-ThalamicNuclei_dseg.tsv
-│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
-│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
-│     └─ sub-01_T1w.nii.gz
-┇
-└─ sub-67/
-   └─ anat/
-      ├─ sub-67_label-ThalamicNuclei_dseg.json
-      ├─ sub-67_label-ThalamicNuclei_dseg.tsv
-      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
-      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
-      └─ sub-67_T1w.nii.gz
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mial67thalamicnuclei-pipeline": {
+      "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": "",
+         },
+      },
+      "sub-01": {
+         "anat": {
+            "sub-01_label-ThalamicNuclei_dseg.json": "",
+            "sub-01_label-ThalamicNuclei_dseg.tsv": "",
+            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+         },
+      },
+      "...": "",
+      "sub-67": {
+         "anat": {
+            "sub-67_label-ThalamicNuclei_dseg.json": "",
+            "sub-67_label-ThalamicNuclei_dseg.tsv": "",
+            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-67_T1w.nii.gz": "",
+         },
+      },
+   }
+})
+}}
 
 where the derivatives of anatomical processing of the 67 subjects that were
 employed to generate the atlas co-exist with the template structure.
@@ -237,128 +301,178 @@ 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:
 
-```Text
-MIAL67ThalamicNuclei-pipeline/
-├─ label-ThalamicNuclei_dseg.json
-├─ label-ThalamicNuclei_dseg.tsv
-├─ 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
-├─ sub-01
-│  └─ anat/
-│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
-│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
-│     └─ sub-01_T1w.nii.gz
-┇
-└─ sub-67
-   └─ anat/
-      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
-      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
-      └─ sub-67_T1w.nii.gz
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mial67thalamicnuclei-pipeline": {
+      "label-ThalamicNuclei_dseg.json": "",
+      "label-ThalamicNuclei_dseg.tsv": "",
+      "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": "",
+         },
+      },
+      "sub-01": {
+         "anat": {
+            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+         },
+      },
+      "...": "",
+      "sub-67": {
+         "anat": {
+            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-67_T1w.nii.gz": "",
+         },
+      },
+   }
+})
+}}
 
 This directory structure can be generally applied when the atlas is derived into several
 template spaces, for example:
 
-```Text
-MIAL67ThalamicNuclei-pipeline/
-├─ atlas-MIAL67ThalamicNuclei_dseg.json
-├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
-├─ label-ThalamicNuclei_dseg.json
-├─ label-ThalamicNuclei_dseg.tsv
-├─ tpl-MNI152NLin6Asym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ tpl-MNI152NLin2009cAsym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ sub-01
-│  └─ anat/
-│     ├─ sub-01_label-ThalamicNuclei_dseg.nii.gz
-│     ├─ sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
-│     └─ sub-01_T1w.nii.gz
-┇
-└─ sub-67
-   └─ anat/
-      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
-      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
-      └─ sub-67_T1w.nii.gz
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mial67thalamicnuclei-pipeline": {
+      "atlas-MIAL67ThalamicNuclei_dseg.json": "",
+      "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
+      "label-ThalamicNuclei_dseg.json": "",
+      "label-ThalamicNuclei_dseg.tsv": "",
+      "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": "",
+         },
+      },
+      "sub-01": {
+         "anat": {
+            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-01_space-MNI152NLin6Asym_T1w.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+         },
+      },
+      "...": "",
+      "sub-67": {
+         "anat": {
+            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-67_space-MNI152NLin6Asym_T1w.nii.gz": "",
+            "sub-67_T1w.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
 `label-ThalamicNuclei`), the above example translates into:
 
-```Text
-MIAL67ThalamicNuclei-pipeline/
-├─ atlas-MIAL67ThalamicNuclei_dseg.json
-├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
-├─ label-ThalamicNuclei_dseg.json
-├─ label-ThalamicNuclei_dseg.tsv
-├─ tpl-MNI152NLin6Asym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ tpl-MNI152NLin2009cAsym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ sub-01
-│  └─ anat/
-│     ├─ sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz
-│     ├─ sub-01_label-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_label-ThalamicNuclei_dseg.nii.gz
-      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
-      └─ sub-67_T1w.nii.gz
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mial67thalamicnuclei-pipeline": {
+      "atlas-MIAL67ThalamicNuclei_dseg.json": "",
+      "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
+      "label-ThalamicNuclei_dseg.json": "",
+      "label-ThalamicNuclei_dseg.tsv": "",
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz": "",
+            "tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz": "",
+         },
+      },
+      "sub-01": {
+         "anat": {
+            "sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_label-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_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-67_T1w.nii.gz": "",
+         },
+      },
+   }
+})
+}}
 
 Without any loss in generality, we can store subjects' spatially normalizing
 transforms, as well as transforms between template spaces:
 
-```Text
-MIAL67ThalamicNuclei-pipeline/
-├─ atlas-MIAL67ThalamicNuclei_dseg.json
-├─ atlas-MIAL67ThalamicNuclei_dseg.tsv
-├─ label-ThalamicNuclei_dseg.json
-├─ label-ThalamicNuclei_dseg.tsv
-├─ tpl-MNI152NLin6Asym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ tpl-MNI152NLin2009cAsym/
-│  └─ anat/
-│     ├─ tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5
-│     ├─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz
-│     └─ tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz
-├─ sub-01
-│  └─ anat/
-│     ├─ sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz
-│     ├─ sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
-│     ├─ sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
-│     ├─ sub-01_label-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_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
-      ├─ sub-67_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
-      ├─ sub-67_label-ThalamicNuclei_dseg.nii.gz
-      ├─ sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz
-      └─ sub-67_T1w.nii.gz
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mial67thalamicnuclei-pipeline": {
+      "atlas-MIAL67ThalamicNuclei_dseg.json": "",
+      "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
+      "label-ThalamicNuclei_dseg.json": "",
+      "label-ThalamicNuclei_dseg.tsv": "",
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5": "",
+            "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": "",
+         },
+      },
+      "sub-01": {
+         "anat": {
+            "sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
+            "sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5": "",
+            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-01_space-MNI152NLin6Asym_T1w.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+         },
+      },
+      "...": "",
+      "sub-67": {
+         "anat": {
+            "sub-67_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
+            "sub-67_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5": "",
+            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
+            "sub-67_space-MNI152NLin6Asym_T1w.nii.gz": "",
+            "sub-67_T1w.nii.gz": "",
+         },
+      },
+   }
+})
+}}
 
 The next subsection describes this latter use-case in further depth.
 
@@ -370,32 +484,44 @@ outputs derived from atlases MUST employ
 [`seg-<label>`](../glossary.md#segmentation-entities), and
 [`scale-<label>`](../glossary.md#scale-entities) when necessary:
 
-```Text
-bold-pipeline/
-├─ atlas-Schaefer2018_dseg.json
-├─ atlas-Schaefer2018_seg-7n_scale-100_dseg.tsv
-├─ atlas-Schaefer2018_seg-7n_scale-200_dseg.tsv
-├─ atlas-Schaefer2018_seg-7n_scale-300_dseg.tsv
-├─ atlas-Schaefer2018_seg-17n_scale-100_dseg.tsv
-├─ atlas-Schaefer2018_seg-17n_scale-200_dseg.tsv
-├─ atlas-Schaefer2018_seg-17n_scale-300_dseg.tsv
-├─ atlas-Schaefer2018_seg-kong17n_scale-100_dseg.tsv
-├─ atlas-Schaefer2018_seg-kong17n_scale-200_dseg.tsv
-├─ atlas-Schaefer2018_seg-kong17n_scale-300_dseg.tsv
-└─ sub-01/
-   ├─ anat/
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-100_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-200_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-300_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-100_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-200_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-300_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-100_den-164k_dseg.label.gii
-   │  ├─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-200_den-164k_dseg.label.gii
-   │  └─ sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-300_den-164k_dseg.label.gii
-   └─ func/
-      └─ sub-01_task-rest_hemi-L_den-164k_bold.func.gii
-```
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "bold-pipeline": {
+      "atlas-Schaefer2018_dseg.json": "",
+      "atlas-Schaefer2018_seg-7n_scale-100_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-7n_scale-200_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-7n_scale-300_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-17n_scale-100_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-17n_scale-200_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-17n_scale-300_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-kong17n_scale-100_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-kong17n_scale-200_dseg.tsv": "",
+      "atlas-Schaefer2018_seg-kong17n_scale-300_dseg.tsv": "",
+      "sub-01": {
+         "anat": {
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-100_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-200_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-7n_scale-300_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-100_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-200_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-17n_scale-300_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-100_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-200_den-164k_dseg.label.gii": "",
+            "sub-01_hemi-L_atlas-Schaefer2018_seg-kong17n_scale-300_den-164k_dseg.label.gii": "",
+            "...": "",
+            "sub-01_hemi-R_atlas-Schaefer2018_seg-kong17n_scale-300_den-164k_dseg.label.gii": "",
+         },
+         "bold": {
+            "sub-01_task-rest_hemi-L_den-164k_bold.func.gii": "",
+            "sub-01_task-rest_hemi-R_den-164k_bold.func.gii": "",
+         }
+      },
+   }
+})
+}}
 
 ## Tabular data
 

From 48e77ae2a5f46ccfba4196f1f3f000e47e828472 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 17 Jun 2024 22:10:02 +0200
Subject: [PATCH 12/47] enh: miscellaneous improvements (sort entries in
 examples, etc.)

---
 src/derivatives/atlas.md | 140 +++++++++++++++++++++++----------------
 1 file changed, 82 insertions(+), 58 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 6252ab3018..e66c8f4ab9 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -7,8 +7,8 @@ These outcomes typically involve quantitative maps, feature maps, parcellations,
 segmentations, and other knowledge annotations such as landmarks defined with
 respect to individual or template brains that are supported by spaces
 such as surfaces and regular grids (images).
-Templates and atlases follow BIDS raw and derivatives specifications to store
-these outcomes:
+For derivatives with atlases in their provenance corresponding to individual subjects,
+the organization follows the standards for BIDS raw and derivatives:
 
 ```Text
 <pipeline_name>/
@@ -17,7 +17,7 @@ these outcomes:
             <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
-Template's [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
+where [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
 such as `T1w`, while it will normally take `dseg`, `probseg`, or `mask` to encode atlased knowledge.
 In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
 `dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
@@ -34,7 +34,30 @@ of a single atlas:
      when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
      by regions.
 
-These three atlas-related entities are discussed later in section [#atlas-filenames-specifications].
+These three atlas-related entities are discussed later in section
+[Filenames of derivatives with atlases in their provenance](#filenames-of-derivatives-with-atlases-in-their-provenance).
+
+For derivatives of template- and altas-generating pipelines, the derivatives-specific
+[`tpl-<label>` entity](../glossary.md#template-entities) MAY be employed as follows:
+
+```Text
+<pipeline_name>/
+    tpl-<label>/
+        [<datatype>/]
+            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+```
+
+Both subject-level and template-level results can coexist in a single pipeline folder:
+
+```Text
+<pipeline_name>/
+    sub-<label>/
+        <datatype>/
+            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+    tpl-<label>/
+        [<datatype>/]
+            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+```
 
 ## Single-subject templates and atlases
 
@@ -210,6 +233,7 @@ A guide for using macros can be found at
 })
 }}
 
+**Storing spatial transforms.**
 Since multi-subject templates and atlas involve the spatial normalization of
 subjects by means of image registration processes, it is RECOMMENDED to store
 the resulting transforms for each of the subjects employed to create the
@@ -226,13 +250,6 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mni152nlin2009casym-pipeline": {
-      "tpl-MNI152NLin2009cAsym": {
-         "anat": {
-            "tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz": "",
-            "...": "",
-            "tpl-MNI152NLin2009cAsym_res-2_T1w.json": "",
-         },
-      },
       "sub-001": {
          "anat": {
             "sub-001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
@@ -248,6 +265,13 @@ A guide for using macros can be found at
             "sub-152_T1w.nii.gz": "",
          },
       },
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_res-1_label-brain_mask.nii.gz": "",
+            "...": "",
+            "tpl-MNI152NLin2009cAsym_res-2_T1w.json": "",
+         },
+      },
    }
 })
 }}
@@ -263,14 +287,6 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mial67thalamicnuclei-pipeline": {
-      "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": "",
-         },
-      },
       "sub-01": {
          "anat": {
             "sub-01_label-ThalamicNuclei_dseg.json": "",
@@ -290,6 +306,14 @@ A guide for using macros can be found at
             "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": "",
+         },
+      },
    }
 })
 }}
@@ -309,14 +333,6 @@ A guide for using macros can be found at
    "mial67thalamicnuclei-pipeline": {
       "label-ThalamicNuclei_dseg.json": "",
       "label-ThalamicNuclei_dseg.tsv": "",
-      "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": "",
-         },
-      },
       "sub-01": {
          "anat": {
             "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
@@ -332,6 +348,14 @@ A guide for using macros can be found at
             "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": "",
+         },
+      },
    }
 })
 }}
@@ -349,18 +373,6 @@ A guide for using macros can be found at
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
       "label-ThalamicNuclei_dseg.json": "",
       "label-ThalamicNuclei_dseg.tsv": "",
-      "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": "",
-         },
-      },
       "sub-01": {
          "anat": {
             "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
@@ -378,6 +390,18 @@ A guide for using macros can be found at
             "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": "",
+         },
+      },
+      "tpl-MNI152NLin6Asym": {
+         "anat": {
+            "tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz": "",
+            "tpl-MNI152NLin6Asym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz": "",
+         },
+      },
    }
 })
 }}
@@ -396,12 +420,6 @@ A guide for using macros can be found at
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
       "label-ThalamicNuclei_dseg.json": "",
       "label-ThalamicNuclei_dseg.tsv": "",
-      "tpl-MNI152NLin2009cAsym": {
-         "anat": {
-            "tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz": "",
-            "tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_probseg.nii.gz": "",
-         },
-      },
       "sub-01": {
          "anat": {
             "sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
@@ -419,6 +437,12 @@ A guide for using macros can be found at
             "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": "",
+         },
+      },
    }
 })
 }}
@@ -436,19 +460,6 @@ A guide for using macros can be found at
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
       "label-ThalamicNuclei_dseg.json": "",
       "label-ThalamicNuclei_dseg.tsv": "",
-      "tpl-MNI152NLin2009cAsym": {
-         "anat": {
-            "tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5": "",
-            "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": "",
-         },
-      },
       "sub-01": {
          "anat": {
             "sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
@@ -470,6 +481,19 @@ A guide for using macros can be found at
             "sub-67_T1w.nii.gz": "",
          },
       },
+      "tpl-MNI152NLin2009cAsym": {
+         "anat": {
+            "tpl-MNI152NLin2009cAsym_from-MNI152NLin6Asym_mode-image_xfm.h5": "",
+            "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": "",
+         },
+      },
    }
 })
 }}

From d6cf6a453ef3dd9f45b8770550c0143af9c24501 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 09:49:10 +0200
Subject: [PATCH 13/47] enh: improve intro

---
 src/derivatives/atlas.md | 51 +++++++++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 22 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index e66c8f4ab9..3df0d4f626 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -1,14 +1,31 @@
 # Templates and atlases
 
-In the following we describe how the outcomes of analyses that produce new
-[templates and atlases](../common-principles.md#definitions) are organized
+In the following, we describe how the outcomes of analyses that derive from or
+produce [templates and atlases](../common-principles.md#definitions) are organized
 as BIDS-Derivatives.
 These outcomes typically involve quantitative maps, feature maps, parcellations,
 segmentations, and other knowledge annotations such as landmarks defined with
 respect to individual or template brains that are supported by spaces
 such as surfaces and regular grids (images).
+
 For derivatives with atlases in their provenance corresponding to individual subjects,
-the organization follows the standards for BIDS raw and derivatives:
+the organization follows the standards for BIDS raw and derivatives.
+The following entities MAY be employed to specify template- and atlas-derived results:
+
+-    [`space-<label>`](../glossary.md#space-entities) is REQUIRED to disambiguate derivatives defined with
+     respect to different [coordinate systems](../appendices/coordinate-systems.md), following the general
+     BIDS-Derivatives specifications.
+-    [`atlas-<label>`](../glossary.md#atlas-entities) is REQUIRED to encode files pertaining
+     or derived from the atlas identified by the entity's label.
+-    [`seg-<label>`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
+     realizations (for instance, segmentations and parcellations created with different criteria) that
+     need disambiguation.
+-    [`scale-<label>`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
+     when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
+     by regions.
+
+The general filename pattern for subject derivatives with templates and atlases in their provenance
+follows the general BIDS-Derivatives pattern:
 
 ```Text
 <pipeline_name>/
@@ -17,27 +34,12 @@ the organization follows the standards for BIDS raw and derivatives:
             <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
-where [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
-such as `T1w`, while it will normally take `dseg`, `probseg`, or `mask` to encode atlased knowledge.
-In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
-`dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
-
-The [`atlas-<label>` entity](../glossary.md#atlas-entities) is REQUIRED to encode files belonging in
-the atlas identified by the label.
-Two entities MAY be employed along with `atlas-` to disentangle different realizations and scales
-of a single atlas:
-
--    [`seg-<label>`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
-     realizations (for instance, segmentations and parcellations created with different criteria) that
-     need disambiguation.
--    [`scale-<label>`](../glossary.md#scale-entities) is REQUIRED to disambiguate different atlas 'scales',
-     when the atlas has more than one 'brain unit' resolutions, typically relating to the area covered
-     by regions.
-
-These three atlas-related entities are discussed later in section
+[`atlas-<label>`](../glossary.md#atlas-entities), [`seg-<label>`](../glossary.md#segmentation-entities),
+and [`scale-<label>`](../glossary.md#scale-entities) are discussed later in section
 [Filenames of derivatives with atlases in their provenance](#filenames-of-derivatives-with-atlases-in-their-provenance).
 
-For derivatives of template- and altas-generating pipelines, the derivatives-specific
+For derivatives of template- and altas-generating pipelines, which typically aggregate
+several sessions and/or subjects, the derivatives-specific
 [`tpl-<label>` entity](../glossary.md#template-entities) MAY be employed as follows:
 
 ```Text
@@ -47,6 +49,11 @@ For derivatives of template- and altas-generating pipelines, the derivatives-spe
             <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
+where [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
+(such as `T1w`) for templates, while it will normally take `dseg`, `probseg`, or `mask` to encode atlased
+knowledge.
+In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
+`dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
 Both subject-level and template-level results can coexist in a single pipeline folder:
 
 ```Text

From 8bfc7ac520f184b59828164310e51818d8e37317 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 10:06:01 +0200
Subject: [PATCH 14/47] enh: add datatype comment to make it recommended cc/
 @effigies

---
 src/derivatives/atlas.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 3df0d4f626..dc8cbef289 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -54,6 +54,9 @@ where [`suffix`](../glossary.md#suffix-common_principles) will generally be exis
 knowledge.
 In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
 `dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
+Please note that the [`<datatype>/` directory](../glossary.md#data_type-common_principles) is RECOMMENDED.
+The [`<datatype>/` directory](../glossary.md#data_type-common_principles) MAY be ommitted in the case
+only one data type (such as `anat/`) is stored under the `tpl-<label>` folder.
 Both subject-level and template-level results can coexist in a single pipeline folder:
 
 ```Text
@@ -326,7 +329,7 @@ A guide for using macros can be found at
 }}
 
 where the derivatives of anatomical processing of the 67 subjects that were
-employed to generate the atlas co-exist with the template structure.
+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

From f2be20ad74c2d76707c2373f4829364db1c6348f Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 10:16:30 +0200
Subject: [PATCH 15/47] enh: start drafting cohort

---
 src/derivatives/atlas.md | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index dc8cbef289..728406d1b1 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -15,6 +15,8 @@ The following entities MAY be employed to specify template- and atlas-derived re
 -    [`space-<label>`](../glossary.md#space-entities) is REQUIRED to disambiguate derivatives defined with
      respect to different [coordinate systems](../appendices/coordinate-systems.md), following the general
      BIDS-Derivatives specifications.
+-    [`cohort-<label>`](../glossary.md#cohort-entities) is REQUIRED to disambiguate derivatives defined with
+     respect to different cohort instances of a single [space (coordinate system)](../appendices/coordinate-systems.md).
 -    [`atlas-<label>`](../glossary.md#atlas-entities) is REQUIRED to encode files pertaining
      or derived from the atlas identified by the entity's label.
 -    [`seg-<label>`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different
@@ -31,7 +33,7 @@ follows the general BIDS-Derivatives pattern:
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+            <source_entities>[_space-<space>][_cohort-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 [`atlas-<label>`](../glossary.md#atlas-entities), [`seg-<label>`](../glossary.md#segmentation-entities),
@@ -40,13 +42,15 @@ and [`scale-<label>`](../glossary.md#scale-entities) are discussed later in sect
 
 For derivatives of template- and altas-generating pipelines, which typically aggregate
 several sessions and/or subjects, the derivatives-specific
-[`tpl-<label>` entity](../glossary.md#template-entities) MAY be employed as follows:
+[`tpl-<label>` entity](../glossary.md#template-entities) is dual in terms of usage to BIDS raw's
+[`sub-<label>`](../glossary.md#subject-entities), and MAY be employed as follows:
 
 ```Text
 <pipeline_name>/
     tpl-<label>/
-        [<datatype>/]
-            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+        [cohort-<label>/]
+           [<datatype>/]
+               <source_entities>[_cohort-<label>][_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 where [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities
@@ -57,16 +61,21 @@ In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]
 Please note that the [`<datatype>/` directory](../glossary.md#data_type-common_principles) is RECOMMENDED.
 The [`<datatype>/` directory](../glossary.md#data_type-common_principles) MAY be ommitted in the case
 only one data type (such as `anat/`) is stored under the `tpl-<label>` folder.
+The [`cohort-<label>` directory and entity](../glossary.md#cohort-entities) MUST be specified for templates
+with several cohorts.
+The [`cohort-<label>` directory and entity](../glossary.md#cohort-entities) are dual in terms of usage to BIDS raw's
+[`session-<label>`](../glossary.md#session-entities).
 Both subject-level and template-level results can coexist in a single pipeline folder:
 
 ```Text
 <pipeline_name>/
     sub-<label>/
         <datatype>/
-            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+            <source_entities>[_space-<space>][_cohort-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
     tpl-<label>/
-        [<datatype>/]
-            <source_entities>[_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+        [cohort-<label>/]
+           [<datatype>/]
+               <source_entities>[_cohort-<label>][_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 ## Single-subject templates and atlases

From d15677ad116c752ac965bc8bf9ab5f60cb056a27 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 10:46:24 +0200
Subject: [PATCH 16/47] enh: add multi-cohort example

---
 src/derivatives/atlas.md | 54 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 728406d1b1..21e9fb4388 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -252,6 +252,60 @@ A guide for using macros can be found at
 })
 }}
 
+**Multi-cohort templates and atlases.**
+In the case that the template- and/or atlas-generating pipeline derives
+several cohorts, the file structure must employ the
+[`cohort-<label>` directory and entity](../glossary.md#cohort-entities).
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "mnipediatricasym-pipeline": {
+      "tpl-MNIPediatricAsym": {
+         "cohort-1": {
+            "anat": {
+               "tpl-MNIPediatricAsym_cohort-1_res-1_PD.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_T1w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_T2w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_desc-brain_mask.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_label-CSF_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_label-GM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-1_label-WM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_PD.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_T1w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_T2w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_desc-brain_mask.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_label-CSF_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_label-GM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-1_res-2_label-WM_probseg.nii.gz": "",
+            },
+         },
+         "...": "",
+         "cohort-6": {
+            "anat": {
+               "tpl-MNIPediatricAsym_cohort-6_res-1_PD.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_T1w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_T2w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_desc-brain_mask.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_label-CSF_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_label-GM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-1_label-WM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_PD.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_T1w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_T2w.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_desc-brain_mask.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_label-CSF_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_label-GM_probseg.nii.gz": "",
+               "tpl-MNIPediatricAsym_cohort-6_res-2_label-WM_probseg.nii.gz": "",
+            },
+         },
+      },
+   }
+})
+}}
+
 **Storing spatial transforms.**
 Since multi-subject templates and atlas involve the spatial normalization of
 subjects by means of image registration processes, it is RECOMMENDED to store

From b275ca39b9d0e46a0d26393e19da69c5e1e73926 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 16:08:55 +0200
Subject: [PATCH 17/47] fix: pacify pre-commit build

---
 src/derivatives/atlas.md    |  6 +++---
 tools/print_contributors.py | 20 +++++++++-----------
 2 files changed, 12 insertions(+), 14 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 21e9fb4388..ae9bf063e2 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -59,13 +59,13 @@ knowledge.
 In terms of [`extension`](../glossary.md#extension-common_principles), `nii[.gz]`, `dscalar.nii[.gz]`,
 `dlabel.nii[.gz]`, `label.gii[.gz]`, `tsv`, or `json`.
 Please note that the [`<datatype>/` directory](../glossary.md#data_type-common_principles) is RECOMMENDED.
-The [`<datatype>/` directory](../glossary.md#data_type-common_principles) MAY be ommitted in the case
-only one data type (such as `anat/`) is stored under the `tpl-<label>` folder.
+The [`<datatype>/` directory](../glossary.md#data_type-common_principles) 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](../glossary.md#cohort-entities) MUST be specified for templates
 with several cohorts.
 The [`cohort-<label>` directory and entity](../glossary.md#cohort-entities) are dual in terms of usage to BIDS raw's
 [`session-<label>`](../glossary.md#session-entities).
-Both subject-level and template-level results can coexist in a single pipeline folder:
+Both subject-level and template-level results can coexist in a single pipeline directory:
 
 ```Text
 <pipeline_name>/
diff --git a/tools/print_contributors.py b/tools/print_contributors.py
index c49ca6f823..29db86a39c 100644
--- a/tools/print_contributors.py
+++ b/tools/print_contributors.py
@@ -15,8 +15,9 @@
 
 
 def contributor_table_header(max_name_length, max_contrib_length):
-    return f"""| name{" " * (max_name_length-4)} | contributions{" " * (max_contrib_length-13)} |
-| {"-" * max_name_length} | {"-"*max_contrib_length} |
+    return f"""\
+| {"name":<{max_name_length}} | {"contributions":<{max_contrib_length}} |
+| {"":-<{max_name_length}} | {"":-<{max_contrib_length}} |
 """
 
 
@@ -24,16 +25,13 @@ def create_line_contributor(
     contributor: dict[str, str], max_name_length: int, max_contrib_length: int
 ):
     name = contributor["name"]
+    emap = emoji_map()
+    contributions = "".join(
+        emoji.emojize(emap[cont]) for cont in contributor["contributions"]
+    )
 
-    line = f"| {name}{' '*(max_name_length-len(name))} | "
-
-    nb_contrib = len(contributor["contributions"]) * 2
-    for contrib in contributor["contributions"]:
-        line += emoji.emojize(emoji_map()[contrib])
-
-    line += f"{' '*(max_contrib_length-nb_contrib)} |\n"
-
-    return line
+    pad = max_contrib_length - len(contributor["contributions"]) * 2
+    return f"| {name:<{max_name_length}} | {contributions}{'':<{pad}} |\n"
 
 
 def main():

From f9ff346ed5ee368eb7802417f63f44745c211826 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 18 Jun 2024 17:34:29 +0200
Subject: [PATCH 18/47] enh: add the PS13 example

---
 src/derivatives/atlas.md | 123 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index ae9bf063e2..58a76500b7 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -349,6 +349,129 @@ A guide for using macros can be found at
 })
 }}
 
+**The PS13 atlas example.**
+The [PS13 atlas](https://doi.org/10.18112/openneuro.ds004401.v1.3.0) is a
+molecular imaging brain atlas of Cyclooxygenase-1 (PET).
+The atlas is generated in two standard spaces: `MNI152Lin` and `fsaverage`:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "ps13-pipeline": {
+      "tpl-fsaverage": {
+         "pet": {
+            "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-fsaverage_atlas-ps13_dseg.json": "",
+            "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
+            "tpl-fsaverage_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_desc-nopvc_mimap.nii.gz": "",
+            "tpl-fsaverage_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_desc-pvc_mimap.nii.gz": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.shape.gii": "",
+            "tpl-fsaverage_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_stat-std_desc-nopvc_mimap.nii.gz": "",
+            "tpl-fsaverage_stat-std_desc-pvc_mimap.json": "",
+            "tpl-fsaverage_stat-std_desc-pvc_mimap.nii.gz": "",
+         },
+      },
+      "tpl-MNI152Lin": {
+         "pet": {
+            "tpl-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
+            "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_mimap.json": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_mimap.json": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtPvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtPvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-nopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_desc-nopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-pvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_desc-pvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_mimap.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_mimap.nii.gz": "",
+         },
+      }
+   }
+})
+}}
+
+If the pipeline generates two different atlases for at least one template space
+in the output, then [`atlas-<label>`](../glossary.md#atlas-entities) is REQUIRED
+for the whole dataset.
+For example, let's imagine the PS13 atlas is revised in 2034, and based on the
+original pipeline and data, it generates now a new manual segmentation
+in the `MNI152Lin` space with some new regions defined.
+The new atlas can be structured as follows:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "ps13rev2034-pipeline": {
+      "tpl-fsaverage": {
+         "pet": {
+            "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-fsaverage_atlas-ps13_dseg.json": "",
+            "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
+            "tpl-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_mimap.json": "",
+            "...": "",
+            "tpl-fsaverage_atlas-ps13_stat-std_desc-pvc_mimap.nii.gz": "",
+         },
+      },
+      "tpl-MNI152Lin": {
+         "pet": {
+            "tpl-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
+            "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
+            "tpl-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_mimap.json": "",
+            "...": "",
+            "tpl-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13rev2034_desc-nopvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13rev2034_desc-pvc_dseg.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13rev2034_dseg.json": "",
+            "tpl-MNI152Lin_atlas-ps13rev2034_dseg.tsv": "",
+         },
+      }
+   }
+})
+}}
+
 **Deriving from an existing template/atlas**.
 For example, the MIAL67ThalamicNuclei
 ([Najdenovska et al., 2018](https://doi.org/10.1038/sdata.2018.270))

From f0e8e0ed826bdd8d769f2a721241ea261ed29708 Mon Sep 17 00:00:00 2001
From: James Kent <jamesdkent21@gmail.com>
Date: Thu, 20 Jun 2024 22:25:44 -0500
Subject: [PATCH 19/47] test


From b00bdf887c69d850ab1cf35445e0cc17491d74d2 Mon Sep 17 00:00:00 2001
From: James Kent <jamesdkent21@gmail.com>
Date: Fri, 21 Jun 2024 02:04:32 -0500
Subject: [PATCH 20/47] Update src/derivatives/atlas.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/derivatives/atlas.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 58a76500b7..52c18df22f 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -50,7 +50,7 @@ several sessions and/or subjects, the derivatives-specific
     tpl-<label>/
         [cohort-<label>/]
            [<datatype>/]
-               <source_entities>[_cohort-<label>][_space-<space>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
+               tpl-<label>_<source_entities>[_cohort-<label>][_atlas-<label>][seg-<label>][_scale-<label>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
 ```
 
 where [`suffix`](../glossary.md#suffix-common_principles) will generally be existing BIDS raw modalities

From abe37b4b7c07d3a760bbf0105f3c317dc1d30440 Mon Sep 17 00:00:00 2001
From: James Kent <jamesdkent21@gmail.com>
Date: Fri, 21 Jun 2024 02:04:51 -0500
Subject: [PATCH 21/47] Update src/derivatives/atlas.md

Co-authored-by: Oscar Esteban <code@oscaresteban.es>
---
 src/derivatives/atlas.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 52c18df22f..d2a15e8867 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -835,7 +835,7 @@ index	label	network_label	hemisphere
 
 ## Atlas metadata
 
-The `[probseg|dseg|mask].json` file provides metadata to uniquely identify, describe and characterize the atlas, as well as give proper attribution to the creators.
+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.
 Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
 <table>

From d812b088823ee95e8015104fac8aa73b595e12b7 Mon Sep 17 00:00:00 2001
From: James Kent <jamesdkent21@gmail.com>
Date: Fri, 21 Jun 2024 02:57:56 -0500
Subject: [PATCH 22/47] incorporate meeting feedback in schema

---
 src/derivatives/atlas.md                      | 181 ++----------------
 src/schema/objects/columns.yaml               |  31 +++
 src/schema/objects/metadata.yaml              |  38 ++++
 .../derivatives/common_derivatives.yaml       |  21 +-
 .../derivatives/common_derivatives.yaml       |   9 +
 5 files changed, 111 insertions(+), 169 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index d2a15e8867..abbc6383f2 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -745,86 +745,13 @@ A guide for using macros can be found at
 
 ## Tabular data
 
-The `[probseg|dseg|mask|channels].tsv` file indexes and labels each node/parcel/region within the atlas.
+The `[probseg|dseg|mask].tsv` file indexes and labels each node/parcel/region within the atlas.
 This file resembles the typical Look Up Table (LUT) often shared with atlases.
 This file will be essential for downstream workflows that generate matrices or other derived files within which node/parcel/region information is required,
 as the index/label fields will be used to reference the original anatomy the index/labels are derived from.
 Additional fields can be added with their respective definition/description in the sidecar json file.
 
-<table>
-  <tr>
-   <td>index (or placeholder in fragment in reference)
-   </td>
-   <td>REQUIRED. (Integer) The number associated with the node/parcel/region (right/left hemispheres may be different).
-   </td>
-  </tr>
-  <tr>
-   <td>label
-   </td>
-   <td>RECOMMENDED. The node name
-   </td>
-  </tr>
-  <tr>
-   <td>network_id
-   </td>
-   <td>OPTIONAL. Network ID the node/parcel belongs to
-   </td>
-  </tr>
-  <tr>
-   <td>network_label
-   </td>
-   <td>OPTIONAL. Label of Network (for example, Dorsal Attention Network)
-   </td>
-  </tr>
-  <tr>
-   <td>coordinate_report_strategy
-   </td>
-   <td>OPTIONAL (RECOMMENDED if x, y, z keys are specified).  The strategy used to assess and report x, y and z coordinates of a given node/parcel/region. For example, "CenterOfMass".
-   </td>
-  </tr>
-  <tr>
-   <td>x
-   </td>
-   <td>OPTIONAL. The x-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>y
-   </td>
-   <td>OPTIONAL. The y-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>z
-   </td>
-   <td>OPTIONAL. The z-coordinate of the node in the spatial reference space (See SpatialReference in the .json file)
-   </td>
-  </tr>
-  <tr>
-   <td>hemisphere
-   </td>
-   <td>OPTIONAL. MUST BE ONE OF: "left", "right", "bilateral". Indicate whether the node/parcel/region is in the left or right hemispheres, or is available bilaterally.
-   </td>
-  </tr>
-  <tr>
-   <td>color
-   </td>
-   <td>OPTIONAL. RGB color to use for the node.
-   </td>
-  </tr>
-  <tr>
-   <td>seed
-   </td>
-   <td>OPTIONAL. Seed vertex/channel of the node/region
-   </td>
-  </tr>
-  <tr>
-   <td>region
-   </td>
-   <td>OPTIONAL. "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
-   </td>
-  </tr>
-</table>
+This is described in the [imaging derivatives](./imaging.md#common-image-derived-labels) section of the BIDS specification
 
 Example:
 ```Text
@@ -838,98 +765,17 @@ index	label	network_label	hemisphere
 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.
 Additionally, SpatialReference serves the important purpose of unambiguously identifying the space the atlas is labeled in.
 
-<table>
-  <tr>
-   <td>Name
-   </td>
-   <td>REQUIRED. Name of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>Description
-   </td>
-   <td>RECOMMENDED. Longform description of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>SpatialReference
-   </td>
-   <td>RECOMMENDED. Point to an existing atlas in a template space (URL or relative file path where this file is located).
-   </td>
-  </tr>
-  <tr>
-   <td>Resolution
-   </td>
-   <td>RECOMMENDED. Resolution atlas is provided in.
-   </td>
-  </tr>
-  <tr>
-   <td>Dimensions
-   </td>
-   <td>RECOMMENDED. Dimensions of the atlas, MUST be 3 (for deterministic atlases) or 4 (for probabilistic atlases).
-   </td>
-  </tr>
-  <tr>
-   <td>4thDimension
-   </td>
-   <td>OPTIONAL. RECOMMENDED if probabilistic atlas. Should indicate what the 4th dimension entails/refers to. MUST be "Indices" or   .
-   </td>
-  </tr>
-  <tr>
-   <td>CoordinateReportStrategy
-   </td>
-   <td>OPTIONAL. MUST BE ONE OF: "peak", "center_of_mass", "other". Indicate the method of coordinate reporting in statistically significant clusters. Could be the "peak" statistical coordinate in the cluster or the "center_of_mass" of the cluster. RECOMMENDED if x, y ,z values are set in the .tsv file.
-   </td>
-  </tr>
-  <tr>
-   <td>Authors
-   </td>
-   <td>RECOMMENDED. List of the authors involved in the creation of the atlas
-   </td>
-  </tr>
-  <tr>
-   <td>Curators
-   </td>
-   <td>RECOMMENDED. List of curators who helped make the atlas accessible in a database or dataset
-   </td>
-  </tr>
-  <tr>
-   <td>Funding
-   </td>
-   <td>RECOMMENDED. The funding source(s) involved in the atlas creation
-   </td>
-  </tr>
-  <tr>
-   <td>License
-   </td>
-   <td>RECOMMENDED. The license agreement for using the atlas.
-   </td>
-  </tr>
-  <tr>
-   <td>ReferencesAndLinks
-   </td>
-   <td>RECOMMENDED. A list of relevant references and links pertaining to the atlas.
-   </td>
-  </tr>
-  <tr>
-   <td>Species
-   </td>
-   <td>RECOMMENDED. The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
-   </td>
-  </tr>
-  <tr>
-   <td>DerivedFrom
-   </td>
-   <td>RECOMMENDED. Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
-   </td>
-  </tr>
-  <tr>
-   <td>LevelType
-   </td>
-   <td>RECOMMENDED. Indicate what analysis level the atlas was derived from, for example, "group", "individual".
-   </td>
-  </tr>
-</table>
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+       "derivatives.common_derivatives.AtlasDescription",
+   ]) }}
 
 Example:
 
@@ -948,7 +794,6 @@ Example:
   "BIDSVersion": "1.1.0",
   "Curators": "FSL team",
   "SpatialReference": "https://templateflow.s3.amazonaws.com/tpl-MNI152NLin6Asym_res-02_T1w.nii.gz",
-  "Space": "MNI152NLin6Asym",
   "Resolution": "Matched with original template resolution (2x2x3 mm^3)",
   "License": "See LICENSE file",
   "RRID": "SCR_002823",
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index ba9f86ba31..28789adf2f 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -236,6 +236,12 @@ index:
   description: |
     The label integer index.
   type: integer
+label:
+  name: label
+  display_name: label
+  description: |
+    The node name.
+  type: string
 low_cutoff:
   name: low_cutoff
   display_name: Low cutoff
@@ -310,6 +316,18 @@ name__segmentations:
   description: |
     The unique label name.
   type: string
+network_id:
+  name: network_id
+  display_name: Network ID
+  description: |
+    Network ID the node/parcel belongs to.
+  type: string
+network_label:
+  name: network_label
+  display_name: Network Label
+  description: |
+    Label of Network (for example, Dorsal Attention Network).
+  type: string
 notch:
   name: notch
   display_name: Notch frequencies
@@ -403,6 +421,13 @@ reference_frame:
     - type: string
       enum:
         - n/a
+region:
+  name: region
+  display_name: Region
+  description: |
+     "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
+  type: string
+  pattern: ^[L|l|R|r|B|b][F|f|T|t|P|p|O|o]$
 respiratory:
   name: respiratory
   display_name: Respiratory measurement
@@ -462,6 +487,12 @@ session_id:
     matching a session found in the dataset.
   type: string
   pattern: ^ses-[0-9a-zA-Z]+$
+seed:
+  name: seed
+  display_name: Seed
+  description: |
+    Seed vertex/channel of the node/region.
+  type: string
 sex:
   name: sex
   display_name: Sex
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 1c0d84e0e8..17d3f50bbf 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -498,6 +498,26 @@ ContrastBolusIngredient:
     # TODO: Add definitions for these values. (perhaps don't specify)
     - UNKNOWN
     - NONE
+CoordinateReportStrategy:
+  name: CoordinateReportStrategy
+  display_name: CoordinateReportStrategy
+  description: |
+    Indicate the method of coordinate reporting in statistically significant clusters.
+    Could be the "peak" statistical coordinate in the cluster or the
+    "center_of_mass" of the cluster.
+  enum:
+    - peak
+    - center_of_mass
+    - other
+  type: string
+Curators:
+  name: Curators
+  display_name: Curators
+  description: |
+    List of curators who helped make the atlas accessible in a database or dataset.
+  type: array
+  items:
+    type: string
 DCOffsetCorrection:
   name: DCOffsetCorrection
   display_name: DC Offset Correction
@@ -599,6 +619,12 @@ Derivative:
     from other columns (for example a summary score based on a subset of items in a
     questionnaire).
   type: boolean
+DerivedFrom:
+  name: DerivedFrom
+  display_name: DerivedFrom
+  description: |
+    Indicate what data modality the atlas was derived from, for example, "cytoarchitecture", "resting-state", "task".
+  type: string
 Description:
   name: Description
   display_name: Description
@@ -1734,6 +1760,12 @@ Levels:
             format: uri
           Description:
             type: string
+LevelType:
+  name: LevelType
+  display_name: LevelType
+  description: |
+    Indicate what analysis level the atlas was derived from, for example, "group", "individual".
+  type: string
 License:
   name: License
   display_name: License
@@ -3228,6 +3260,12 @@ SpatialReference:
             format: uri
           - type: string
             format: dataset_relative
+Species:
+  name: Species
+  display_name: Species
+  description: |
+    The species the atlas was derived from. For example, could be Human, Macaque, Rat, Mouse, etc.
+  type: string
 SpecificRadioactivity:
   name: SpecificRadioactivity
   display_name: Specific Radioactivity
diff --git a/src/schema/rules/sidecars/derivatives/common_derivatives.yaml b/src/schema/rules/sidecars/derivatives/common_derivatives.yaml
index fbc05937bc..089b9de832 100644
--- a/src/schema/rules/sidecars/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/sidecars/derivatives/common_derivatives.yaml
@@ -41,9 +41,12 @@ MaskDerivatives:
 SegmentationCommon:
   selectors:
     - dataset.dataset_description.DatasetType == "derivative"
-    - 'intersects([suffix], ["dseg", "probseg"])'
+    - 'intersects([suffix], ["dseg", "probseg", "mask"])'
   fields:
+    SpatialReference: recommended
     Manual: optional
+    CoordinateReportStrategy: optional
+
 
 # Derivatives -> Imaging data types
 ImageDerivatives:
@@ -74,3 +77,19 @@ ImageDerivativeDenEntity:
     Density:
       level: required
       level_addendum: if `den` is present
+
+AtlasDescription:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - 'intersects([suffix], ["dseg", "probseg", "mask"])'
+  fields:
+    Name: required
+    Description: recommended
+    Authors: recommended
+    Curators: recommended
+    Funding: recommended
+    License: recommended
+    ReferencesAndLinks: recommended
+    Species: recommended
+    DerivedFrom: recommended
+    LevelType: recommended
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
index 3fef5e88fa..31159d3c87 100644
--- a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -6,7 +6,16 @@ SegmentationLookup:
   columns:
     index: required
     name__segmentations: required
+    label: recommended
     abbreviation: optional
     color: optional
+    hemisphere: optional
     mapping: optional
+    network_id: optional
+    network_label: optional
+    region: optional
+    seed: optional
+    x: optional
+    y: optional
+    z: optional
   index_columns: [index]

From 3accb28efab2ce079d2fe59ee306922f472b0b55 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 7 Oct 2024 08:54:59 +0200
Subject: [PATCH 23/47] enh: add note about 'MNI Space' below template
 identifiers @CPernet

---
 src/appendices/coordinate-systems.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/appendices/coordinate-systems.md b/src/appendices/coordinate-systems.md
index c5b44207bc..0663674dfd 100644
--- a/src/appendices/coordinate-systems.md
+++ b/src/appendices/coordinate-systems.md
@@ -224,6 +224,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

From e5e27f141e1c15248acbb9ef4f14e73c02554040 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 7 Oct 2024 09:45:30 +0200
Subject: [PATCH 24/47] enh: clarify the creation of BOTH a new template AND
 atlas

These changes clarify how templates and atlases interact and are specified
together, especially when the template is not an existing one (MNI space
or fsaverage, typically).

cc/ @CPernet, @melanieganz, @mnoergaard
---
 src/derivatives/atlas.md | 304 ++++++++++++++++++++++++++++-----------
 1 file changed, 220 insertions(+), 84 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index abbc6383f2..73771f8a7c 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -126,83 +126,6 @@ A guide for using macros can be found at
 })
 }}
 
-Often, templates are necessary to bring or project information from/to an atlas.
-Derivatives provenant from an atlas MUST be encoded with the
-[`atlas-<label>` entity](../glossary.md#atlas-entities).
-The following example shows how 'Colin27' could have encoded the Automated Anatomical Labeling (AAL)
-atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
-defined on the Colin27 space:
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_filetree_example({
-   "colin27-pipeline": {
-      "sub-01": {
-         "anat": {
-            "sub-01_atlas-AAL_dseg.json": "",
-            "sub-01_atlas-AAL_dseg.nii.gz": "",
-            "sub-01_atlas-AAL_dseg.tsv": "",
-            "sub-01_atlas-AAL_probseg.nii.gz": "",
-            "sub-01_label-brain_mask.nii.gz": "",
-            "sub-01_label-head_mask.nii.gz": "",
-            "sub-01_T1w.nii.gz": "",
-            "sub-01_T1w.json": "",
-         },
-      },
-   }
-})
-}}
-
-As [the authors of 'Colin27' indicate](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27),
-it is aligned with MNI305:
-
-> In 1998, a new atlas with much higher definition than MNI305s was created at the MNI.
-> One individual (CJH) was scanned 27 times and the images linearly registered to create
-> an average with high SNR and structure definition (Holmes et al., 1998).
-> This average was linearly registered to the average 305.
-> Ironically, this dataset was not originally intended for use as a stereotaxic template
-> but as the sub-strate for an ROI parcellation scheme to be used with
-> ANIMAL non-linear spatial normalization (Collins et al., 1995),
-> i.e. it was intended for the purpose of segmentation, NOT stereotaxy.
-> As a single brain atlas, it did not capture anatomical variability and was, to some degree,
-> a reversion to the Talairach approach.
->
-> However, the high definition proved too attractive to the community and,
-> after non-linear mapping to fit the MNI305 space, it has been adopted
-> by many groups as a stereotaxic template.
-
-Therefore, this pipeline potentially could have produced outputs in the realigned T1w space
-before alignment to the MNI305 template.
-To disambiguate in this case, we employ the [`space-<label>` entity](../glossary.md#space-entities):
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_filetree_example({
-   "colin27-pipeline": {
-      "sub-01": {
-         "anat": {
-            "sub-01_space-MNI305_atlas-AAL_dseg.json": "",
-            "sub-01_space-MNI305_atlas-AAL_dseg.nii.gz": "",
-            "sub-01_space-MNI305_atlas-AAL_dseg.tsv": "",
-            "sub-01_space-MNI305_atlas-AAL_probseg.nii.gz": "",
-            "sub-01_space-MNI305_label-brain_mask.nii.gz": "",
-            "sub-01_space-MNI305_label-head_mask.nii.gz": "",
-            "sub-01_space-MNI305_T1w.nii.gz": "",
-            "sub-01_space-MNI305_T1w.json": "",
-            "sub-01_space-T1w_label-brain_mask.nii.gz": "",
-            "sub-01_space-T1w_label-head_mask.nii.gz": "",
-            "sub-01_space-T1w_T1w.nii.gz": "",
-            "sub-01_space-T1w_T1w.json": "",
-         },
-      },
-   }
-})
-}}
-
 ## Multi-subject template and atlases and deriving an existing template/atlas
 
 Atlasing multiple individual brains is a higher-than-first-level analysis,
@@ -212,7 +135,7 @@ and distill the sample-pooled knowledge and feature maps.
 Similarly, deriving from an existing template and atlases is also
 a higher-than-first-level analysis as it builds on a previous analysis.
 
-**Multi-subject templates and atlases**.
+**Multi-subject templates**.
 While at the subject level analysis it is the individual brain that establishes
 stereotaxy.
 At higher-than-first-level stereotaxy is supported by templates, which are
@@ -252,8 +175,8 @@ A guide for using macros can be found at
 })
 }}
 
-**Multi-cohort templates and atlases.**
-In the case that the template- and/or atlas-generating pipeline derives
+**Multi-cohort templates.**
+In the case that the template-generating pipeline derives
 several cohorts, the file structure must employ the
 [`cohort-<label>` directory and entity](../glossary.md#cohort-entities).
 
@@ -349,10 +272,88 @@ A guide for using macros can be found at
 })
 }}
 
-**The PS13 atlas example.**
-The [PS13 atlas](https://doi.org/10.18112/openneuro.ds004401.v1.3.0) is a
-molecular imaging brain atlas of Cyclooxygenase-1 (PET).
-The atlas is generated in two standard spaces: `MNI152Lin` and `fsaverage`:
+**Defining atlases referenced to a pre-existing template.**
+Once a standard space is instantiated by a reference template,
+atlasing knowledge MAY be specified employing the
+[`atlas-<label>` entity](../glossary.md#atlas-entities).
+
+The following example shows how 'Colin27' could have encoded the Automated Anatomical Labeling (AAL)
+atlas ([Tzourio-Mazoyer et al., 2002](https://doi.org/10.1006/nimg.2001.0978)), which was originally
+defined on the Colin27 space:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_atlas-AAL_dseg.json": "",
+            "sub-01_atlas-AAL_dseg.nii.gz": "",
+            "sub-01_atlas-AAL_dseg.tsv": "",
+            "sub-01_atlas-AAL_probseg.nii.gz": "",
+            "sub-01_label-brain_mask.nii.gz": "",
+            "sub-01_label-head_mask.nii.gz": "",
+            "sub-01_T1w.nii.gz": "",
+            "sub-01_T1w.json": "",
+         },
+      },
+   }
+})
+}}
+
+As [the authors of 'Colin27' indicate](https://www.mcgill.ca/bic/software/tools-data-analysis/anatomical-mri/atlases/colin-27),
+it is aligned with MNI305:
+
+> In 1998, a new atlas with much higher definition than MNI305s was created at the MNI.
+> One individual (CJH) was scanned 27 times and the images linearly registered to create
+> an average with high SNR and structure definition (Holmes et al., 1998).
+> This average was linearly registered to the average 305.
+> Ironically, this dataset was not originally intended for use as a stereotaxic template
+> but as the sub-strate for an ROI parcellation scheme to be used with
+> ANIMAL non-linear spatial normalization (Collins et al., 1995),
+> i.e. it was intended for the purpose of segmentation, NOT stereotaxy.
+> As a single brain atlas, it did not capture anatomical variability and was, to some degree,
+> a reversion to the Talairach approach.
+>
+> However, the high definition proved too attractive to the community and,
+> after non-linear mapping to fit the MNI305 space, it has been adopted
+> by many groups as a stereotaxic template.
+
+Therefore, this pipeline potentially could have produced outputs in the realigned T1w space
+before alignment to the MNI305 template.
+To disambiguate in this case, we employ the [`space-<label>` entity](../glossary.md#space-entities):
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "colin27-pipeline": {
+      "sub-01": {
+         "anat": {
+            "sub-01_space-MNI305_atlas-AAL_dseg.json": "",
+            "sub-01_space-MNI305_atlas-AAL_dseg.nii.gz": "",
+            "sub-01_space-MNI305_atlas-AAL_dseg.tsv": "",
+            "sub-01_space-MNI305_atlas-AAL_probseg.nii.gz": "",
+            "sub-01_space-MNI305_label-brain_mask.nii.gz": "",
+            "sub-01_space-MNI305_label-head_mask.nii.gz": "",
+            "sub-01_space-MNI305_T1w.nii.gz": "",
+            "sub-01_space-MNI305_T1w.json": "",
+            "sub-01_space-T1w_label-brain_mask.nii.gz": "",
+            "sub-01_space-T1w_label-head_mask.nii.gz": "",
+            "sub-01_space-T1w_T1w.nii.gz": "",
+            "sub-01_space-T1w_T1w.json": "",
+         },
+      },
+   }
+})
+}}
+
+For example, the [PS13 atlas](https://doi.org/10.18112/openneuro.ds004401.v1.3.0),
+a molecular imaging brain atlas of Cyclooxygenase-1 (PET),
+was generated in two standard spaces: `MNI152Lin` and `fsaverage`:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -472,6 +473,141 @@ A guide for using macros can be found at
 })
 }}
 
+**Producing a new template AND atlas.**
+Atlasing is often performed with reference to a *custom* standard space.
+In this case, a feature template map is generated from all the participant(s)
+in the study, and the atlas' artifacts are produced with reference to that
+template.
+
+Either by generating the template space with aligning to a pre-existing template,
+or by estimating a transform between templates by means of image registration,
+a new template definition MUST be employed if the new template generates
+a new [*space*](../common-principles.md#definitions).
+For example, let's imagine that PS13 first generated a template nuclear imaging
+map and after that, a corresponding [*atlas*](../common-principles.md#definitions)
+was defined.
+In that case, the [`atlas-<label>`](../glossary.md#atlas-entities) SHOULD be omitted
+except several atlases need specification:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "ps13-pipeline": {
+      "tpl-PS13": {
+         "pet": {
+            "tpl-PS13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-PS13_desc-pvc_dseg.nii.gz": "",
+            "tpl-PS13_dseg.json": "",
+            "tpl-PS13_dseg.tsv": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-nopvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-pvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-pvc_mimap.nii.gz": "",
+         },
+      },
+   }
+})
+}}
+
+Let's complete the above example by adding two new atlases to the existing
+template and (*default*) atlas:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "ps13-with-atlases-pipeline": {
+      "tpl-PS13": {
+         "pet": {
+            "tpl-PS13_atlas-Economo1916_desc-nopvc_dseg.nii.gz": "",
+            "tpl-PS13_atlas-Economo1916_desc-pvc_dseg.nii.gz": "",
+            "tpl-PS13_atlas-Economo1916_dseg.json": "",
+            "tpl-PS13_atlas-Economo1916_dseg.tsv": "",
+            "tpl-PS13_atlas-RamonCajal1908_desc-nopvc_dseg.nii.gz": "",
+            "tpl-PS13_atlas-RamonCajal1908_desc-pvc_dseg.nii.gz": "",
+            "tpl-PS13_atlas-RamonCajal1908_dseg.json": "",
+            "tpl-PS13_atlas-RamonCajal1908_dseg.tsv": "",
+            "tpl-PS13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-PS13_desc-pvc_dseg.nii.gz": "",
+            "tpl-PS13_dseg.json": "",
+            "tpl-PS13_dseg.tsv": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-nopvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-nopvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-pvc_mimap.json": "",
+            "tpl-PS13_stat-std_desc-pvc_mimap.nii.gz": "",
+         },
+      },
+   }
+})
+}}
+
+where the `atlas-RamonCajal1908` and `atlas-Economo1916` hypothetically define
+two different atlases (please note that, often, atlases are named after
+the first author and indicating a year of a reference communication).
+The original *default* or *implicit* atlas' artifacts such as
+the `tpl-PS13_desc-nopvc_dseg.nii.gz` segmentation,
+which were originally generated with the PS13 template,
+MAY take an [`atlas-<label>`](../glossary.md#atlas-entities) if they
+need to be differentiated from the original template and atlas dataset.
+However, it is RECOMMENDED that these *default* or *implicit* atlases employed
+in the *custom* space they were generated only define
+[`atlas-<label>`](../glossary.md#atlas-entities)
+if it is necessary to disambiguate two or more atlases.
+
+A further example of these template-and-atlas specifications
+is the *Spatially Unbiased Infratentorial Template (SUIT)*
+([Diedrichsen, 2006](https://doi.org/10.1016/j.neuroimage.2006.05.056)):
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+   "suit-pipeline": {
+      "tpl-SUIT": {
+         "anat": {
+            "CHANGES": "",
+            "LICENSE": "",
+            "README.md": "",
+            "dataset_description.json": "",
+            "tpl-SUIT_T1w.nii.gz": "",
+            "tpl-SUIT_atlas-Buckner2011_dseg.json": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.label.gii": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.nii.gz": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_dseg.tsv": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-17n_stat-confidence_probseg.nii.gz": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-7n_dseg.label.gii": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-7n_dseg.nii.gz": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-7n_dseg.tsv": "",
+            "tpl-SUIT_atlas-Buckner2011_seg-7n_stat-confidence_probseg.nii.gz": "",
+            "tpl-SUIT_atlas-Diedrichsen2009_dseg.json": "",
+            "tpl-SUIT_atlas-Diedrichsen2009_dseg.label.gii": "",
+            "tpl-SUIT_atlas-Diedrichsen2009_dseg.nii.gz": "",
+            "tpl-SUIT_atlas-Diedrichsen2009_dseg.tsv": "",
+            "tpl-SUIT_atlas-Diedrichsen2009_probseg.nii.gz": "",
+            "tpl-SUIT_flat.surf.gii": "",
+            "tpl-SUIT_sulc.shape.gii": "",
+         },
+      },
+   }
+})
+}}
+
+In this case, a new T1w template of the cerebellum was created, and two different
+atlases (`Diedrichsen2009`, and `Buckner2011`) were generated with respect to
+the T1w template.
+
 **Deriving from an existing template/atlas**.
 For example, the MIAL67ThalamicNuclei
 ([Najdenovska et al., 2018](https://doi.org/10.1038/sdata.2018.270))

From 8ffda51ac1c510e8fc0e8c69b5ce826ecefed87a Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 7 Oct 2024 09:56:19 +0200
Subject: [PATCH 25/47] fix: avoid using an atlas name for a segmentation label

As @CPernet mentioned, the spec was unclear because the example illustrating
``seg-`` was using an atlas name for the label.

I grepped the whole spec for ``seg-`` and only found ``seg-Desikan``.

This commit replaces that label, edits a bit the text around it and
updates the `seg-` entity definition in the schema to be more clear.

Even though its use with ``atlas-`` was already mentioned:

> For atlases, `seg-<label>` distinguish different realizations of a given
> segmentation or parcellation.
> For example, the [Yeo 2011 atlas](https://doi.org/10.1152/jn.00338.2011)
> is distributed within *FreeSurfer* with two different parcellations
> (*7 networks* and *17 networks*).

I have updated the entity's description to be more clear (hopefully).
---
 src/derivatives/imaging.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
index d8a3022a01..d5c2e43518 100644
--- a/src/derivatives/imaging.md
+++ b/src/derivatives/imaging.md
@@ -293,9 +293,11 @@ In this case, the mask suffix MUST be used,
 the [`label` entity](../appendices/entities.md#label)) SHOULD be used
 to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
-and the [`seg` entity](../appendices/entities.md#segmentation) SHOULD be defined.
+and the [`seg` entity](../appendices/entities.md#segmentation) specifying
+what segmentation generated the mask SHOULD be defined.
 
-For example:
+For example, we can specify the gray-matter mask corresponding to the
+results of a brain tissue segmentation algorithm as:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -306,8 +308,8 @@ A guide for using macros can be found at
     "pipeline": {
         "sub-001": {
             "anat": {
-                "sub-001_space-orig_seg-Desikan_label-GM_mask.nii.gz": "",
-                "sub-001_space-orig_seg-Desikan_label-GM_mask.json": "",
+                "sub-001_space-orig_seg-tissue_label-GM_mask.nii.gz": "",
+                "sub-001_space-orig_seg-tissue_label-GM_mask.json": "",
                 },
             },
         }

From d62f0d9fd36ca60cacd8631275c821bae301dbcd Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 7 Oct 2024 10:22:36 +0200
Subject: [PATCH 26/47] enh: rework the text to clarify notions: atlas,
 template, space

Makes more clear the structure of what encodes what:

- Space: an abstract concept meaning that anatomy gives raise to "space" (i.e., subjects also generate a space)
- Template: an instance of a space that represents a population by averaging features, in a way, template encodes the sample and registration algorithm to create feature maps
- Atlas: an annotation of knowledge such as partitions (or families of partitions such as 7-networks and 17-networks) in a space with reference to a template. In other words, atlas would encode the methodology to create such partitions.
- Seg(mentation): a label given to a partition of the space, which potentially instances an atlas' partition (and hence, its combined used with atlas).

cc/ @CPernet, @melanieganz, @mnoergaard
---
 src/schema/objects/common_principles.yaml | 23 +++++++++++------------
 src/schema/objects/entities.yaml          | 20 ++++++++++++++------
 2 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index ec752db4fb..9a6c082050 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -6,19 +6,17 @@
 atlas:
   display_name: Atlas
   description: |
-    Knowledge about the brain, generally formalized with reference to a standard space (see the *Template* definition)
+    Knowledge about the brain, generally formalized with reference to a standard space (see the *Template* definition above)
     by means of spatiotemporal annotations such as landmarks, segmentations, parcellations, or probability maps.
+    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).
 
-        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)).
+        To further differentiate the concept of *atlas* and *template* throughout the specification, *template* will
+        designate a standardized stereotaxy frame where some feature or features are mapped through spatial normalization
+        and then possibly averaged.
+        Conversely, *atlas* will designate a specific methodology or algorithm to create meaningful partitions 
+        and other knowledge annotations about the brain such as landmarks, with reference to a
+        *template* instantiating a *space*.
 data_acquisition:
   display_name: Data acquisition
   description: |
@@ -152,7 +150,7 @@ session:
 space:
   display_name: Space
   description: |
-    A reference [coordinate system](appendices/coordinate-systems.md) of analysis
+    A reference [coordinate system](SPEC_ROOT/appendices/coordinate-systems.md) of analysis
     engendered by the spatiotemporal distribution of neuroimaging features such as
     those given by subjects' and templates' data.
 suffix:
@@ -186,3 +184,4 @@ template:
     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.
+    In other words, *templates* are specific feature maps that instantiate an abstract *space*.
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 6340e9ff37..4b79c373b8 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -301,13 +301,21 @@ segmentation:
   display_name: Segmentation
   description: |
     The `seg-<label>` key/value pair corresponds to a custom label the user
-    MAY use to distinguish different segmentations or parcellations.
-
-    For atlases, `seg-<label>` distinguish different realizations of a given
-    segmentation or parcellation.
+    MAY use to distinguish specific partitions of the data space
+    (segmentations or parcellations).
+    
+    Segmentations and parcellations MAY or MAY NOT be associated with
+    [atlases](SPEC_ROOT/common-principles.md#definitions),
+    Therefore, `seg-<label>` SHOULD NOT be used to designate
+    [atlases](SPEC_ROOT/common-principles.md#definitions),
+    please refer to the [template and atlas section](SPEC_ROOT/derivatives/atlas.md)
+    for detailed specifications on their combined use.
+    When a segmentation *is a realization* of an atlas' segmentation or parcellation,
+    `seg-<label>` SHOULD be employed to distinguish them.
     For example, the [Yeo 2011 atlas](https://doi.org/10.1152/jn.00338.2011)
-    is distributed within *FreeSurfer* with two different parcellations
-    (*7 networks* and *17 networks*).
+    is distributed within *FreeSurfer* with two different parcellations:
+    the *7 networks* MAY be described with `seg-7n`, for instance, and
+    the *17 networks* MAY correspondingly be described with `seg-17n`.
 
     This entity is only applicable to derivative data.
   type: string

From 161db116face15e16bc6b72be03255fbe4c5d3f0 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Oct 2024 08:53:51 +0000
Subject: [PATCH 27/47] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/schema/objects/common_principles.yaml | 2 +-
 src/schema/objects/entities.yaml          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index 9a6c082050..aafd00ffab 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -14,7 +14,7 @@ atlas:
         To further differentiate the concept of *atlas* and *template* throughout the specification, *template* will
         designate a standardized stereotaxy frame where some feature or features are mapped through spatial normalization
         and then possibly averaged.
-        Conversely, *atlas* will designate a specific methodology or algorithm to create meaningful partitions 
+        Conversely, *atlas* will designate a specific methodology or algorithm to create meaningful partitions
         and other knowledge annotations about the brain such as landmarks, with reference to a
         *template* instantiating a *space*.
 data_acquisition:
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 4b79c373b8..be175fe21a 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -303,7 +303,7 @@ segmentation:
     The `seg-<label>` key/value pair corresponds to a custom label the user
     MAY use to distinguish specific partitions of the data space
     (segmentations or parcellations).
-    
+
     Segmentations and parcellations MAY or MAY NOT be associated with
     [atlases](SPEC_ROOT/common-principles.md#definitions),
     Therefore, `seg-<label>` SHOULD NOT be used to designate

From 44cb808ba39bdef152a748d7c5b92f2f1faa1ac5 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 11 Oct 2024 16:55:40 +0200
Subject: [PATCH 28/47] fix: addressing some inconsistencies about
 segmentations

---
 src/derivatives/imaging.md | 99 +++++++++++++++++++++++++-------------
 1 file changed, 66 insertions(+), 33 deletions(-)

diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
index d5c2e43518..ddbb89cb67 100644
--- a/src/derivatives/imaging.md
+++ b/src/derivatives/imaging.md
@@ -153,7 +153,7 @@ Template:
 
 A binary (1 - inside, 0 - outside) mask in the space defined by the [`space` entity](../appendices/entities.md#space).
 If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
-If the mask is an ROI mask derived from an atlas segmentation,
+If the mask is an ROI mask derived from a discrete or probabilistic segmentation,
 then the [`label` entity](../appendices/entities.md#label) SHOULD be used to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)).
 
@@ -184,8 +184,8 @@ A guide for using macros can be found at
     "func_loc": {
         "sub-001": {
             "func": {
-                "sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.nii.gz": "",
-                "sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.json": "",
+                "sub-001_task-rest_run-1_space-MNI305_label-PFC_mask.nii.gz": "",
+                "sub-001_task-rest_run-1_space-MNI305_label-PFC_mask.json": "",
                 },
             },
         }
@@ -201,8 +201,8 @@ A guide for using macros can be found at
     "manual_masks": {
         "sub-001": {
             "anat": {
-                "sub-001_desc-tumor_mask.nii.gz": "",
-                "sub-001_desc-tumor_mask.json": "",
+                "sub-001_label-tumor_mask.nii.gz": "",
+                "sub-001_label-tumor_mask.json": "",
                 },
             },
         }
@@ -211,12 +211,12 @@ A guide for using macros can be found at
 
 ## Segmentations
 
-A *segmentation* is a labeling of regions of an image such that each location
-(for example, a voxel or a surface vertex) is identified with a label or a
-combination of labels.
-Labeled regions may include anatomical structures (such as tissue class,
-Brodmann area or white matter tract), discontiguous, functionally-defined
-networks, tumors or lesions.
+A *segmentation* is a spatiotemporal partition of images and surfaces,
+such that each location and/or timepoint (for example, a voxel or a surface vertex)
+is identified with one label (discrete) or a combination of labels (probabilistic).
+Labeled regions may include anatomical structures (for example, tissue classes,
+white matter tracts, Thalamic nuclei, cortical areas),
+functionally-defined networks, tumors or lesions.
 
 A *discrete segmentation* represents each region with a unique integer
 label.
@@ -227,10 +227,13 @@ structure may be concatenated in a single file.
 Segmentations may be defined in a volume (labeled voxels), a surface (labeled
 vertices) or a combined volume/surface space.
 
-If the segmentation can be generated in different ways,
-for example, following an atlas segmentation,
-the [`seg` entity](../appendices/entities.md#segmentation) MAY be used to
-distinguish the name of the segmentation used.
+If different segmentations coexist within the same folder of the BIDS
+structure, the [`seg-<label>` entity](../appendices/entities.md#segmentation)
+SHOULD be used for disambiguation.
+
+The [`seg-<label>` entity](../appendices/entities.md#segmentation) MAY be used in combination
+with the [`atlas-<label>` entity](../appendices/entities.md#segmentation)
+as indicated by the [Templates and Atlases section](atlas.md).
 
 The following section describes discrete and probabilistic segmentations of
 volumes, followed by discrete segmentations of surface/combined spaces.
@@ -254,8 +257,7 @@ A guide for using macros can be found at
 
 ### Discrete Segmentations
 
-Discrete segmentations of brain tissue represent multiple anatomical structures
-(such as tissue class or Brodmann area) with a unique integer label in a 3D volume.
+Discrete segmentations of brain tissue represent regions with unique integer labels.
 See [Common image-derived labels](#common-image-derived-labels) for a description
 of how integer values map to anatomical structures.
 
@@ -264,11 +266,12 @@ Template:
 ```Text
 <pipeline_name>/
     sub-<label>/
-        anat|func|dwi/
+        <data_type>/
             <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_den-<label>]_dseg.nii.gz
 ```
 
-Example:
+For example, we can specify the results of a classic brain tissue segmentation algorithm
+of a T1w image based on a Gaussian mixture model as:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -279,25 +282,46 @@ A guide for using macros can be found at
     "pipeline": {
         "sub-001": {
             "anat": {
-                "sub-001_space-orig_dseg.nii.gz": "",
-                "sub-001_space-orig_dseg.json": "",
+                "sub-001_dseg.nii.gz": "",
+                "sub-001_dseg.json": "",
                 },
             },
         }
    }
 ) }}
 
-A segmentation can be used to generate a binary mask that functions as a
-discrete "label" for a single structure.
-In this case, the mask suffix MUST be used,
-the [`label` entity](../appendices/entities.md#label)) SHOULD be used
-to specify the masked structure
-(see [Common image-derived labels](#common-image-derived-labels)),
-and the [`seg` entity](../appendices/entities.md#segmentation) specifying
-what segmentation generated the mask SHOULD be defined.
+When several segmentations coexist at the same BIDS hierarchy point,
+[`seg-<label>` entity](../appendices/entities.md#segmentation) SHOULD
+be used for disambiguation.
+For example, if the brain tissue segmentation above will be stored next
+to segmentations of the eyes:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+   {
+    "pipeline": {
+        "sub-001": {
+            "anat": {
+                "sub-001_seg-braintissues_dseg.nii.gz": "",
+                "sub-001_seg-braintissues_dseg.json": "",
+                "sub-001_seg-eyes_dseg.nii.gz": "",
+                "sub-001_seg-eyes_dseg.json": "",
+                },
+            },
+        }
+   }
+) }}
 
-For example, we can specify the gray-matter mask corresponding to the
-results of a brain tissue segmentation algorithm as:
+Often, segmentations are *atlas-based*, meaning, the partition of the space is
+projected from prior knowledge in the form of an [atlas](../common-principles.md).
+In such cases, [`seg-<label>`](../appendices/entities.md#segmentation) MAY be used in combination
+with the [`atlas-<label>` entity](../appendices/entities.md#segmentation).
+Extending on our previous example, when the brain tissue and the eye
+segmentations are stored with the results of *FreeSurfer*'s automatic subcortical
+segmentation ("aseg") using the `Destrieux2009` atlas:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -308,14 +332,23 @@ A guide for using macros can be found at
     "pipeline": {
         "sub-001": {
             "anat": {
-                "sub-001_space-orig_seg-tissue_label-GM_mask.nii.gz": "",
-                "sub-001_space-orig_seg-tissue_label-GM_mask.json": "",
+                "sub-001_atlas-Destrieux2009_seg-aseg_dseg.nii.gz": "",
+                "sub-001_atlas-Destrieux2009_seg-aseg_dseg.json": "",
+                "sub-001_atlas-Destrieux2009_seg-aseg+aparc_dseg.nii.gz": "",
+                "sub-001_atlas-Destrieux2009_seg-aseg+aparc_dseg.json": "",
+                "sub-001_seg-braintissues_dseg.nii.gz": "",
+                "sub-001_seg-braintissues_dseg.json": "",
+                "sub-001_seg-eyes_dseg.nii.gz": "",
+                "sub-001_seg-eyes_dseg.json": "",
                 },
             },
         }
    }
 ) }}
 
+For further details on the [`atlas-<label>` entity](../appendices/entities.md#segmentation)
+specifications, check the [Templates and Atlases section](atlas.md).
+
 ### Probabilistic Segmentations
 
 Probabilistic segmentations of brain tissue represent a single anatomical

From c77df1048b6e17805cc5ba9d19db91286b77e88b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 11 Oct 2024 17:59:32 +0200
Subject: [PATCH 29/47] fix: add clarification about cohort

Addresses @effigies' comment https://github.com/bids-standard/bids-specification/pull/1856#discussion_r1648354737

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/derivatives/atlas.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 73771f8a7c..055b23b184 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -12,11 +12,15 @@ For derivatives with atlases in their provenance corresponding to individual sub
 the organization follows the standards for BIDS raw and derivatives.
 The following entities MAY be employed to specify template- and atlas-derived results:
 
+-    [`tpl-<label>`](../glossary.md#template-entities) is REQUIRED to specify derivatives defining
+     a [template](../common-principles.md).
 -    [`space-<label>`](../glossary.md#space-entities) is REQUIRED to disambiguate derivatives defined with
      respect to different [coordinate systems](../appendices/coordinate-systems.md), following the general
      BIDS-Derivatives specifications.
 -    [`cohort-<label>`](../glossary.md#cohort-entities) is REQUIRED to disambiguate derivatives defined with
      respect to different cohort instances of a single [space (coordinate system)](../appendices/coordinate-systems.md).
+     Please note that [`cohort-<label>`](../glossary.md#cohort-entities) MUST NOT be used if neither
+     [`tpl-<label>`](../glossary.md#template-entities) nor [`space-<label>`](../glossary.md#space-entities) are used.
 -    [`atlas-<label>`](../glossary.md#atlas-entities) is REQUIRED to encode files pertaining
      or derived from the atlas identified by the entity's label.
 -    [`seg-<label>`](../glossary.md#segmentation-entities) is REQUIRED when a single atlas has several different

From 947f2798039c0ab5b2d6b20c30732275204bc394 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Fri, 11 Oct 2024 18:02:49 +0200
Subject: [PATCH 30/47] fix: replace ``_mimap`` with ``_pet``

Follows the comment by @melanieganz: https://github.com/bids-standard/bids-specification/pull/1856#discussion_r1793440847

Co-authored-by: melanieganz <ganz@di.ku.dk>
---
 src/derivatives/atlas.md | 136 +++++++++++++++++++--------------------
 1 file changed, 68 insertions(+), 68 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index 055b23b184..fed2b30c43 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -371,30 +371,30 @@ A guide for using macros can be found at
             "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
             "tpl-fsaverage_atlas-ps13_dseg.json": "",
             "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
-            "tpl-fsaverage_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_desc-nopvc_mimap.nii.gz": "",
-            "tpl-fsaverage_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_desc-pvc_mimap.nii.gz": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_mimap.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_mimap.shape.gii": "",
-            "tpl-fsaverage_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-fsaverage_stat-std_desc-nopvc_mimap.nii.gz": "",
-            "tpl-fsaverage_stat-std_desc-pvc_mimap.json": "",
-            "tpl-fsaverage_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-fsaverage_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_desc-nopvc_pet.nii.gz": "",
+            "tpl-fsaverage_desc-pvc_pet.json": "",
+            "tpl-fsaverage_desc-pvc_pet.nii.gz": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_pet.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.json": "",
+            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_pet.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.json": "",
+            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
+            "tpl-fsaverage_stat-std_desc-nopvc_pet.json": "",
+            "tpl-fsaverage_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-fsaverage_stat-std_desc-pvc_pet.json": "",
+            "tpl-fsaverage_stat-std_desc-pvc_pet.nii.gz": "",
          },
       },
       "tpl-MNI152Lin": {
@@ -403,30 +403,30 @@ A guide for using macros can be found at
             "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
             "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
             "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_mimap.json": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_mimap.json": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtPvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtPvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-nopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_desc-nopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-pvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_desc-pvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_mimap.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_mimap.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.json": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.json": "",
+            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.json": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.json": "",
+            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtPvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-nopvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_desc-nopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_desc-pvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_desc-pvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_pet.json": "",
+            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_pet.nii.gz": "",
          },
       }
    }
@@ -453,9 +453,9 @@ A guide for using macros can be found at
             "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
             "tpl-fsaverage_atlas-ps13_dseg.json": "",
             "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
-            "tpl-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_mimap.json": "",
+            "tpl-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_pet.json": "",
             "...": "",
-            "tpl-fsaverage_atlas-ps13_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-fsaverage_atlas-ps13_stat-std_desc-pvc_pet.nii.gz": "",
          },
       },
       "tpl-MNI152Lin": {
@@ -464,9 +464,9 @@ A guide for using macros can be found at
             "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
             "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
             "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
-            "tpl-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_mimap.json": "",
+            "tpl-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_pet.json": "",
             "...": "",
-            "tpl-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_pet.nii.gz": "",
             "tpl-MNI152Lin_atlas-ps13rev2034_desc-nopvc_dseg.nii.gz": "",
             "tpl-MNI152Lin_atlas-ps13rev2034_desc-pvc_dseg.nii.gz": "",
             "tpl-MNI152Lin_atlas-ps13rev2034_dseg.json": "",
@@ -505,14 +505,14 @@ A guide for using macros can be found at
             "tpl-PS13_desc-pvc_dseg.nii.gz": "",
             "tpl-PS13_dseg.json": "",
             "tpl-PS13_dseg.tsv": "",
-            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-nopvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-pvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-nopvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-pvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-pvc_pet.nii.gz": "",
          },
       },
    }
@@ -542,14 +542,14 @@ A guide for using macros can be found at
             "tpl-PS13_desc-pvc_dseg.nii.gz": "",
             "tpl-PS13_dseg.json": "",
             "tpl-PS13_dseg.tsv": "",
-            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-fnirtNopvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-fnirtPvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-nopvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-nopvc_mimap.nii.gz": "",
-            "tpl-PS13_stat-std_desc-pvc_mimap.json": "",
-            "tpl-PS13_stat-std_desc-pvc_mimap.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-nopvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-PS13_stat-std_desc-pvc_pet.json": "",
+            "tpl-PS13_stat-std_desc-pvc_pet.nii.gz": "",
          },
       },
    }

From a5111aa41afbd90fdc24df2cda8758b748480cb8 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 10:43:30 +0200
Subject: [PATCH 31/47] fix: replace ``label-`` with ``seg-`` where applies

---
 src/derivatives/atlas.md | 46 ++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index fed2b30c43..d617c71a65 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -625,9 +625,9 @@ A guide for using macros can be found at
    "mial67thalamicnuclei-pipeline": {
       "sub-01": {
          "anat": {
-            "sub-01_label-ThalamicNuclei_dseg.json": "",
-            "sub-01_label-ThalamicNuclei_dseg.tsv": "",
-            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "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": "",
          },
@@ -635,9 +635,9 @@ A guide for using macros can be found at
       "...": "",
       "sub-67": {
          "anat": {
-            "sub-67_label-ThalamicNuclei_dseg.json": "",
-            "sub-67_label-ThalamicNuclei_dseg.tsv": "",
-            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "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": "",
          },
@@ -667,11 +667,11 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mial67thalamicnuclei-pipeline": {
-      "label-ThalamicNuclei_dseg.json": "",
-      "label-ThalamicNuclei_dseg.tsv": "",
+      "seg-ThalamicNuclei_dseg.json": "",
+      "seg-ThalamicNuclei_dseg.tsv": "",
       "sub-01": {
          "anat": {
-            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-01_T1w.nii.gz": "",
          },
@@ -679,7 +679,7 @@ A guide for using macros can be found at
       "...": "",
       "sub-67": {
          "anat": {
-            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-67_T1w.nii.gz": "",
          },
@@ -707,11 +707,11 @@ A guide for using macros can be found at
    "mial67thalamicnuclei-pipeline": {
       "atlas-MIAL67ThalamicNuclei_dseg.json": "",
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
-      "label-ThalamicNuclei_dseg.json": "",
-      "label-ThalamicNuclei_dseg.tsv": "",
+      "seg-ThalamicNuclei_dseg.json": "",
+      "seg-ThalamicNuclei_dseg.tsv": "",
       "sub-01": {
          "anat": {
-            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-01_space-MNI152NLin6Asym_T1w.nii.gz": "",
             "sub-01_T1w.nii.gz": "",
@@ -720,7 +720,7 @@ A guide for using macros can be found at
       "...": "",
       "sub-67": {
          "anat": {
-            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-67_space-MNI152NLin6Asym_T1w.nii.gz": "",
             "sub-67_T1w.nii.gz": "",
@@ -744,7 +744,7 @@ A guide for using macros can be found at
 
 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
-`label-ThalamicNuclei`), the above example translates into:
+`seg-ThalamicNuclei`), the above example translates into:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -754,12 +754,12 @@ A guide for using macros can be found at
    "mial67thalamicnuclei-pipeline": {
       "atlas-MIAL67ThalamicNuclei_dseg.json": "",
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
-      "label-ThalamicNuclei_dseg.json": "",
-      "label-ThalamicNuclei_dseg.tsv": "",
+      "seg-ThalamicNuclei_dseg.json": "",
+      "seg-ThalamicNuclei_dseg.tsv": "",
       "sub-01": {
          "anat": {
             "sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
-            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-01_T1w.nii.gz": "",
          },
@@ -768,7 +768,7 @@ A guide for using macros can be found at
       "sub-67": {
          "anat": {
             "sub-67_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
-            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-67_T1w.nii.gz": "",
          },
@@ -794,13 +794,13 @@ A guide for using macros can be found at
    "mial67thalamicnuclei-pipeline": {
       "atlas-MIAL67ThalamicNuclei_dseg.json": "",
       "atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
-      "label-ThalamicNuclei_dseg.json": "",
-      "label-ThalamicNuclei_dseg.tsv": "",
+      "seg-ThalamicNuclei_dseg.json": "",
+      "seg-ThalamicNuclei_dseg.tsv": "",
       "sub-01": {
          "anat": {
             "sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
             "sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5": "",
-            "sub-01_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-01_space-MNI152NLin6Asym_T1w.nii.gz": "",
             "sub-01_T1w.nii.gz": "",
@@ -811,7 +811,7 @@ A guide for using macros can be found at
          "anat": {
             "sub-67_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
             "sub-67_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5": "",
-            "sub-67_label-ThalamicNuclei_dseg.nii.gz": "",
+            "sub-67_seg-ThalamicNuclei_dseg.nii.gz": "",
             "sub-67_space-MNI152NLin2009cAsym_T1w.nii.gz": "",
             "sub-67_space-MNI152NLin6Asym_T1w.nii.gz": "",
             "sub-67_T1w.nii.gz": "",

From c05146c1b58f9614f907c34dae68e67596e9f9d2 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 11:05:54 +0200
Subject: [PATCH 32/47] enh: update schema according to this proposal

---
 src/schema/rules/files/deriv/imaging.yaml | 40 +++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index e037dcc10c..7519fddbea 100644
--- a/src/schema/rules/files/deriv/imaging.yaml
+++ b/src/schema/rules/files/deriv/imaging.yaml
@@ -89,9 +89,13 @@ anat_parametric_discrete_segmentation:
     - dseg
   entities:
     $ref: rules.files.raw.anat.parametric.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional
   extensions:
     - .nii.gz
@@ -105,9 +109,13 @@ anat_nonparametric_discrete_segmentation:
     - dseg
   entities:
     $ref: rules.files.raw.anat.nonparametric.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional
   extensions:
     - .nii.gz
@@ -121,9 +129,13 @@ func_discrete_segmentation:
     - dseg
   entities:
     $ref: rules.files.raw.func.func.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional
 
 dwi_discrete_segmentation:
@@ -132,9 +144,13 @@ dwi_discrete_segmentation:
     - dseg
   entities:
     $ref: rules.files.raw.dwi.dwi.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional
 
 anat_parametric_probabilistic_segmentation:
@@ -143,9 +159,13 @@ anat_parametric_probabilistic_segmentation:
     - probseg
   entities:
     $ref: rules.files.raw.anat.parametric.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     label: optional
     description: optional
 
@@ -155,9 +175,13 @@ anat_nonparametric_probabilistic_segmentation:
     - probseg
   entities:
     $ref: rules.files.raw.anat.nonparametric.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     label: optional
     description: optional
 
@@ -167,9 +191,13 @@ func_probabilistic_segmentation:
     - probseg
   entities:
     $ref: rules.files.raw.func.func.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     label: optional
     description: optional
 
@@ -179,9 +207,13 @@ dwi_probabilistic_segmentation:
     - probseg
   entities:
     $ref: rules.files.raw.dwi.dwi.entities
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     label: optional
     description: optional
 
@@ -197,9 +229,13 @@ anat_parametic_discrete_surface:
   entities:
     $ref: rules.files.raw.anat.parametric.entities
     hemisphere: optional
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional
 
 anat_nonparametic_discrete_surface:
@@ -214,7 +250,11 @@ anat_nonparametic_discrete_surface:
   entities:
     $ref: rules.files.raw.anat.nonparametric.entities
     hemisphere: optional
+    cohort: optional
     space: optional
+    atlas: optional
+    segmentation: option
     resolution: optional
     density: optional
+    scale: optional
     description: optional

From f221ad056470ee965a5312b99713f1897c96a22b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 11:07:49 +0200
Subject: [PATCH 33/47] fix: folder -> directory (pacify pre-commit)

---
 src/derivatives/imaging.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md
index ddbb89cb67..025210db37 100644
--- a/src/derivatives/imaging.md
+++ b/src/derivatives/imaging.md
@@ -227,7 +227,7 @@ structure may be concatenated in a single file.
 Segmentations may be defined in a volume (labeled voxels), a surface (labeled
 vertices) or a combined volume/surface space.
 
-If different segmentations coexist within the same folder of the BIDS
+If different segmentations coexist within the same directory of the BIDS
 structure, the [`seg-<label>` entity](../appendices/entities.md#segmentation)
 SHOULD be used for disambiguation.
 

From 9ec94cdf0238412ec376f4eb19b8d9bccbdfd5e8 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 11:20:53 +0200
Subject: [PATCH 34/47] fix: order of ``scale-`` in the schema

---
 src/schema/rules/files/deriv/imaging.yaml | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index 7519fddbea..3ecdf4f9ba 100644
--- a/src/schema/rules/files/deriv/imaging.yaml
+++ b/src/schema/rules/files/deriv/imaging.yaml
@@ -93,9 +93,9 @@ anat_parametric_discrete_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional
   extensions:
     - .nii.gz
@@ -113,9 +113,9 @@ anat_nonparametric_discrete_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional
   extensions:
     - .nii.gz
@@ -133,9 +133,9 @@ func_discrete_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional
 
 dwi_discrete_segmentation:
@@ -148,9 +148,9 @@ dwi_discrete_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional
 
 anat_parametric_probabilistic_segmentation:
@@ -163,9 +163,9 @@ anat_parametric_probabilistic_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     label: optional
     description: optional
 
@@ -179,9 +179,9 @@ anat_nonparametric_probabilistic_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     label: optional
     description: optional
 
@@ -195,9 +195,9 @@ func_probabilistic_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     label: optional
     description: optional
 
@@ -211,9 +211,9 @@ dwi_probabilistic_segmentation:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     label: optional
     description: optional
 
@@ -233,9 +233,9 @@ anat_parametic_discrete_surface:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional
 
 anat_nonparametic_discrete_surface:
@@ -254,7 +254,7 @@ anat_nonparametic_discrete_surface:
     space: optional
     atlas: optional
     segmentation: option
+    scale: optional
     resolution: optional
     density: optional
-    scale: optional
     description: optional

From 1a258b5251ebe195f20be6e1d1833088d108ac06 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 13:29:27 +0200
Subject: [PATCH 35/47] enh: refine atlas' definition in common principles

Co-authored-by: melanieganz <ganz@di.ku.dk>
---
 src/schema/objects/common_principles.yaml | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index aafd00ffab..1ccb5530d3 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -14,9 +14,8 @@ atlas:
         To further differentiate the concept of *atlas* and *template* throughout the specification, *template* will
         designate a standardized stereotaxy frame where some feature or features are mapped through spatial normalization
         and then possibly averaged.
-        Conversely, *atlas* will designate a specific methodology or algorithm to create meaningful partitions
-        and other knowledge annotations about the brain such as landmarks, with reference to a
-        *template* instantiating a *space*.
+        Conversely, *atlas* will designate a specific methodology or algorithm to create meaningful knowledge annotations
+        about the brain such as landmarks or segmentations.
 data_acquisition:
   display_name: Data acquisition
   description: |

From 79f1ea9b5f30b615b69342951be73e15207dbd64 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 13:36:11 +0200
Subject: [PATCH 36/47] enh: add "authoritative definition of spaces" to
 template

Co-authored-by: Paul Wighton <PWIGHTON@mgh.harvard.edu>
---
 src/schema/objects/common_principles.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index 1ccb5530d3..4515166d1e 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -183,4 +183,5 @@ template:
     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.
-    In other words, *templates* are specific feature maps that instantiate an abstract *space*.
+    In other words, *templates* (that is, specific feature maps) are *authoritative definitions* of *spaces*
+    in that they instantiate the abstract concept of *space*.

From 3f2bde56302dbb151303878884ea9dc1fe09306b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 20:21:23 +0200
Subject: [PATCH 37/47] enh: update schema to consider ``tpl-`` and ``cohort-``

cc @effigies @tsalo does this look reasonable? will the ``atlas/`` folder be picked up automatically?
---
 src/schema/rules/files/atlas/anat.yaml        | 210 ++++++++++++++
 src/schema/rules/files/atlas/common.yaml      |   5 +
 src/schema/rules/files/atlas/derivatives.yaml | 260 ++++++++++++++++++
 src/schema/rules/files/atlas/dwi.yaml         |  38 +++
 src/schema/rules/files/atlas/fmap.yaml        | 144 ++++++++++
 src/schema/rules/files/atlas/func.yaml        |  43 +++
 src/schema/rules/files/atlas/micr.yaml        |  36 +++
 src/schema/rules/files/atlas/perf.yaml        |  46 ++++
 src/schema/rules/files/atlas/pet.yaml         |  32 +++
 src/schema/rules/files/atlas/photo.yaml       |  29 ++
 src/schema/rules/files/raw/anat.yaml          |  27 +-
 src/schema/rules/files/raw/beh.yaml           |   3 +-
 src/schema/rules/files/raw/channels.yaml      |  12 +-
 src/schema/rules/files/raw/common.yaml        |   5 +
 src/schema/rules/files/raw/dwi.yaml           |   6 +-
 src/schema/rules/files/raw/eeg.yaml           |   3 +-
 src/schema/rules/files/raw/fmap.yaml          |  21 +-
 src/schema/rules/files/raw/func.yaml          |   6 +-
 src/schema/rules/files/raw/ieeg.yaml          |   3 +-
 src/schema/rules/files/raw/meg.yaml           |  15 +-
 src/schema/rules/files/raw/micr.yaml          |   3 +-
 src/schema/rules/files/raw/motion.yaml        |   3 +-
 src/schema/rules/files/raw/nirs.yaml          |   3 +-
 src/schema/rules/files/raw/perf.yaml          |   9 +-
 src/schema/rules/files/raw/pet.yaml           |   6 +-
 src/schema/rules/files/raw/photo.yaml         |   3 +-
 src/schema/rules/files/raw/task.yaml          |  15 +-
 27 files changed, 894 insertions(+), 92 deletions(-)
 create mode 100644 src/schema/rules/files/atlas/anat.yaml
 create mode 100644 src/schema/rules/files/atlas/common.yaml
 create mode 100644 src/schema/rules/files/atlas/derivatives.yaml
 create mode 100644 src/schema/rules/files/atlas/dwi.yaml
 create mode 100644 src/schema/rules/files/atlas/fmap.yaml
 create mode 100644 src/schema/rules/files/atlas/func.yaml
 create mode 100644 src/schema/rules/files/atlas/micr.yaml
 create mode 100644 src/schema/rules/files/atlas/perf.yaml
 create mode 100644 src/schema/rules/files/atlas/pet.yaml
 create mode 100644 src/schema/rules/files/atlas/photo.yaml
 create mode 100644 src/schema/rules/files/raw/common.yaml

diff --git a/src/schema/rules/files/atlas/anat.yaml b/src/schema/rules/files/atlas/anat.yaml
new file mode 100644
index 0000000000..0e97925486
--- /dev/null
+++ b/src/schema/rules/files/atlas/anat.yaml
@@ -0,0 +1,210 @@
+---
+nonparametric:
+  suffixes:
+    - T1w
+    - T2w
+    - PDw
+    - T2starw
+    - FLAIR
+    - inplaneT1
+    - inplaneT2
+    - PDT2
+    - angio
+    - T2star # deprecated
+    - FLASH # deprecated
+    - PD # deprecated
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    part: optional
+    chunk: optional
+
+parametric:
+  suffixes:
+    - T1map
+    - T2map
+    - T2starmap
+    - R1map
+    - R2map
+    - R2starmap
+    - PDmap
+    - MTRmap
+    - MTsat
+    - UNIT1
+    - T1rho
+    - MWFmap
+    - MTVmap
+    - Chimap
+    - S0map
+    - M0map
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    chunk: optional
+
+defacemask:
+  suffixes:
+    - defacemask
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    modality: optional
+    chunk: optional
+
+multiecho:
+  suffixes:
+    - MESE
+    - MEGRE
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: required
+    part: optional
+    chunk: optional
+
+multiflip:
+  suffixes:
+    - VFA
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    flip: required
+    part: optional
+    chunk: optional
+
+multiinversion:
+  suffixes:
+    - IRT1
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    inversion: required
+    part: optional
+    chunk: optional
+
+mp2rage:
+  suffixes:
+    - MP2RAGE
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    flip: optional
+    inversion: required
+    part: optional
+    chunk: optional
+
+vfamt:
+  suffixes:
+    - MPM
+    - MTS
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    flip: required
+    mtransfer: required
+    part: optional
+    chunk: optional
+
+mtr:
+  suffixes:
+    - MTR
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    mtransfer: required
+    part: optional
+    chunk: optional
diff --git a/src/schema/rules/files/atlas/common.yaml b/src/schema/rules/files/atlas/common.yaml
new file mode 100644
index 0000000000..cbafafa014
--- /dev/null
+++ b/src/schema/rules/files/atlas/common.yaml
@@ -0,0 +1,5 @@
+---
+baseline:
+  entities:
+    template: required
+    cohort: optional
\ No newline at end of file
diff --git a/src/schema/rules/files/atlas/derivatives.yaml b/src/schema/rules/files/atlas/derivatives.yaml
new file mode 100644
index 0000000000..7c03ae25eb
--- /dev/null
+++ b/src/schema/rules/files/atlas/derivatives.yaml
@@ -0,0 +1,260 @@
+---
+anat_parametric_volumetric:
+  $ref: rules.files.atlas.anat.parametric
+  entities:
+    $ref: rules.files.atlas.anat.parametric.entities
+    space: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+anat_nonparametric_volumetric:
+  $ref: rules.files.atlas.anat.nonparametric
+  entities:
+    $ref: rules.files.atlas.anat.nonparametric.entities
+    space: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+dwi_volumetric:
+  $ref: rules.files.atlas.dwi.dwi
+  entities:
+    $ref: rules.files.atlas.dwi.dwi.entities
+    space: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+func_volumetric:
+  $ref: rules.files.atlas.func.func
+  entities:
+    $ref: rules.files.atlas.func.func.entities
+    space: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+anat_parametric_mask:
+  $ref: rules.files.atlas.anat.parametric
+  suffixes:
+    - mask
+  entities:
+    $ref: rules.files.atlas.anat.parametric.entities
+    space: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+anat_nonparametric_mask:
+  $ref: rules.files.atlas.anat.nonparametric
+  suffixes:
+    - mask
+  entities:
+    $ref: rules.files.atlas.anat.nonparametric.entities
+    space: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+dwi_mask:
+  $ref: rules.files.atlas.dwi.dwi
+  suffixes:
+    - mask
+  entities:
+    $ref: rules.files.atlas.dwi.dwi.entities
+    space: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+func_mask:
+  $ref: rules.files.atlas.func.func
+  suffixes:
+    - mask
+  entities:
+    $ref: rules.files.atlas.func.func.entities
+    space: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+anat_parametric_discrete_segmentation:
+  $ref: rules.files.atlas.anat.parametric
+  suffixes:
+    - dseg
+  entities:
+    $ref: rules.files.atlas.anat.parametric.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+    - .tsv
+
+anat_nonparametric_discrete_segmentation:
+  $ref: rules.files.atlas.anat.nonparametric
+  suffixes:
+    - dseg
+  entities:
+    $ref: rules.files.atlas.anat.nonparametric.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+    - .tsv
+
+func_discrete_segmentation:
+  $ref: rules.files.atlas.func.func
+  suffixes:
+    - dseg
+  entities:
+    $ref: rules.files.atlas.func.func.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+dwi_discrete_segmentation:
+  $ref: rules.files.atlas.dwi.dwi
+  suffixes:
+    - dseg
+  entities:
+    $ref: rules.files.atlas.dwi.dwi.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+anat_parametric_probabilistic_segmentation:
+  $ref: rules.files.atlas.anat.parametric
+  suffixes:
+    - probseg
+  entities:
+    $ref: rules.files.atlas.anat.parametric.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+anat_nonparametric_probabilistic_segmentation:
+  $ref: rules.files.atlas.anat.nonparametric
+  suffixes:
+    - probseg
+  entities:
+    $ref: rules.files.atlas.anat.nonparametric.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+func_probabilistic_segmentation:
+  $ref: rules.files.atlas.func.func
+  suffixes:
+    - probseg
+  entities:
+    $ref: rules.files.atlas.func.func.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+dwi_probabilistic_segmentation:
+  $ref: rules.files.atlas.dwi.dwi
+  suffixes:
+    - probseg
+  entities:
+    $ref: rules.files.atlas.dwi.dwi.entities
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    label: optional
+    description: optional
+
+anat_parametic_discrete_surface:
+  $ref: rules.files.atlas.anat.parametric
+  suffixes:
+    - dseg
+  extensions:
+    - .label.gii
+    - .dlabel.nii
+    - .json
+    - .tsv
+  entities:
+    $ref: rules.files.atlas.anat.parametric.entities
+    hemisphere: optional
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
+
+anat_nonparametic_discrete_surface:
+  $ref: rules.files.atlas.anat.nonparametric
+  suffixes:
+    - dseg
+  extensions:
+    - .label.gii
+    - .dlabel.nii
+    - .json
+    - .tsv
+  entities:
+    $ref: rules.files.atlas.anat.nonparametric.entities
+    hemisphere: optional
+    cohort: optional
+    space: optional
+    atlas: optional
+    segmentation: option
+    scale: optional
+    resolution: optional
+    density: optional
+    description: optional
diff --git a/src/schema/rules/files/atlas/dwi.yaml b/src/schema/rules/files/atlas/dwi.yaml
new file mode 100644
index 0000000000..4742ea969a
--- /dev/null
+++ b/src/schema/rules/files/atlas/dwi.yaml
@@ -0,0 +1,38 @@
+---
+dwi:
+  suffixes:
+    - dwi
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+    - .bvec
+    - .bval
+  datatypes:
+    - dwi
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    part: optional
+    chunk: optional
+
+sbref:
+  suffixes:
+    - sbref
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - dwi
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    part: optional
+    chunk: optional
diff --git a/src/schema/rules/files/atlas/fmap.yaml b/src/schema/rules/files/atlas/fmap.yaml
new file mode 100644
index 0000000000..0a34c241c2
--- /dev/null
+++ b/src/schema/rules/files/atlas/fmap.yaml
@@ -0,0 +1,144 @@
+---
+fieldmaps:
+  suffixes:
+    - phasediff
+    - phase1
+    - phase2
+    - magnitude1
+    - magnitude2
+    - magnitude
+    - fieldmap
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    run: optional
+    chunk: optional
+
+pepolar:
+  suffixes:
+    - epi
+    - m0scan
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    direction: required
+    run: optional
+    part: optional
+    chunk: optional
+
+TB1DAM:
+  suffixes:
+    - TB1DAM
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    flip: required
+    inversion: optional
+    part: optional
+    chunk: optional
+
+TB1EPI:
+  suffixes:
+    - TB1EPI
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: required
+    flip: required
+    inversion: optional
+    part: optional
+    chunk: optional
+
+RFFieldMaps:
+  suffixes:
+    - TB1AFI
+    - TB1TFL
+    - TB1RFM
+    - RB1COR
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    flip: optional
+    inversion: optional
+    part: optional
+    chunk: optional
+
+TB1SRGE:
+  suffixes:
+    - TB1SRGE
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    flip: required
+    inversion: required
+    part: optional
+    chunk: optional
+
+parametric:
+  suffixes:
+    - TB1map
+    - RB1map
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - fmap
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    run: optional
+    chunk: optional
diff --git a/src/schema/rules/files/atlas/func.yaml b/src/schema/rules/files/atlas/func.yaml
new file mode 100644
index 0000000000..8515ea67e1
--- /dev/null
+++ b/src/schema/rules/files/atlas/func.yaml
@@ -0,0 +1,43 @@
+---
+func:
+  suffixes:
+    - bold
+    - cbv
+    - sbref
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - func
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: required
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    echo: optional
+    part: optional
+    chunk: optional
+
+phase:
+  suffixes:
+    - phase # deprecated
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - func
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: required
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    echo: optional
+    chunk: optional
diff --git a/src/schema/rules/files/atlas/micr.yaml b/src/schema/rules/files/atlas/micr.yaml
new file mode 100644
index 0000000000..62f6d30b1f
--- /dev/null
+++ b/src/schema/rules/files/atlas/micr.yaml
@@ -0,0 +1,36 @@
+---
+microscopy:
+  suffixes:
+    - TEM
+    - SEM
+    - uCT
+    - BF
+    - DF
+    - PC
+    - DIC
+    - FLUO
+    - CONF
+    - PLI
+    - CARS
+    - 2PE
+    - MPE
+    - SR
+    - NLO
+    - OCT
+    - SPIM
+  extensions:
+    - .ome.tif
+    - .ome.btf
+    - .ome.zarr/
+    - .png
+    - .tif
+    - .json
+  datatypes:
+    - micr
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    sample: required
+    acquisition: optional
+    stain: optional
+    run: optional
+    chunk: optional
diff --git a/src/schema/rules/files/atlas/perf.yaml b/src/schema/rules/files/atlas/perf.yaml
new file mode 100644
index 0000000000..fe1fd41a79
--- /dev/null
+++ b/src/schema/rules/files/atlas/perf.yaml
@@ -0,0 +1,46 @@
+---
+asl:
+  suffixes:
+    - asl
+    - m0scan
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - perf
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+
+aslcontext:
+  suffixes:
+    - aslcontext
+  extensions:
+    - .tsv
+  datatypes:
+    - perf
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+
+asllabeling:
+  suffixes:
+    - asllabeling
+  extensions:
+    - .jpg
+    - .png
+    - .tif
+  datatypes:
+    - perf
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    acquisition: optional
+    reconstruction: optional
+    run: optional
diff --git a/src/schema/rules/files/atlas/pet.yaml b/src/schema/rules/files/atlas/pet.yaml
new file mode 100644
index 0000000000..0733cb9a02
--- /dev/null
+++ b/src/schema/rules/files/atlas/pet.yaml
@@ -0,0 +1,32 @@
+---
+pet:
+  suffixes:
+    - pet
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - pet
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    tracer: optional
+    reconstruction: optional
+    run: optional
+
+blood:
+  suffixes:
+    - blood
+  extensions:
+    - .tsv
+    - .json
+  datatypes:
+    - pet
+  entities:
+    $ref: rules.files.atlas.common.baseline.entities
+    task: optional
+    tracer: optional
+    reconstruction: optional
+    run: optional
+    recording: required
diff --git a/src/schema/rules/files/atlas/photo.yaml b/src/schema/rules/files/atlas/photo.yaml
new file mode 100644
index 0000000000..035278bfff
--- /dev/null
+++ b/src/schema/rules/files/atlas/photo.yaml
@@ -0,0 +1,29 @@
+---
+photo:
+  suffixes:
+    - photo
+  extensions:
+    - .jpg
+    - .png
+    - .tif
+  datatypes:
+    - eeg
+    - ieeg
+    - meg
+    - nirs
+  entities:
+    $ref: rules.files.common.baseline.entities
+    acquisition: optional
+
+photo__micr:
+  $ref: rules.files.raw.photo.photo
+  extensions:
+    - .jpg
+    - .png
+    - .tif
+    - .json
+  datatypes:
+    - micr
+  entities:
+    $ref: rules.files.raw.photo.photo.entities
+    sample: required
diff --git a/src/schema/rules/files/raw/anat.yaml b/src/schema/rules/files/raw/anat.yaml
index 7a8a3234e6..8ef4212980 100644
--- a/src/schema/rules/files/raw/anat.yaml
+++ b/src/schema/rules/files/raw/anat.yaml
@@ -20,8 +20,7 @@ nonparametric:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -56,8 +55,7 @@ parametric:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -75,8 +73,7 @@ defacemask:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -96,8 +93,7 @@ multiecho:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -117,8 +113,7 @@ multiflip:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -139,8 +134,7 @@ multiinversion:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -160,8 +154,7 @@ mp2rage:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -184,8 +177,7 @@ vfamt:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -207,8 +199,7 @@ mtr:
   datatypes:
     - anat
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/raw/beh.yaml b/src/schema/rules/files/raw/beh.yaml
index 6193015295..eea9fbe3b4 100644
--- a/src/schema/rules/files/raw/beh.yaml
+++ b/src/schema/rules/files/raw/beh.yaml
@@ -9,8 +9,7 @@ noncontinuous:
   datatypes:
     - beh
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/channels.yaml b/src/schema/rules/files/raw/channels.yaml
index 06c213be17..f8dd6381bb 100644
--- a/src/schema/rules/files/raw/channels.yaml
+++ b/src/schema/rules/files/raw/channels.yaml
@@ -10,8 +10,7 @@ channels:
     - ieeg
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
@@ -43,8 +42,7 @@ coordsystem:
     - meg
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
 
 # (i)EEG has a space entity
@@ -67,8 +65,7 @@ electrodes:
     - eeg
     - ieeg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     space: optional
 
@@ -90,6 +87,5 @@ optodes:
   datatypes:
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
diff --git a/src/schema/rules/files/raw/common.yaml b/src/schema/rules/files/raw/common.yaml
new file mode 100644
index 0000000000..afd1e42506
--- /dev/null
+++ b/src/schema/rules/files/raw/common.yaml
@@ -0,0 +1,5 @@
+---
+baseline:
+  entities:
+    subject: required
+    session: optional
\ No newline at end of file
diff --git a/src/schema/rules/files/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 22b224b023..a8a318b430 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -11,8 +11,7 @@ dwi:
   datatypes:
     - dwi
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -30,8 +29,7 @@ sbref:
   datatypes:
     - dwi
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     reconstruction: optional
     direction: optional
diff --git a/src/schema/rules/files/raw/eeg.yaml b/src/schema/rules/files/raw/eeg.yaml
index 676d66dc1b..05374d556e 100644
--- a/src/schema/rules/files/raw/eeg.yaml
+++ b/src/schema/rules/files/raw/eeg.yaml
@@ -14,8 +14,7 @@ eeg:
   datatypes:
     - eeg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/fmap.yaml b/src/schema/rules/files/raw/fmap.yaml
index 056ed1d67e..ab48bca9fc 100644
--- a/src/schema/rules/files/raw/fmap.yaml
+++ b/src/schema/rules/files/raw/fmap.yaml
@@ -15,8 +15,7 @@ fieldmaps:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     run: optional
     chunk: optional
@@ -32,8 +31,7 @@ pepolar:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     direction: required
@@ -51,8 +49,7 @@ TB1DAM:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -72,8 +69,7 @@ TB1EPI:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -97,8 +93,7 @@ RFFieldMaps:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -119,8 +114,7 @@ TB1SRGE:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -142,8 +136,7 @@ parametric:
   datatypes:
     - fmap
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/raw/func.yaml b/src/schema/rules/files/raw/func.yaml
index 5e2c42b813..5d9d0f74c8 100644
--- a/src/schema/rules/files/raw/func.yaml
+++ b/src/schema/rules/files/raw/func.yaml
@@ -11,8 +11,7 @@ func:
   datatypes:
     - func
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     ceagent: optional
@@ -33,8 +32,7 @@ phase:
   datatypes:
     - func
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/raw/ieeg.yaml b/src/schema/rules/files/raw/ieeg.yaml
index 587f9bcbb8..9ea03a5bd3 100644
--- a/src/schema/rules/files/raw/ieeg.yaml
+++ b/src/schema/rules/files/raw/ieeg.yaml
@@ -15,8 +15,7 @@ ieeg:
   datatypes:
     - ieeg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/meg.yaml b/src/schema/rules/files/raw/meg.yaml
index a25ed56646..b2ef66dad7 100644
--- a/src/schema/rules/files/raw/meg.yaml
+++ b/src/schema/rules/files/raw/meg.yaml
@@ -19,8 +19,7 @@ meg:
   datatypes:
     - meg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
@@ -35,8 +34,7 @@ calibration:
   datatypes:
     - meg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition:
       level: required
       enum:
@@ -50,8 +48,7 @@ crosstalk:
   datatypes:
     - meg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition:
       level: required
       enum:
@@ -66,8 +63,7 @@ headshape:
   datatypes:
     - meg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
 
 markers:
@@ -79,8 +75,7 @@ markers:
   datatypes:
     - meg
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     acquisition: optional
     space: optional
diff --git a/src/schema/rules/files/raw/micr.yaml b/src/schema/rules/files/raw/micr.yaml
index aba1b48352..95102f5b7f 100644
--- a/src/schema/rules/files/raw/micr.yaml
+++ b/src/schema/rules/files/raw/micr.yaml
@@ -28,8 +28,7 @@ microscopy:
   datatypes:
     - micr
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     sample: required
     acquisition: optional
     stain: optional
diff --git a/src/schema/rules/files/raw/motion.yaml b/src/schema/rules/files/raw/motion.yaml
index 5ac18a4e92..660fb27e0e 100644
--- a/src/schema/rules/files/raw/motion.yaml
+++ b/src/schema/rules/files/raw/motion.yaml
@@ -8,8 +8,7 @@ motion:
   datatypes:
     - motion
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     tracksys: required
     acquisition: optional
diff --git a/src/schema/rules/files/raw/nirs.yaml b/src/schema/rules/files/raw/nirs.yaml
index 8dfc41e861..a367405807 100644
--- a/src/schema/rules/files/raw/nirs.yaml
+++ b/src/schema/rules/files/raw/nirs.yaml
@@ -8,8 +8,7 @@ nirs:
   datatypes:
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/perf.yaml b/src/schema/rules/files/raw/perf.yaml
index 2964cff31e..3bc4075407 100644
--- a/src/schema/rules/files/raw/perf.yaml
+++ b/src/schema/rules/files/raw/perf.yaml
@@ -10,8 +10,7 @@ asl:
   datatypes:
     - perf
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -25,8 +24,7 @@ aslcontext:
   datatypes:
     - perf
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -42,8 +40,7 @@ asllabeling:
   datatypes:
     - perf
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     reconstruction: optional
     run: optional
diff --git a/src/schema/rules/files/raw/pet.yaml b/src/schema/rules/files/raw/pet.yaml
index a94cb9addd..6e63a6767f 100644
--- a/src/schema/rules/files/raw/pet.yaml
+++ b/src/schema/rules/files/raw/pet.yaml
@@ -9,8 +9,7 @@ pet:
   datatypes:
     - pet
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     tracer: optional
     reconstruction: optional
@@ -25,8 +24,7 @@ blood:
   datatypes:
     - pet
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: optional
     tracer: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/raw/photo.yaml b/src/schema/rules/files/raw/photo.yaml
index f5969e2d0c..2dc5d9181c 100644
--- a/src/schema/rules/files/raw/photo.yaml
+++ b/src/schema/rules/files/raw/photo.yaml
@@ -12,8 +12,7 @@ photo:
     - meg
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
 
 photo__micr:
diff --git a/src/schema/rules/files/raw/task.yaml b/src/schema/rules/files/raw/task.yaml
index b7171e568f..5b7491163c 100644
--- a/src/schema/rules/files/raw/task.yaml
+++ b/src/schema/rules/files/raw/task.yaml
@@ -12,8 +12,7 @@ events:
     - meg
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
@@ -31,8 +30,7 @@ timeseries:
     - ieeg
     - nirs
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     acquisition: optional
     run: optional
@@ -49,8 +47,7 @@ timeseries__mri_no_task:
     - dwi
     - perf
   entities:
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     acquisition: optional
     run: optional
     reconstruction: optional
@@ -84,8 +81,7 @@ events__pet:
     - pet
   entities:
     # Most events allow acquisition, PET doesn't
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     tracer: optional
     reconstruction: optional
@@ -123,8 +119,7 @@ timeseries__pet:
     - pet
   entities:
     # Most timeseries allow acquisition, PET doesn't
-    subject: required
-    session: optional
+    $ref: rules.files.raw.common.baseline.entities
     task: required
     tracer: optional
     reconstruction: optional

From 95a85a1c1778a312d37b39baf8e626491722ce05 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 12 Oct 2024 18:23:47 +0000
Subject: [PATCH 38/47] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/schema/rules/files/atlas/common.yaml | 2 +-
 src/schema/rules/files/raw/common.yaml   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/schema/rules/files/atlas/common.yaml b/src/schema/rules/files/atlas/common.yaml
index cbafafa014..9d5b016d94 100644
--- a/src/schema/rules/files/atlas/common.yaml
+++ b/src/schema/rules/files/atlas/common.yaml
@@ -2,4 +2,4 @@
 baseline:
   entities:
     template: required
-    cohort: optional
\ No newline at end of file
+    cohort: optional
diff --git a/src/schema/rules/files/raw/common.yaml b/src/schema/rules/files/raw/common.yaml
index afd1e42506..1ca0e98a95 100644
--- a/src/schema/rules/files/raw/common.yaml
+++ b/src/schema/rules/files/raw/common.yaml
@@ -2,4 +2,4 @@
 baseline:
   entities:
     subject: required
-    session: optional
\ No newline at end of file
+    session: optional

From 0d7f9659cf2e0783466f94dcb7ecccc4e7f7d01a Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 21:54:18 +0200
Subject: [PATCH 39/47] enh(schema): add ``atlas`` to entities

---
 src/schema/rules/entities.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index 92f074b2a4..23290e5e62 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -27,6 +27,7 @@
 - split
 - recording
 - chunk
+- atlas
 - segmentation
 - scale
 - resolution

From a9fa24a1efeed71c21e0e7fe86ccc4c79b221c79 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 21:58:27 +0200
Subject: [PATCH 40/47] fix: delete photo from atlas' file rules

---
 src/schema/rules/files/atlas/photo.yaml | 29 -------------------------
 1 file changed, 29 deletions(-)
 delete mode 100644 src/schema/rules/files/atlas/photo.yaml

diff --git a/src/schema/rules/files/atlas/photo.yaml b/src/schema/rules/files/atlas/photo.yaml
deleted file mode 100644
index 035278bfff..0000000000
--- a/src/schema/rules/files/atlas/photo.yaml
+++ /dev/null
@@ -1,29 +0,0 @@
----
-photo:
-  suffixes:
-    - photo
-  extensions:
-    - .jpg
-    - .png
-    - .tif
-  datatypes:
-    - eeg
-    - ieeg
-    - meg
-    - nirs
-  entities:
-    $ref: rules.files.common.baseline.entities
-    acquisition: optional
-
-photo__micr:
-  $ref: rules.files.raw.photo.photo
-  extensions:
-    - .jpg
-    - .png
-    - .tif
-    - .json
-  datatypes:
-    - micr
-  entities:
-    $ref: rules.files.raw.photo.photo.entities
-    sample: required

From 44c3ad89ab9960e64a8481d8b817fa6892efb2f3 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 12 Oct 2024 22:11:57 +0200
Subject: [PATCH 41/47] Update src/schema/objects/columns.yaml

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/schema/objects/columns.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index 28789adf2f..7b25069d09 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -427,7 +427,7 @@ region:
   description: |
      "XY", where X can be L:left, R:right, B:bilateral, and Y can be F:frontal, T:temporal, P:parietal, O:occipital
   type: string
-  pattern: ^[L|l|R|r|B|b][F|f|T|t|P|p|O|o]$
+  pattern: ^[LRB][FTPO]$
 respiratory:
   name: respiratory
   display_name: Respiratory measurement

From b66c3ee4c697c6a55b72d611d6c123fc26314700 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 14 Oct 2024 20:50:59 +0200
Subject: [PATCH 42/47] fix: dereference twice schema files

---
 tools/schemacode/bidsschematools/schema.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/schemacode/bidsschematools/schema.py b/tools/schemacode/bidsschematools/schema.py
index 8a51725f1b..ee7bb32bef 100644
--- a/tools/schemacode/bidsschematools/schema.py
+++ b/tools/schemacode/bidsschematools/schema.py
@@ -197,6 +197,7 @@ def load_schema(schema_path=None):
     if not schema.rules:
         raise ValueError(f"rules subdirectory path not found in {schema_path}")
 
+    dereference(schema)
     dereference(schema)
     flatten_enums(schema)
 

From c3b6f41abc73e1e484afe2dbc3430e1e7d74f175 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 14 Oct 2024 21:19:36 +0200
Subject: [PATCH 43/47] fix: add missing properties to atlas entity definition

---
 src/schema/objects/entities.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index be175fe21a..12dfd1ce7a 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -34,6 +34,8 @@ atlas:
     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
     surface/vertex data, as well as gray and white matter atlases.
+  type: string
+  format: label
 ceagent:
   name: ce
   display_name: Contrast Enhancing Agent

From 891bcf01bd9638e37909302c02c314e5648a3c27 Mon Sep 17 00:00:00 2001
From: mnoergaard <martin.noergaard@nru.dk>
Date: Wed, 23 Oct 2024 10:23:13 +0200
Subject: [PATCH 44/47] FIX: update PET examples

---
 src/derivatives/atlas.md | 160 +++++++++++++++++++--------------------
 1 file changed, 76 insertions(+), 84 deletions(-)

diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
index d617c71a65..cb28b83a8f 100644
--- a/src/derivatives/atlas.md
+++ b/src/derivatives/atlas.md
@@ -276,7 +276,7 @@ A guide for using macros can be found at
 })
 }}
 
-**Defining atlases referenced to a pre-existing template.**
+**Defining atlases and templates referenced to a pre-existing template.**
 Once a standard space is instantiated by a reference template,
 atlasing knowledge MAY be specified employing the
 [`atlas-<label>` entity](../glossary.md#atlas-entities).
@@ -355,8 +355,8 @@ A guide for using macros can be found at
 })
 }}
 
-For example, the [PS13 atlas](https://doi.org/10.18112/openneuro.ds004401.v1.3.0),
-a molecular imaging brain atlas of Cyclooxygenase-1 (PET),
+For example, the [PS13 template](https://doi.org/10.18112/openneuro.ds004401.v1.3.0),
+a molecular imaging brain template of Cyclooxygenase-1 (PET),
 was generated in two standard spaces: `MNI152Lin` and `fsaverage`:
 
 <!-- This block generates a file tree.
@@ -365,70 +365,66 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "ps13-pipeline": {
-      "tpl-fsaverage": {
+      "tpl-ps13": {
          "pet": {
-            "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
-            "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
-            "tpl-fsaverage_atlas-ps13_dseg.json": "",
-            "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
-            "tpl-fsaverage_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_desc-nopvc_pet.nii.gz": "",
-            "tpl-fsaverage_desc-pvc_pet.json": "",
-            "tpl-fsaverage_desc-pvc_pet.nii.gz": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-nopvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_pet.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_desc-pvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.json": "",
-            "tpl-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-nopvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_pet.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_desc-pvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.json": "",
-            "tpl-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
-            "tpl-fsaverage_stat-std_desc-nopvc_pet.json": "",
-            "tpl-fsaverage_stat-std_desc-nopvc_pet.nii.gz": "",
-            "tpl-fsaverage_stat-std_desc-pvc_pet.json": "",
-            "tpl-fsaverage_stat-std_desc-pvc_pet.nii.gz": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_dseg.json": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_dseg.tsv": "",
+            "tpl-ps13_space-fsaverage_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_desc-nopvc_pet.nii.gz": "",
+            "tpl-ps13_space-fsaverage_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_desc-pvc_pet.nii.gz": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_desc-nopvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage-L_den-164k_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage-L_den-164k_desc-pvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-L_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_desc-nopvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_desc-pvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_stat-std_desc-nopvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_hemi-R_den-164k_stat-std_desc-pvc_pet.shape.gii": "",
+            "tpl-ps13_space-fsaverage_stat-std_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-ps13_space-fsaverage_stat-std_desc-pvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_stat-std_desc-pvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_dseg.json": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_dseg.tsv": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-fnirtNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-fnirtPvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-nopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-pvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_desc-pvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-nopvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-pvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_res-2_stat-std_desc-pvc_pet.nii.gz": "",
          },
       },
-      "tpl-MNI152Lin": {
-         "pet": {
-            "tpl-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
-            "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.json": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmNopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.json": "",
-            "tpl-MNI152Lin_res-1p5_desc-spmvbmPvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.json": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmNopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.json": "",
-            "tpl-MNI152Lin_res-1p5_stat-std_desc-spmvbmPvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtNopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtPvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_desc-fnirtPvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-nopvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_desc-nopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_desc-pvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_desc-pvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtNopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-fnirtPvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-nopvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_pet.json": "",
-            "tpl-MNI152Lin_res-2_stat-std_desc-pvc_pet.nii.gz": "",
-         },
-      }
    }
 })
 }}
@@ -449,28 +445,24 @@ A guide for using macros can be found at
    "ps13rev2034-pipeline": {
       "tpl-fsaverage": {
          "pet": {
-            "tpl-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
-            "tpl-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
-            "tpl-fsaverage_atlas-ps13_dseg.json": "",
-            "tpl-fsaverage_atlas-ps13_dseg.tsv": "",
-            "tpl-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_dseg.json": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_dseg.tsv": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_hemi-L_den-164k_desc-nopvc_pet.json": "",
+            "tpl-ps13_space-fsaverage_atlas-ps13_stat-std_desc-pvc_pet.nii.gz": "",
             "...": "",
-            "tpl-fsaverage_atlas-ps13_stat-std_desc-pvc_pet.nii.gz": "",
-         },
-      },
-      "tpl-MNI152Lin": {
-         "pet": {
-            "tpl-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13_dseg.json": "",
-            "tpl-MNI152Lin_atlas-ps13_dseg.tsv": "",
-            "tpl-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_desc-nopvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_desc-pvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_dseg.json": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_dseg.tsv": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_res-1p5_desc-spmvbmNopvc_pet.json": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_pet.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13rev2034_desc-nopvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13rev2034_desc-pvc_dseg.nii.gz": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13rev2034_dseg.json": "",
+            "tpl-ps13_space-MNI152Lin_atlas-ps13rev2034_dseg.tsv": "",
             "...": "",
-            "tpl-MNI152Lin_atlas-ps13_res-2_stat-std_desc-pvc_pet.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13rev2034_desc-nopvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13rev2034_desc-pvc_dseg.nii.gz": "",
-            "tpl-MNI152Lin_atlas-ps13rev2034_dseg.json": "",
-            "tpl-MNI152Lin_atlas-ps13rev2034_dseg.tsv": "",
          },
       }
    }

From bc6b0647a5e5b964d70aeb14b4139ce33645e8b8 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 5 Nov 2024 13:40:55 -0500
Subject: [PATCH 45/47] schema: Move templates out of rules.files

---
 src/metaschema.json                      |  3 +++
 src/schema/meta/templates.yaml           | 30 ++++++++++++++++++++++++
 src/schema/rules/files/atlas/anat.yaml   | 18 +++++++-------
 src/schema/rules/files/atlas/common.yaml |  5 ----
 src/schema/rules/files/atlas/dwi.yaml    |  4 ++--
 src/schema/rules/files/atlas/fmap.yaml   | 14 +++++------
 src/schema/rules/files/atlas/func.yaml   |  4 ++--
 src/schema/rules/files/atlas/micr.yaml   |  2 +-
 src/schema/rules/files/atlas/perf.yaml   |  6 ++---
 src/schema/rules/files/atlas/pet.yaml    |  4 ++--
 src/schema/rules/files/raw/anat.yaml     | 18 +++++++-------
 src/schema/rules/files/raw/beh.yaml      |  2 +-
 src/schema/rules/files/raw/channels.yaml |  8 +++----
 src/schema/rules/files/raw/common.yaml   |  5 ----
 src/schema/rules/files/raw/dwi.yaml      |  4 ++--
 src/schema/rules/files/raw/eeg.yaml      |  2 +-
 src/schema/rules/files/raw/fmap.yaml     | 14 +++++------
 src/schema/rules/files/raw/func.yaml     |  4 ++--
 src/schema/rules/files/raw/ieeg.yaml     |  2 +-
 src/schema/rules/files/raw/meg.yaml      | 10 ++++----
 src/schema/rules/files/raw/micr.yaml     |  2 +-
 src/schema/rules/files/raw/motion.yaml   |  2 +-
 src/schema/rules/files/raw/nirs.yaml     |  2 +-
 src/schema/rules/files/raw/perf.yaml     |  6 ++---
 src/schema/rules/files/raw/pet.yaml      |  4 ++--
 src/schema/rules/files/raw/photo.yaml    |  2 +-
 src/schema/rules/files/raw/task.yaml     | 10 ++++----
 27 files changed, 105 insertions(+), 82 deletions(-)
 create mode 100644 src/schema/meta/templates.yaml
 delete mode 100644 src/schema/rules/files/atlas/common.yaml
 delete mode 100644 src/schema/rules/files/raw/common.yaml

diff --git a/src/metaschema.json b/src/metaschema.json
index c00481b5e8..aab0f487c1 100644
--- a/src/metaschema.json
+++ b/src/metaschema.json
@@ -65,6 +65,9 @@
             "additionalProperties": false
           }
         },
+        "templates": {
+          "type": "object"
+        },
         "versions": {
           "type": "array",
           "items": {
diff --git a/src/schema/meta/templates.yaml b/src/schema/meta/templates.yaml
new file mode 100644
index 0000000000..a89a989892
--- /dev/null
+++ b/src/schema/meta/templates.yaml
@@ -0,0 +1,30 @@
+---
+# This section is unstructured, for inclusion in rules by reference
+
+# Entities that apply to most raw files
+# Include e.g.,
+#
+# filerule:
+#   entities:
+#     $ref: meta.templates.raw_base_entities
+#     task: optional
+#     ...
+#   datatypes:
+#     ...
+raw_base_entities:
+  subject: required
+  session: optional
+
+# Entities that apply to most atlas files
+# Include e.g.,
+#
+# filerule:
+#   entities:
+#     $ref: meta.templates.atlas_base_entities
+#     task: optional
+#     ...
+#   datatypes:
+#     ...
+atlas_base_entities:
+  template: required
+  cohort: optional
diff --git a/src/schema/rules/files/atlas/anat.yaml b/src/schema/rules/files/atlas/anat.yaml
index 0e97925486..bcfe29c0b1 100644
--- a/src/schema/rules/files/atlas/anat.yaml
+++ b/src/schema/rules/files/atlas/anat.yaml
@@ -20,7 +20,7 @@ nonparametric:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -55,7 +55,7 @@ parametric:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -73,7 +73,7 @@ defacemask:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -93,7 +93,7 @@ multiecho:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -113,7 +113,7 @@ multiflip:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -134,7 +134,7 @@ multiinversion:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -154,7 +154,7 @@ mp2rage:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -177,7 +177,7 @@ vfamt:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -199,7 +199,7 @@ mtr:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/atlas/common.yaml b/src/schema/rules/files/atlas/common.yaml
deleted file mode 100644
index 9d5b016d94..0000000000
--- a/src/schema/rules/files/atlas/common.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
----
-baseline:
-  entities:
-    template: required
-    cohort: optional
diff --git a/src/schema/rules/files/atlas/dwi.yaml b/src/schema/rules/files/atlas/dwi.yaml
index 4742ea969a..55f51e1ac7 100644
--- a/src/schema/rules/files/atlas/dwi.yaml
+++ b/src/schema/rules/files/atlas/dwi.yaml
@@ -11,7 +11,7 @@ dwi:
   datatypes:
     - dwi
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -29,7 +29,7 @@ sbref:
   datatypes:
     - dwi
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
diff --git a/src/schema/rules/files/atlas/fmap.yaml b/src/schema/rules/files/atlas/fmap.yaml
index 0a34c241c2..33162acc69 100644
--- a/src/schema/rules/files/atlas/fmap.yaml
+++ b/src/schema/rules/files/atlas/fmap.yaml
@@ -15,7 +15,7 @@ fieldmaps:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     run: optional
     chunk: optional
@@ -31,7 +31,7 @@ pepolar:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     direction: required
@@ -49,7 +49,7 @@ TB1DAM:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -69,7 +69,7 @@ TB1EPI:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -93,7 +93,7 @@ RFFieldMaps:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -114,7 +114,7 @@ TB1SRGE:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -136,7 +136,7 @@ parametric:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/atlas/func.yaml b/src/schema/rules/files/atlas/func.yaml
index 8515ea67e1..586a0eb342 100644
--- a/src/schema/rules/files/atlas/func.yaml
+++ b/src/schema/rules/files/atlas/func.yaml
@@ -11,7 +11,7 @@ func:
   datatypes:
     - func
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: required
     acquisition: optional
     ceagent: optional
@@ -32,7 +32,7 @@ phase:
   datatypes:
     - func
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: required
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/atlas/micr.yaml b/src/schema/rules/files/atlas/micr.yaml
index 62f6d30b1f..9ffd68e465 100644
--- a/src/schema/rules/files/atlas/micr.yaml
+++ b/src/schema/rules/files/atlas/micr.yaml
@@ -28,7 +28,7 @@ microscopy:
   datatypes:
     - micr
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     sample: required
     acquisition: optional
     stain: optional
diff --git a/src/schema/rules/files/atlas/perf.yaml b/src/schema/rules/files/atlas/perf.yaml
index fe1fd41a79..aec5ae7b80 100644
--- a/src/schema/rules/files/atlas/perf.yaml
+++ b/src/schema/rules/files/atlas/perf.yaml
@@ -10,7 +10,7 @@ asl:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -24,7 +24,7 @@ aslcontext:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -40,7 +40,7 @@ asllabeling:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     acquisition: optional
     reconstruction: optional
     run: optional
diff --git a/src/schema/rules/files/atlas/pet.yaml b/src/schema/rules/files/atlas/pet.yaml
index 0733cb9a02..277d28bf8a 100644
--- a/src/schema/rules/files/atlas/pet.yaml
+++ b/src/schema/rules/files/atlas/pet.yaml
@@ -9,7 +9,7 @@ pet:
   datatypes:
     - pet
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     tracer: optional
     reconstruction: optional
@@ -24,7 +24,7 @@ blood:
   datatypes:
     - pet
   entities:
-    $ref: rules.files.atlas.common.baseline.entities
+    $ref: meta.templates.atlas_base_entities
     task: optional
     tracer: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/raw/anat.yaml b/src/schema/rules/files/raw/anat.yaml
index 8ef4212980..bc19e331ae 100644
--- a/src/schema/rules/files/raw/anat.yaml
+++ b/src/schema/rules/files/raw/anat.yaml
@@ -20,7 +20,7 @@ nonparametric:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -55,7 +55,7 @@ parametric:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -73,7 +73,7 @@ defacemask:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -93,7 +93,7 @@ multiecho:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -113,7 +113,7 @@ multiflip:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -134,7 +134,7 @@ multiinversion:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -154,7 +154,7 @@ mp2rage:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -177,7 +177,7 @@ vfamt:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
@@ -199,7 +199,7 @@ mtr:
   datatypes:
     - anat
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/raw/beh.yaml b/src/schema/rules/files/raw/beh.yaml
index eea9fbe3b4..8757a3206f 100644
--- a/src/schema/rules/files/raw/beh.yaml
+++ b/src/schema/rules/files/raw/beh.yaml
@@ -9,7 +9,7 @@ noncontinuous:
   datatypes:
     - beh
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/channels.yaml b/src/schema/rules/files/raw/channels.yaml
index b5f0ba2617..76996a7468 100644
--- a/src/schema/rules/files/raw/channels.yaml
+++ b/src/schema/rules/files/raw/channels.yaml
@@ -10,7 +10,7 @@ channels:
     - ieeg
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
@@ -42,7 +42,7 @@ coordsystem:
     - meg
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
 
@@ -66,7 +66,7 @@ electrodes:
     - eeg
     - ieeg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     run: optional
@@ -90,5 +90,5 @@ optodes:
   datatypes:
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
diff --git a/src/schema/rules/files/raw/common.yaml b/src/schema/rules/files/raw/common.yaml
deleted file mode 100644
index 1ca0e98a95..0000000000
--- a/src/schema/rules/files/raw/common.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
----
-baseline:
-  entities:
-    subject: required
-    session: optional
diff --git a/src/schema/rules/files/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 0740930b56..f11e7642fd 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -11,7 +11,7 @@ dwi:
   datatypes:
     - dwi
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -29,7 +29,7 @@ sbref:
   datatypes:
     - dwi
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
diff --git a/src/schema/rules/files/raw/eeg.yaml b/src/schema/rules/files/raw/eeg.yaml
index 05374d556e..6ce05c8703 100644
--- a/src/schema/rules/files/raw/eeg.yaml
+++ b/src/schema/rules/files/raw/eeg.yaml
@@ -14,7 +14,7 @@ eeg:
   datatypes:
     - eeg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/fmap.yaml b/src/schema/rules/files/raw/fmap.yaml
index 37166c7c78..be1f7df34e 100644
--- a/src/schema/rules/files/raw/fmap.yaml
+++ b/src/schema/rules/files/raw/fmap.yaml
@@ -15,7 +15,7 @@ fieldmaps:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     run: optional
     chunk: optional
@@ -51,7 +51,7 @@ pepolar_m0scan:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     direction: required
@@ -69,7 +69,7 @@ TB1DAM:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -89,7 +89,7 @@ TB1EPI:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -113,7 +113,7 @@ RFFieldMaps:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -134,7 +134,7 @@ TB1SRGE:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
@@ -156,7 +156,7 @@ parametric:
   datatypes:
     - fmap
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     ceagent: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/raw/func.yaml b/src/schema/rules/files/raw/func.yaml
index 431cb3bbff..f54a8f3e02 100644
--- a/src/schema/rules/files/raw/func.yaml
+++ b/src/schema/rules/files/raw/func.yaml
@@ -11,7 +11,7 @@ func:
   datatypes:
     - func
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     ceagent: optional
@@ -40,7 +40,7 @@ phase:
   datatypes:
     - func
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     ceagent: optional
diff --git a/src/schema/rules/files/raw/ieeg.yaml b/src/schema/rules/files/raw/ieeg.yaml
index bd5695f70b..774d20533f 100644
--- a/src/schema/rules/files/raw/ieeg.yaml
+++ b/src/schema/rules/files/raw/ieeg.yaml
@@ -16,7 +16,7 @@ ieeg:
   datatypes:
     - ieeg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/meg.yaml b/src/schema/rules/files/raw/meg.yaml
index b2ef66dad7..438022accf 100644
--- a/src/schema/rules/files/raw/meg.yaml
+++ b/src/schema/rules/files/raw/meg.yaml
@@ -19,7 +19,7 @@ meg:
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
@@ -34,7 +34,7 @@ calibration:
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition:
       level: required
       enum:
@@ -48,7 +48,7 @@ crosstalk:
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition:
       level: required
       enum:
@@ -63,7 +63,7 @@ headshape:
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
 
 markers:
@@ -75,7 +75,7 @@ markers:
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     acquisition: optional
     space: optional
diff --git a/src/schema/rules/files/raw/micr.yaml b/src/schema/rules/files/raw/micr.yaml
index b5ab3355e3..5539d3d43d 100644
--- a/src/schema/rules/files/raw/micr.yaml
+++ b/src/schema/rules/files/raw/micr.yaml
@@ -29,7 +29,7 @@ microscopy:
   datatypes:
     - micr
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     sample: required
     acquisition: optional
     stain: optional
diff --git a/src/schema/rules/files/raw/motion.yaml b/src/schema/rules/files/raw/motion.yaml
index 660fb27e0e..c71e09f6df 100644
--- a/src/schema/rules/files/raw/motion.yaml
+++ b/src/schema/rules/files/raw/motion.yaml
@@ -8,7 +8,7 @@ motion:
   datatypes:
     - motion
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     tracksys: required
     acquisition: optional
diff --git a/src/schema/rules/files/raw/nirs.yaml b/src/schema/rules/files/raw/nirs.yaml
index a367405807..41f3062784 100644
--- a/src/schema/rules/files/raw/nirs.yaml
+++ b/src/schema/rules/files/raw/nirs.yaml
@@ -8,7 +8,7 @@ nirs:
   datatypes:
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
diff --git a/src/schema/rules/files/raw/perf.yaml b/src/schema/rules/files/raw/perf.yaml
index 9979243001..1668c8eeba 100644
--- a/src/schema/rules/files/raw/perf.yaml
+++ b/src/schema/rules/files/raw/perf.yaml
@@ -10,7 +10,7 @@ asl:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -26,7 +26,7 @@ aslcontext:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     reconstruction: optional
     direction: optional
@@ -42,7 +42,7 @@ asllabeling:
   datatypes:
     - perf
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     reconstruction: optional
     run: optional
diff --git a/src/schema/rules/files/raw/pet.yaml b/src/schema/rules/files/raw/pet.yaml
index 6e63a6767f..fac07a5c7c 100644
--- a/src/schema/rules/files/raw/pet.yaml
+++ b/src/schema/rules/files/raw/pet.yaml
@@ -9,7 +9,7 @@ pet:
   datatypes:
     - pet
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     tracer: optional
     reconstruction: optional
@@ -24,7 +24,7 @@ blood:
   datatypes:
     - pet
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: optional
     tracer: optional
     reconstruction: optional
diff --git a/src/schema/rules/files/raw/photo.yaml b/src/schema/rules/files/raw/photo.yaml
index 2dc5d9181c..49914099ed 100644
--- a/src/schema/rules/files/raw/photo.yaml
+++ b/src/schema/rules/files/raw/photo.yaml
@@ -12,7 +12,7 @@ photo:
     - meg
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
 
 photo__micr:
diff --git a/src/schema/rules/files/raw/task.yaml b/src/schema/rules/files/raw/task.yaml
index 829c886268..fd40cbac8c 100644
--- a/src/schema/rules/files/raw/task.yaml
+++ b/src/schema/rules/files/raw/task.yaml
@@ -12,7 +12,7 @@ events:
     - meg
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
@@ -30,7 +30,7 @@ timeseries:
     - ieeg
     - nirs
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     acquisition: optional
     run: optional
@@ -47,7 +47,7 @@ timeseries__mri_no_task:
     - dwi
     - perf
   entities:
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     acquisition: optional
     run: optional
     reconstruction: optional
@@ -81,7 +81,7 @@ events__pet:
     - pet
   entities:
     # Most events allow acquisition, PET doesn't
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     tracer: optional
     reconstruction: optional
@@ -141,7 +141,7 @@ timeseries__pet:
     - pet
   entities:
     # Most timeseries allow acquisition, PET doesn't
-    $ref: rules.files.raw.common.baseline.entities
+    $ref: meta.templates.raw_base_entities
     task: required
     tracer: optional
     reconstruction: optional

From 226f134b93a6954048c4ef4fee0b8db61d298b49 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 5 Nov 2024 13:41:21 -0500
Subject: [PATCH 46/47] test: Fix check to avoid overlap between
 common_principles and common

---
 tools/schemacode/bidsschematools/tests/test_render_text.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/schemacode/bidsschematools/tests/test_render_text.py b/tools/schemacode/bidsschematools/tests/test_render_text.py
index e6745c8780..32a00908f5 100644
--- a/tools/schemacode/bidsschematools/tests/test_render_text.py
+++ b/tools/schemacode/bidsschematools/tests/test_render_text.py
@@ -60,9 +60,9 @@ def test_make_glossary(schema_obj, schema_dir):
     for line in glossary.split("\n"):
         if line.startswith('<a name="objects.'):
             # Are all objects objects?
-            assert any([line.startswith(f'<a name="objects.{i}') for i in object_files])
+            assert any([line.startswith(f'<a name="objects.{i}.') for i in object_files])
             # Are rules loaded incorrectly?
-            assert not any([line.startswith(f'<a name="objects.{i}') for i in rules_only])
+            assert not any([line.startswith(f'<a name="objects.{i}.') for i in rules_only])
 
 
 def test_make_filename_template(schema_obj, schema_dir):

From ac745e678815bdf7a0e8965f48ee28e0cff32448 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 5 Nov 2024 13:45:44 -0500
Subject: [PATCH 47/47] schema: Update metaschema, fix errors caught by
 metaschema

---
 src/metaschema.json                           | 12 +++++++++++
 src/schema/rules/files/atlas/derivatives.yaml | 20 +++++++++----------
 src/schema/rules/files/deriv/imaging.yaml     | 20 +++++++++----------
 3 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/src/metaschema.json b/src/metaschema.json
index aab0f487c1..23c858543a 100644
--- a/src/metaschema.json
+++ b/src/metaschema.json
@@ -361,6 +361,18 @@
               "required": ["core", "tables"],
               "additionalProperties": false
             },
+            "atlas": {
+              "type": "object",
+              "patternProperties": {
+                "^[a-z_]+$": {
+                  "type": "object",
+                  "patternProperties": {
+                    "^[a-zA-Z0-9_]+$": { "$ref": "#/definitions/suffixRule" }
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
             "deriv": {
               "type": "object",
               "patternProperties": {
diff --git a/src/schema/rules/files/atlas/derivatives.yaml b/src/schema/rules/files/atlas/derivatives.yaml
index 7c03ae25eb..3c6eef8595 100644
--- a/src/schema/rules/files/atlas/derivatives.yaml
+++ b/src/schema/rules/files/atlas/derivatives.yaml
@@ -92,7 +92,7 @@ anat_parametric_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -112,7 +112,7 @@ anat_nonparametric_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -132,7 +132,7 @@ func_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -147,7 +147,7 @@ dwi_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -162,7 +162,7 @@ anat_parametric_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -178,7 +178,7 @@ anat_nonparametric_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -194,7 +194,7 @@ func_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -210,7 +210,7 @@ dwi_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -232,7 +232,7 @@ anat_parametic_discrete_surface:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -253,7 +253,7 @@ anat_nonparametic_discrete_surface:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index f1a6cc63f6..5da448e324 100644
--- a/src/schema/rules/files/deriv/imaging.yaml
+++ b/src/schema/rules/files/deriv/imaging.yaml
@@ -101,7 +101,7 @@ anat_parametric_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -121,7 +121,7 @@ anat_nonparametric_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -141,7 +141,7 @@ func_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -156,7 +156,7 @@ dwi_discrete_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -171,7 +171,7 @@ anat_parametric_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -187,7 +187,7 @@ anat_nonparametric_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -203,7 +203,7 @@ func_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -219,7 +219,7 @@ dwi_probabilistic_segmentation:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -241,7 +241,7 @@ anat_parametic_discrete_surface:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional
@@ -262,7 +262,7 @@ anat_nonparametic_discrete_surface:
     cohort: optional
     space: optional
     atlas: optional
-    segmentation: option
+    segmentation: optional
     scale: optional
     resolution: optional
     density: optional