Skip to content

Commit c1098d7

Browse files
yarikopticclaude
yarikoptic
and
claude
committed
Replace atlas-<label>_description.json with atlases.tsv pattern
This change makes BEP038's atlas metadata approach consistent with existing BIDS conventions for entity-specific TSV files (like participants.tsv, sessions.tsv, descriptions.tsv). Changes: - Replace atlas-<label>_description.json with atlases.tsv - Add templates.tsv for template metadata - Add tpl-<label>_cohorts.tsv for cohort metadata within templates - Support tpl-<label>_atlases.tsv for template-level atlas metadata The atlases.tsv includes columns derived from the original JSON fields: - atlas_id, name, license (REQUIRED) - description, authors (RECOMMENDED) - curators, funding, references_and_links, species, sample_size, derived_from, level_type, rrid (OPTIONAL) Array fields (authors, curators, funding, references_and_links) use JSON-encoded strings in TSV cells. Schema changes: - Added column definitions for all atlas/template/cohort TSV columns - Added suffix definitions for atlases, templates, cohorts - Added tabular_data rules for column validation - Added file rules supporting both root-level and template-level naming - Removed old atlas_description JSON-based rules and associations This addresses the inconsistency noted in: - Issue #2285: atlas-<label>_description.json pattern introduced by BEP038 - Issue #2283: Proposal to formalize {entities_plural}.tsv pattern This is a follow-up to PR #1714 (BEP038: Templates and atlases). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent 8f49cd2 commit c1098d7

File tree

10 files changed

+444
-140
lines changed

10 files changed

+444
-140
lines changed

‎src/derivatives/atlas.md‎

Lines changed: 180 additions & 70 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": "",
@@ -190,49 +267,106 @@ Template:
190267

191268
```Text
192269
<pipeline_name>/
193-
atlas-<label>_description.json
270+
atlases.tsv
271+
atlases.json
194272
tpl-<label>/
273+
[tpl-<label>_atlases.tsv]
274+
[tpl-<label>_atlases.json]
195275
[cohort-<label>/]
196276
[<datatype>/]
197277
tpl-<label>[_cohort-<label>][_<entities>]_<suffix>.<extension>
198278
```
199279

200-
### Atlas identification and metadata
280+
### atlases.tsv
201281

202-
The `atlas-<label>_description.json` file provides metadata to uniquely identify,
203-
describe and characterize the atlas, as well as give proper attribution to the creators.
204-
Atlases MUST include `atlas-<label>_description.json` files
205-
corresponding to the atlas or atlases in the structure.
282+
Template:
206283

207-
!!! tip "Recommendation"
284+
```Text
285+
<pipeline_name>/
286+
atlases.tsv
287+
atlases.json
288+
```
208289

