Skip to content

Commit 5e1ac9b

Browse files
yarikopticclaude
yarikoptic
and
claude
committed
ENH: Add templates.tsv and cohorts.tsv for template/cohort entity metadata
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>
1 parent e7ab432 commit 5e1ac9b

5 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎src/derivatives/atlas.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,79 @@ as described in the [Derived atlases](#derived-atlases) section, below.
7676
For uses of the `atlas-` entity without the `tpl-` entity,
7777
see [Imaging derivatives - Derivatives from atlases](imaging.md#derivatives-from-atlases).
7878

79+
### templates.tsv
80+
81+
Template:
82+
83+
```Text
84+
<pipeline_name>/
85+
templates.tsv
86+
templates.json
87+
```
88+
89+
Optional: Yes
90+
91+
To keep a record of templates in the dataset, a `templates.tsv` file MAY be used.
92+
The `templates.tsv` file consists of one row for each unique `tpl-<label>`
93+
entity used in the dataset and a set of REQUIRED and OPTIONAL columns:
94+
95+
<!-- This block generates a columns table.
96+
The definitions of these fields can be found in
97+
src/schema/rules/tabular_data/*.yaml
98+
and a guide for using macros can be found at
99+
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
100+
-->
101+
{{ MACROS___make_columns_table("derivatives.common_derivatives.Templates") }}
102+
103+
This file MUST be located at the root of the derivative dataset.
104+
105+
`templates.tsv` example:
106+
107+
```tsv
108+
template_id description
109+
tpl-MNI152NLin2009cAsym MNI152 nonlinear 2009c asymmetric template
110+
tpl-MNIPediatricAsym MNI pediatric asymmetric template
111+
```
112+
113+
### cohorts.tsv
114+
115+
Template:
116+
117+
```Text
118+
<pipeline_name>/
119+
tpl-<label>/
120+
tpl-<label>_cohorts.tsv
121+
tpl-<label>_cohorts.json
122+
```
123+
124+
Optional: Yes
125+
126+
For templates with multiple cohorts, a `cohorts.tsv` file MAY be used to describe each cohort.
127+
The `cohorts.tsv` file consists of one row for each unique `cohort-<label>`
128+
entity used within the template and a set of REQUIRED and OPTIONAL columns:
129+
130+
<!-- This block generates a columns table.
131+
The definitions of these fields can be found in
132+
src/schema/rules/tabular_data/*.yaml
133+
and a guide for using macros can be found at
134+
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
135+
-->
136+
{{ MACROS___make_columns_table("derivatives.common_derivatives.Cohorts") }}
137+
138+
This file MUST be located within the `tpl-<label>/` directory for which it describes cohorts.
139+
140+
`tpl-MNIPediatricAsym_cohorts.tsv` example:
141+
142+
```tsv
143+
cohort_id description
144+
cohort-1 Ages 0-2 months
145+
cohort-2 Ages 3-5 months
146+
cohort-3 Ages 6-11 months
147+
cohort-4 Ages 1-2 years
148+
cohort-5 Ages 3-6 years
149+
cohort-6 Ages 7-18 years
150+
```
151+
79152
### Example: Single-cohort template
80153

81154
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
87160
-->
88161
{{ MACROS___make_filetree_example({
89162
"mni152nlin2009casym-pipeline": {
163+
"templates.tsv": "",
90164
"tpl-MNI152NLin2009cAsym": {
91165
"tpl-MNI152NLin2009cAsym_res-1_T1w.nii.gz": "",
92166
"tpl-MNI152NLin2009cAsym_res-1_T1w.json": "",
@@ -117,7 +191,9 @@ A guide for using macros can be found at
117191
-->
118192
{{ MACROS___make_filetree_example({
119193
"mnipediatricasym-pipeline": {
194+
"templates.tsv": "",
120195
"tpl-MNIPediatricAsym": {
196+
"tpl-MNIPediatricAsym_cohorts.tsv": "",
121197
"cohort-1": {
122198
"tpl-MNIPediatricAsym_cohort-1_T1w.nii.gz": "",
123199
"tpl-MNIPediatricAsym_cohort-1_T2w.nii.gz": "",
@@ -152,6 +228,7 @@ A guide for using macros can be found at
152228
-->
153229
{{ MACROS___make_filetree_example({
154230
"mni152nlin2009casym-pipeline": {
231+
"templates.tsv": "",
155232
"sub-001": {
156233
"anat": {
157234
"sub-001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5": "",

‎src/schema/objects/columns.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,22 @@ derived_from:
120120
for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`).
121121
type: string
122122
pattern: ^sample-[0-9a-zA-Z+]+$
123+
cohort_id:
124+
name: cohort_id
125+
display_name: Cohort ID
126+
description: |
127+
A cohort identifier of the form `cohort-<label>`,
128+
matching a cohort entity found in the dataset.
129+
130+
The `cohort_id` column contains the labels used with the
131+
[`cohort` entity](SPEC_ROOT/appendices/entities.md#cohort),
132+
within the particular nesting that the `cohorts.tsv` file is placed.
133+
134+
For example, if the `cohorts.tsv` file is placed within a `tpl-<label>/` directory,
135+
its `cohort_id` column SHOULD contain all labels of the `cohort` entity
136+
used within that template directory.
137+
type: string
138+
pattern: ^cohort-[0-9a-zA-Z+]+$
123139
desc_id:
124140
name: desc_id
125141
display_name: Description Label
@@ -913,6 +929,22 @@ template_y:
913929
description: |
914930
Assumed or ideal position along the y axis.
915931
type: number
932+
template_id:
933+
name: template_id
934+
display_name: Template ID
935+
description: |
936+
A template identifier of the form `tpl-<label>`,
937+
matching a template entity found in the dataset.
938+
939+
The `template_id` column contains the labels used with the
940+
[`tpl` entity](SPEC_ROOT/appendices/entities.md#tpl),
941+
within the particular nesting that the `templates.tsv` file is placed.
942+
943+
For example, if the `templates.tsv` file is placed at the root of the derivative dataset,
944+
its `template_id` column SHOULD contain all labels of the `tpl` entity
945+
used across the entire derivative dataset.
946+
type: string
947+
pattern: ^tpl-[0-9a-zA-Z+]+$
916948
template_z:
917949
name: template_z
918950
display_name: Z template position

‎src/schema/objects/suffixes.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -566,6 +566,15 @@ colFA:
566566
image color is determined by the principal eigenvector of the diffusion tensor,
567567
where red encodes the magnitude of the left-right component of that orientation,
568568
with green and blue similarly encoding the anterior-posterior and inferior-superior components respectively.
569+
cohorts:
570+
value: cohorts
571+
display_name: Cohort Entity Definitions
572+
description: |
573+
A TSV file describing labels found for the `cohort` entity within a template.
574+
575+
This file MUST be located within a `tpl-<label>/` directory.
576+
577+
The `cohorts.tsv` file provides metadata to identify and describe cohorts in the template.
569578
coordsystem:
570579
value: coordsystem
571580
display_name: Coordinate System File
@@ -870,6 +879,15 @@ stim:
870879
display_name: Continuous recording
871880
description: |
872881
Continuous measures, such as parameters of a film or audio stimulus.
882+
templates:
883+
value: templates
884+
display_name: Template Entity Definitions
885+
description: |
886+
A TSV file describing labels found for the `tpl` entity in a Derivatives dataset.
887+
888+
This file MAY be located at the root of the derivative dataset.
889+
890+
The `templates.tsv` file provides metadata to identify and describe templates in the dataset.
873891
svs:
874892
value: svs
875893
display_name: Single-voxel spectroscopy

‎src/schema/rules/files/deriv/tables.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,27 @@
11
---
2+
templates:
3+
selectors:
4+
- dataset.dataset_description.DatasetType == 'derivative'
5+
level: optional
6+
suffixes:
7+
- templates
8+
extensions:
9+
- .tsv
10+
- .json
11+
entities: {}
12+
13+
cohorts:
14+
selectors:
15+
- dataset.dataset_description.DatasetType == 'derivative'
16+
level: optional
17+
suffixes:
18+
- cohorts
19+
extensions:
20+
- .tsv
21+
- .json
22+
entities:
23+
template: required
24+
225
descriptions:
326
selectors:
427
- dataset.dataset_description.DatasetType == 'derivative'

‎src/schema/rules/tabular_data/derivatives/common_derivatives.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,38 @@ SegmentationLookup:
1212
index_columns: [index]
1313
additional_columns: allowed
1414

15+
Templates:
16+
selectors:
17+
- suffix == "templates"
18+
- extension == ".tsv"
19+
initial_columns:
20+
- template_id
21+
- description__entities
22+
columns:
23+
template_id: required
24+
description__entities:
25+
level: required
26+
description_addendum: |
27+
The corresponding label column is `template_id`.
28+
index_columns: [template_id]
29+
additional_columns: allowed
30+
31+
Cohorts:
32+
selectors:
33+
- suffix == "cohorts"
34+
- extension == ".tsv"
35+
initial_columns:
36+
- cohort_id
37+
- description__entities
38+
columns:
39+
cohort_id: required
40+
description__entities:
41+
level: required
42+
description_addendum: |
43+
The corresponding label column is `cohort_id`.
44+
index_columns: [cohort_id]
45+
additional_columns: allowed
46+
1547
Descriptions:
1648
selectors:
1749
- suffix == "descriptions"

0 commit comments

Comments
 (0)