Skip to content

Replace atlas-<label>_description.json with atlases.tsv pattern and also add templates.tsv and cohorts.tsv #2286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yarikoptic wants to merge 2 commits into
base: bep038
Choose a base branch
from
Open

Replace atlas-<label>_description.json with atlases.tsv pattern and also add templates.tsv and cohorts.tsv #2286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e1ac9b
ENH: Add templates.tsv and cohorts.tsv for template/cohort entity met…
yarikoptic Dec 18, 2025
688a0be
ENH: Refactor atlas metadata from JSON to atlases.tsv pattern
yarikoptic Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 180 additions & 70 deletions src/derivatives/atlas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +144 to +149
Copy link
Collaborator

@oesteban oesteban Dec 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Someone can remind me whether we have sub- in the participants.tsv file or it must be removed? If it is not allowed:

Suggested change
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
1 Ages 0-2 months
2 Ages 3-5 months
3 Ages 6-11 months
4 Ages 1-2 years
5 Ages 3-6 years
6 Ages 7-18 years

Copy link
Collaborator Author

@yarikoptic yarikoptic Dec 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see

for detailed response, but yes -- all our "{entity}_id", to become those "id" unique across entities, are including entity name in them, so we have sub-{label}, ses-{label} and so on.

```

### Example: Single-cohort template

For the pipeline that generated [`MNI152NLin2009cAsym`](../appendices/coordinate-systems.md#standard-template-identifiers),
Expand All @@ -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": "",
Expand Down Expand Up @@ -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": "",
Expand Down Expand Up @@ -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": "",
Expand Down Expand Up @@ -190,49 +267,106 @@ Template:

```Text
<pipeline_name>/
atlas-<label>_description.json
atlases.tsv
atlases.json
tpl-<label>/
[tpl-<label>_atlases.tsv]
[tpl-<label>_atlases.json]
[cohort-<label>/]
[<datatype>/]
tpl-<label>[_cohort-<label>][_<entities>]_<suffix>.<extension>
```

### Atlas identification and metadata
### Atlas identification and metadata (`atlases.tsv`)

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.
Atlases MUST include `atlas-<label>_description.json` files
corresponding to the atlas or atlases in the structure.
Template:

!!! tip "Recommendation"
```Text
<pipeline_name>/
atlases.tsv
atlases.json
```

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

Atlas metadata fields:
```Text
<pipeline_name>/
tpl-<label>/
tpl-<label>_atlases.tsv
tpl-<label>_atlases.json
```

<!-- This block generates a metadata table.
Optional: Yes

To keep a record of atlases in the dataset, an `atlases.tsv` file MAY be used.
The `atlases.tsv` file consists of one row for each unique `atlas-<label>`
entity used in the dataset and a set of REQUIRED, RECOMMENDED, and OPTIONAL columns:

<!-- This block generates a columns table.
The definitions of these fields can be found in
src/schema/objects/metadata.yaml
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_json_table('dataset_metadata.atlas_description') }}
{{ MACROS___make_columns_table("derivatives.common_derivatives.Atlases") }}

This file MAY be located at the root of the derivative dataset as `atlases.tsv`,
or within a `tpl-<label>/` directory as `tpl-<label>_atlases.tsv`
([Inheritance Principle](../common-principles.md#the-inheritance-principle)).

!!! note "Array fields"

Example `atlas-MyAtlas2025_description.json`:
For columns that represent arrays (such as `authors`, `curators`, `funding`,
and `references_and_links`), the value MUST be a JSON-encoded array of strings.
For example: `["Jane Doe", "John Doe"]`.

!!! tip "Recommendation"

The selected `<label>` in the `atlases.tsv` file is RECOMMENDED
for the [`atlas-<label>` entity](../appendices/entities.md#atlas)
in downstream derivatives from this particular atlas (see previous section
[Derivatives from atlases](imaging.md#derivatives-from-atlases)).

`atlases.tsv` example:

```tsv
atlas_id name license description authors species sample_size references_and_links
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"]
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"]
```

It is RECOMMENDED to accompany each `atlases.tsv` file with a sidecar
`atlases.json` file to describe the TSV column names and properties of their values
(see also the [section on tabular files](../common-principles.md#tabular-files)).

`atlases.json` example:

```JSON
{
"Name": "A new atlas of the human brain",
"Authors": [
"Jane Doe",
"John Doe"
],
"License": "CC0",
"RRID": "SCR_002823",
"Species": "Human"
"atlas_id": {
"Description": "Atlas identifier matching the atlas-<label> entity"
},
"name": {
"Description": "Name of the atlas"
},
"license": {
"Description": "License for the atlas"
},
"description": {
"Description": "Brief description of the atlas"
},
"authors": {
"Description": "JSON-encoded array of authors who created the atlas"
},
"species": {
"Description": "Species from which the atlas was derived"
},
"sample_size": {
"Description": "Number of participants used to create the atlas"
},
"references_and_links": {
"Description": "JSON-encoded array of references and links"
}
}
```

Expand Down Expand Up @@ -269,6 +403,7 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"suit-pipeline": {
"templates.tsv": "",
"tpl-SUIT": {
"anat": {
"tpl-SUIT_T1w.nii.gz": "",
Expand Down Expand Up @@ -296,7 +431,8 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"suit-pipeline": {
"atlas-Diedrichsen2009_description.json": "",
"atlases.tsv": "",
"templates.tsv": "",
"tpl-SUIT": {
"anat": {
"tpl-SUIT_T1w.nii.gz": "",
Expand All @@ -310,26 +446,11 @@ A guide for using macros can be found at
})
}}

where `atlas-Diedrichsen2009_description.json` could contain:
where `atlases.tsv` could contain:

```JSON
{
"Name": "A probabilistic MR atlas of the human cerebellum",
"Authors": [
"Jörn Diedrichsen",
"Joshua H Balsters",
"Jonathan Flavell",
"Emma Cussans",
"Narender Ramnani"
],
"SampleSize": 20,
"License": "LICENSE file",
"ReferencesAndLinks": [
"https://doi.org/10.1016/j.neuroimage.2009.01.045",
"https://github.com/jdiedrichsen/suit"
],
"Species": "Human"
}
```tsv
atlas_id name license description authors species sample_size references_and_links
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", "https://github.com/jdiedrichsen/suit"]
```

