ENH: Add templates.tsv and cohorts.tsv for template/cohort entity metadata

yarikoptic · claude · yarikoptic · commit 5e1ac9b3f31d · 2025-12-19T21:27:55.000-05:00
Introduce templates.tsv and cohorts.tsv files consistent with existing BIDS entity-specific TSV files (participants.tsv, sessions.tsv). - templates.tsv: placed at derivative dataset root, describes tpl-<label> entities - cohorts.tsv: placed within tpl-<label>/ directory, describes cohort-<label> entities This enables consistent documentation of template and cohort entities in derivative datasets. Part of BEP038 atlas metadata improvements. Schema changes: - Add template_id and cohort_id columns to columns.yaml - Add templates and cohorts suffixes to suffixes.yaml - Add Templates and Cohorts rules to common_derivatives.yaml - Add templates and cohorts file rules to tables.yaml - Update atlas.md with templates.tsv and cohorts.tsv documentation Related to: - #2285 - #2283 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/src/derivatives/atlas.md b/src/derivatives/atlas.md
@@ -76,6 +76,79 @@ as described in the [Derived atlases](#derived-atlases) section, below.
 For uses of the `atlas-` entity without the `tpl-` entity,
 see [Imaging derivatives - Derivatives from atlases](imaging.md#derivatives-from-atlases).
 
+### templates.tsv
+
+Template:
+
+```Text
+<pipeline_name>/
+    templates.tsv
+    templates.json
+```
+
+Optional: Yes
+
+To keep a record of templates in the dataset, a `templates.tsv` file MAY be used.
+The `templates.tsv` file consists of one row for each unique `tpl-<label>`
+entity used in the dataset and a set of REQUIRED and OPTIONAL columns:
+
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/*.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("derivatives.common_derivatives.Templates") }}
+
+This file MUST be located at the root of the derivative dataset.
+
+`templates.tsv` example:
+
+```tsv
+template_id	description
+tpl-MNI152NLin2009cAsym	MNI152 nonlinear 2009c asymmetric template
+tpl-MNIPediatricAsym	MNI pediatric asymmetric template
+```
+
+### cohorts.tsv
+
+Template:
+
+```Text
+<pipeline_name>/
+    tpl-<label>/
+        tpl-<label>_cohorts.tsv
+        tpl-<label>_cohorts.json
+```
+
+Optional: Yes
+
+For templates with multiple cohorts, a `cohorts.tsv` file MAY be used to describe each cohort.
+The `cohorts.tsv` file consists of one row for each unique `cohort-<label>`
+entity used within the template and a set of REQUIRED and OPTIONAL columns:
+
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/*.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("derivatives.common_derivatives.Cohorts") }}
+
+This file MUST be located within the `tpl-<label>/` directory for which it describes cohorts.
+
+`tpl-MNIPediatricAsym_cohorts.tsv` example:
+
+```tsv
+cohort_id	description
+cohort-1	Ages 0-2 months
+cohort-2	Ages 3-5 months
+cohort-3	Ages 6-11 months
+cohort-4	Ages 1-2 years
+cohort-5	Ages 3-6 years
+cohort-6	Ages 7-18 years
+```
+
 ### Example: Single-cohort template
 
 For the pipeline that generated [`MNI152NLin2009cAsym`](../appendices/coordinate-systems.md#standard-template-identifiers),
@@ -87,6 +160,7 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mni152nlin2009casym-pipeline": {
+      "templates.tsv": "",
       "tpl-MNI152NLin2009cAsym": {
          "tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz": "",
          "tpl-MNI152NLin2009cAsym_res-1_T1w.json": "",
@@ -117,7 +191,9 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mnipediatricasym-pipeline": {
+      "templates.tsv": "",
       "tpl-MNIPediatricAsym": {
+         "tpl-MNIPediatricAsym_cohorts.tsv": "",
          "cohort-1": {
             "tpl-MNIPediatricAsym_cohort-1_T1w.nii.gz": "",
             "tpl-MNIPediatricAsym_cohort-1_T2w.nii.gz": "",
@@ -152,6 +228,7 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example({
    "mni152nlin2009casym-pipeline": {
+      "templates.tsv": "",
       "sub-001": {
          "anat": {
             "sub-001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
@@ -120,6 +120,22 @@ derived_from:
     for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`).
   type: string
   pattern: ^sample-[0-9a-zA-Z+]+$
+cohort_id:
+  name: cohort_id
+  display_name: Cohort ID
+  description: |
+    A cohort identifier of the form `cohort-<label>`,
+    matching a cohort entity found in the dataset.
+
+    The `cohort_id` column contains the labels used with the
+    [`cohort` entity](SPEC_ROOT/appendices/entities.md#cohort),
+    within the particular nesting that the `cohorts.tsv` file is placed.
+
+    For example, if the `cohorts.tsv` file is placed within a `tpl-<label>/` directory,
+    its `cohort_id` column SHOULD contain all labels of the `cohort` entity
+    used within that template directory.
+  type: string
+  pattern: ^cohort-[0-9a-zA-Z+]+$
 desc_id:
   name: desc_id
   display_name: Description Label
@@ -913,6 +929,22 @@ template_y:
   description: |
     Assumed or ideal position along the y axis.
   type: number
+template_id:
+  name: template_id
+  display_name: Template ID
+  description: |
+    A template identifier of the form `tpl-<label>`,
+    matching a template entity found in the dataset.
+
+    The `template_id` column contains the labels used with the
+    [`tpl` entity](SPEC_ROOT/appendices/entities.md#tpl),
+    within the particular nesting that the `templates.tsv` file is placed.
+
+    For example, if the `templates.tsv` file is placed at the root of the derivative dataset,
+    its `template_id` column SHOULD contain all labels of the `tpl` entity
+    used across the entire derivative dataset.
+  type: string
+  pattern: ^tpl-[0-9a-zA-Z+]+$
 template_z:
   name: template_z
   display_name: Z template position
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
@@ -566,6 +566,15 @@ colFA:
     image color is determined by the principal eigenvector of the diffusion tensor,
     where red encodes the magnitude of the left-right component of that orientation,
     with green and blue similarly encoding the anterior-posterior and inferior-superior components respectively.
+cohorts:
+  value: cohorts
+  display_name: Cohort Entity Definitions
+  description: |
+    A TSV file describing labels found for the `cohort` entity within a template.
+
+    This file MUST be located within a `tpl-<label>/` directory.
+
+    The `cohorts.tsv` file provides metadata to identify and describe cohorts in the template.
 coordsystem:
   value: coordsystem
   display_name: Coordinate System File
@@ -870,6 +879,15 @@ stim:
   display_name: Continuous recording
   description: |
     Continuous measures, such as parameters of a film or audio stimulus.
+templates:
+  value: templates
+  display_name: Template Entity Definitions
+  description: |
+    A TSV file describing labels found for the `tpl` entity in a Derivatives dataset.
+
+    This file MAY be located at the root of the derivative dataset.
+
+    The `templates.tsv` file provides metadata to identify and describe templates in the dataset.
 svs:
   value: svs
   display_name: Single-voxel spectroscopy
diff --git a/src/schema/rules/files/deriv/tables.yaml b/src/schema/rules/files/deriv/tables.yaml
@@ -1,4 +1,27 @@
 ---
+templates:
+  selectors:
+    - dataset.dataset_description.DatasetType == 'derivative'
+  level: optional
+  suffixes:
+    - templates
+  extensions:
+    - .tsv
+    - .json
+  entities: {}
+
+cohorts:
+  selectors:
+    - dataset.dataset_description.DatasetType == 'derivative'
+  level: optional
+  suffixes:
+    - cohorts
+  extensions:
+    - .tsv
+    - .json
+  entities:
+    template: required
+
 descriptions:
   selectors:
     - dataset.dataset_description.DatasetType == 'derivative'
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -12,6 +12,38 @@ SegmentationLookup:
   index_columns: [index]
   additional_columns: allowed
 
+Templates:
+  selectors:
+    - suffix == "templates"
+    - extension == ".tsv"
+  initial_columns:
+    - template_id
+    - description__entities
+  columns:
+    template_id: required
+    description__entities:
+      level: required
+      description_addendum: |
+        The corresponding label column is `template_id`.
+  index_columns: [template_id]
+  additional_columns: allowed
+
+Cohorts:
+  selectors:
+    - suffix == "cohorts"
+    - extension == ".tsv"
+  initial_columns:
+    - cohort_id
+    - description__entities
+  columns:
+    cohort_id: required
+    description__entities:
+      level: required
+      description_addendum: |
+        The corresponding label column is `cohort_id`.
+  index_columns: [cohort_id]
+  additional_columns: allowed
+
 Descriptions:
   selectors:
     - suffix == "descriptions"