209-
The selected `<label>` in the `atlas-<label>_description.json` file is RECOMMENDED
210-
for the [`atlas-<label>` entity](../appendices/entities.md#atlas)
211-
in downstream derivatives from this particular atlas (see previous section
212-
[Derivatives from atlases](imaging.md#derivatives-from-atlases)).
290+
or at the template level:
213291

214-
Atlas metadata fields:
292+
```Text
293+
<pipeline_name>/
294+
tpl-<label>/
295+
tpl-<label>_atlases.tsv
296+
tpl-<label>_atlases.json
297+
```
215298

216-
<!-- This block generates a metadata table.
299+
Optional: Yes
300+
301+
To keep a record of atlases in the dataset, an `atlases.tsv` file MAY be used.
302+
The `atlases.tsv` file consists of one row for each unique `atlas-<label>`
303+
entity used in the dataset and a set of REQUIRED, RECOMMENDED, and OPTIONAL columns:
304+
305+
<!-- This block generates a columns table.
217306
The definitions of these fields can be found in
218-
src/schema/objects/metadata.yaml
307+
src/schema/rules/tabular_data/*.yaml
219308
and a guide for using macros can be found at
220309
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
221310
-->
222-
{{ MACROS___make_json_table('dataset_metadata.atlas_description') }}
311+
{{ MACROS___make_columns_table("derivatives.common_derivatives.Atlases") }}
312+
313+
This file MAY be located at the root of the derivative dataset as `atlases.tsv`,
314+
or within a `tpl-<label>/` directory as `tpl-<label>_atlases.tsv`
315+
([Inheritance Principle](../common-principles.md#the-inheritance-principle)).
316+
317+
!!! note "Array fields"
223318

224-
Example `atlas-MyAtlas2025_description.json`:
319+
For columns that represent arrays (such as `authors`, `curators`, `funding`,
320+
and `references_and_links`), the value MUST be a JSON-encoded array of strings.
321+
For example: `["Jane Doe", "John Doe"]`.
322+
323+
!!! tip "Recommendation"
324+
325+
The selected `<label>` in the `atlases.tsv` file is RECOMMENDED
326+
for the [`atlas-<label>` entity](../appendices/entities.md#atlas)
327+
in downstream derivatives from this particular atlas (see previous section
328+
[Derivatives from atlases](imaging.md#derivatives-from-atlases)).
329+
330+
`atlases.tsv` example:
331+
332+
```tsv
333+
atlas_id name license description authors species sample_size references_and_links
334+
atlas-Diedrichsen2009 A probabilistic MR atlas of the human cerebellum LICENSE file Probabilistic atlas of the human cerebellum ["Jörn Diedrichsen", "Joshua H Balsters", "Jonathan Flavell", "Emma Cussans", "Narender Ramnani"] human 20 ["https://doi.org/10.1016/j.neuroimage.2009.01.045"]
335+
atlas-Buckner2011 Atlas of the human cerebellum estimated by intrinsic functional connectivity LICENSE file Cerebellar atlas estimated by intrinsic functional connectivity ["Randy L Buckner", "Fenna M Krienen", "Angela Castellanos", "Julio C Diaz", "B T Thomas Yeo"] human 1000 ["https://doi.org/10.1152/jn.00339.2011"]
336+
```
337+
338+
It is RECOMMENDED to accompany each `atlases.tsv` file with a sidecar
339+
`atlases.json` file to describe the TSV column names and properties of their values
340+
(see also the [section on tabular files](../common-principles.md#tabular-files)).
341+
342+
`atlases.json` example:
225343

226344
```JSON
227345
{
228-
"Name": "A new atlas of the human brain",
229-
"Authors": [
230-
"Jane Doe",
231-
"John Doe"
232-
],
233-
"License": "CC0",
234-
"RRID": "SCR_002823",
235-
"Species": "Human"
346+
"atlas_id": {
347+
"Description": "Atlas identifier matching the atlas-<label> entity"
348+
},
349+
"name": {
350+
"Description": "Name of the atlas"
351+
},
352+
"license": {
353+
"Description": "License for the atlas"
354+
},
355+
"description": {
356+
"Description": "Brief description of the atlas"
357+
},
358+
"authors": {
359+
"Description": "JSON-encoded array of authors who created the atlas"
360+
},
361+
"species": {
362+
"Description": "Species from which the atlas was derived"
363+
},
364+
"sample_size": {
365+
"Description": "Number of participants used to create the atlas"
366+
},
367+
"references_and_links": {
368+
"Description": "JSON-encoded array of references and links"
369+
}
236370
}
237371
```
238372

@@ -269,6 +403,7 @@ A guide for using macros can be found at
269403
-->
270404
{{ MACROS___make_filetree_example({
271405
"suit-pipeline": {
406+
"templates.tsv": "",
272407
"tpl-SUIT": {
273408
"anat": {
274409
"tpl-SUIT_T1w.nii.gz": "",
@@ -296,7 +431,8 @@ A guide for using macros can be found at
296431
-->
297432
{{ MACROS___make_filetree_example({
298433
"suit-pipeline": {
299-
"atlas-Diedrichsen2009_description.json": "",
434+
"atlases.tsv": "",
435+
"templates.tsv": "",
300436
"tpl-SUIT": {
301437
"anat": {
302438
"tpl-SUIT_T1w.nii.gz": "",
@@ -310,26 +446,11 @@ A guide for using macros can be found at
310446
})
311447
}}
312448

313-
where `atlas-Diedrichsen2009_description.json` could contain:
449+
where `atlases.tsv` could contain:
314450

315-
```JSON
316-
{
317-
"Name": "A probabilistic MR atlas of the human cerebellum",
318-
"Authors": [
319-
"Jörn Diedrichsen",
320-
"Joshua H Balsters",
321-
"Jonathan Flavell",
322-
"Emma Cussans",
323-
"Narender Ramnani"
324-
],
325-
"SampleSize": 20,
326-
"License": "LICENSE file",
327-
"ReferencesAndLinks": [
328-
"https://doi.org/10.1016/j.neuroimage.2009.01.045",
329-
"https://github.com/jdiedrichsen/suit"
330-
],
331-
"Species": "Human"
332-
}
451+
```tsv
452+
atlas_id name license description authors species sample_size references_and_links
453+
atlas-Diedrichsen2009 A probabilistic MR atlas of the human cerebellum LICENSE file Probabilistic atlas of the human cerebellum ["Jörn Diedrichsen", "Joshua H Balsters", "Jonathan Flavell", "Emma Cussans", "Narender Ramnani"] human 20 ["https://doi.org/10.1016/j.neuroimage.2009.01.045"]
333454
```
334455

335456
Later, in 2011 a second atlas was developed integrating new segmentations,
@@ -341,8 +462,8 @@ A guide for using macros can be found at
341462
-->
342463
{{ MACROS___make_filetree_example({
343464
"suit-pipeline": {
344-
"atlas-Buckner2011_description.json": "",
345-
"atlas-Diedrichsen2009_description.json": "",
465+
"atlases.tsv": "",
466+
"templates.tsv": "",
346467
"tpl-SUIT": {
347468
"anat": {
348469
"tpl-SUIT_T1w.nii.gz": "",
@@ -363,27 +484,12 @@ A guide for using macros can be found at
363484
})
364485
}}
365486

366-
where `atlas-Diedrichsen2009_description.json` remains as above,
367-
and `atlas-Buckner2011_description.json` could contain:
487+
where `atlases.tsv` now contains both atlases:
368488

369-
```JSON
370-
{
371-
"Name": "Atlas of the human cerebellum estimated by intrinsic functional connectivity",
372-
"Authors": [
373-
"Randy L Buckner",
374-
"Fenna M Krienen",
375-
"Angela Castellanos",
376-
"Julio C Diaz",
377-
"B T Thomas Yeo"
378-
],
379-
"SampleSize": 1000,
380-
"License": "LICENSE file",
381-
"ReferencesAndLinks": [
382-
"https://doi.org/10.1152/jn.00339.2011",
383-
"https://github.com/jdiedrichsen/suit"
384-
],
385-
"Species": "Human"
386-
}
489+
```tsv
490+
atlas_id name license description authors species sample_size references_and_links
491+
atlas-Buckner2011 Atlas of the human cerebellum estimated by intrinsic functional connectivity LICENSE file Cerebellar atlas estimated by intrinsic functional connectivity ["Randy L Buckner", "Fenna M Krienen", "Angela Castellanos", "Julio C Diaz", "B T Thomas Yeo"] human 1000 ["https://doi.org/10.1152/jn.00339.2011"]
492+
atlas-Diedrichsen2009 A probabilistic MR atlas of the human cerebellum LICENSE file Probabilistic atlas of the human cerebellum ["Jörn Diedrichsen", "Joshua H Balsters", "Jonathan Flavell", "Emma Cussans", "Narender Ramnani"] human 20 ["https://doi.org/10.1016/j.neuroimage.2009.01.045"]
387493
```
388494

389495
### Example: Deriving a new atlas referenced in an existing template
@@ -398,7 +504,8 @@ A guide for using macros can be found at
398504
-->
399505
{{ MACROS___make_filetree_example({
400506
"mial67thalamicnuclei-pipeline": {
401-
"atlas-MIAL67ThalamicNuclei_description.json": "",
507+
"atlases.tsv": "",
508+
"templates.tsv": "",
402509
"sub-01": {
403510
"anat": {
404511
"sub-01_seg-ThalamicNuclei_dseg.json": "",
@@ -443,9 +550,10 @@ A guide for using macros can be found at
443550
-->
444551
{{ MACROS___make_filetree_example({
445552
"mial67thalamicnuclei-pipeline": {
446-
"atlas-MIAL67ThalamicNuclei_description.json": "",
553+
"atlases.tsv": "",
447554
"seg-ThalamicNuclei_dseg.json": "",
448555
"seg-ThalamicNuclei_dseg.tsv": "",
556+
"templates.tsv": "",
449557
"sub-01": {
450558
"anat": {
451559
"sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
@@ -483,11 +591,12 @@ A guide for using macros can be found at
483591
-->
484592
{{ MACROS___make_filetree_example({
485593
"mial67thalamicnuclei-pipeline": {
486-
"atlas-MIAL67ThalamicNuclei_description.json": "",
487594
"atlas-MIAL67ThalamicNuclei_dseg.json": "",
488595
"atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
596+
"atlases.tsv": "",
489597
"seg-ThalamicNuclei_dseg.json": "",
490598
"seg-ThalamicNuclei_dseg.tsv": "",
599+
"templates.tsv": "",
491600
"sub-01": {
492601
"anat": {
493602
"sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
@@ -526,10 +635,11 @@ A guide for using macros can be found at
526635
-->
527636
{{ MACROS___make_filetree_example({
528637
"mial67thalamicnuclei-pipeline": {
529-
"atlas-MIAL67ThalamicNuclei_description.json": "",
530638
"atlas-MIAL67ThalamicNuclei_dseg.json": "",
531639
"atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
532640
"atlas-MIAL67ThalamicNuclei_probseg.json": "",
641+
"atlases.tsv": "",
642+
"templates.tsv": "",
533643
"tpl-MNI152NLin2009cAsym": {
534644
"anat": {
535645
"tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz": "",

‎src/schema/meta/associations.yaml‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -113,10 +113,5 @@ coordsystems:
113113
- space
114114
inherit: true
115115

116-
atlas_description:
117-
selectors:
118-
- entities.atlas
119-
- extension != '.json'
120-
target:
121-
suffix: description
122-
extension: .json
116+
# atlas_description association has been replaced by atlases.tsv pattern
117+
# See src/derivatives/atlas.md for the specification.

0 commit comments

Comments
 (0)