Later, in 2011 a second atlas was developed integrating new segmentations,
Expand All @@ -341,8 +462,8 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"suit-pipeline": {
"atlas-Buckner2011_description.json": "",
"atlas-Diedrichsen2009_description.json": "",
"atlases.tsv": "",
"templates.tsv": "",
"tpl-SUIT": {
"anat": {
"tpl-SUIT_T1w.nii.gz": "",
Expand All @@ -363,27 +484,12 @@ A guide for using macros can be found at
})
}}

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

```JSON
{
"Name": "Atlas of the human cerebellum estimated by intrinsic functional connectivity",
"Authors": [
"Randy L Buckner",
"Fenna M Krienen",
"Angela Castellanos",
"Julio C Diaz",
"B T Thomas Yeo"
],
"SampleSize": 1000,
"License": "LICENSE file",
"ReferencesAndLinks": [
"https://doi.org/10.1152/jn.00339.2011",
"https://github.com/jdiedrichsen/suit"
],
"Species": "Human"
}
```tsv
atlas_id name license description authors species sample_size references_and_links
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", "https://github.com/jdiedrichsen/suit"]
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", "https://github.com/jdiedrichsen/suit"]
```

### Example: Deriving a new atlas referenced in an existing template
Expand All @@ -398,7 +504,8 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"mial67thalamicnuclei-pipeline": {
"atlas-MIAL67ThalamicNuclei_description.json": "",
"atlases.tsv": "",
"templates.tsv": "",
"sub-01": {
"anat": {
"sub-01_seg-ThalamicNuclei_dseg.json": "",
Expand Down Expand Up @@ -443,9 +550,10 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"mial67thalamicnuclei-pipeline": {
"atlas-MIAL67ThalamicNuclei_description.json": "",
"atlases.tsv": "",
"seg-ThalamicNuclei_dseg.json": "",
"seg-ThalamicNuclei_dseg.tsv": "",
"templates.tsv": "",
"sub-01": {
"anat": {
"sub-01_seg-ThalamicNuclei_dseg.nii.gz": "",
Expand Down Expand Up @@ -483,11 +591,12 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"mial67thalamicnuclei-pipeline": {
"atlas-MIAL67ThalamicNuclei_description.json": "",
"atlas-MIAL67ThalamicNuclei_dseg.json": "",
"atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
"atlases.tsv": "",
"seg-ThalamicNuclei_dseg.json": "",
"seg-ThalamicNuclei_dseg.tsv": "",
"templates.tsv": "",
"sub-01": {
"anat": {
"sub-01_atlas-MIAL67ThalamicNuclei_dseg.nii.gz": "",
Expand Down Expand Up @@ -526,10 +635,11 @@ A guide for using macros can be found at
-->
{{ MACROS___make_filetree_example({
"mial67thalamicnuclei-pipeline": {
"atlas-MIAL67ThalamicNuclei_description.json": "",
"atlas-MIAL67ThalamicNuclei_dseg.json": "",
"atlas-MIAL67ThalamicNuclei_dseg.tsv": "",
"atlas-MIAL67ThalamicNuclei_probseg.json": "",
"atlases.tsv": "",
"templates.tsv": "",
"tpl-MNI152NLin2009cAsym": {
"anat": {
"tpl-MNI152NLin2009cAsym_atlas-MIAL67ThalamicNuclei_res-1_dseg.nii.gz": "",
Expand Down
9 changes: 2 additions & 7 deletions src/schema/meta/associations.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,10 +113,5 @@ coordsystems:
- space
inherit: true

atlas_description:
selectors:
- entities.atlas
- extension != '.json'
target:
suffix: description
extension: .json
# atlas_description association has been replaced by atlases.tsv pattern
# See src/derivatives/atlas.md for the specification.
Loading