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

yarikoptic · 2025-12-18T23:11:16Z

This is a follow-up to PR #1714 (BEP038: Templates and atlases) to make atlas metadata approach consistent with existing BIDS conventions for entity-specific TSV files (like participants.tsv, sessions.tsv, descriptions.tsv, etc).

It was edited to be split into 2 commits, first one is submitted independently for a dedicated, and less radical discussion:

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

Changes of the 2nd commit here:

Replace atlas-_description.json with atlases.tsv

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 Formalize concept of '{entity}-<label>_description.json' #2285: atlas-_description.json pattern introduced by BEP038

via already prevalent in BIDS

Issue Formalize the concept of [{leading entities}_]{entity_plural}.{tsv,json} file(s) #2283: Proposal to formalize {entities_plural}.tsv pattern

src/schema/objects/columns.yaml

oesteban

The only caveat is now updating the examples accordingly, but overall, I can't see any issues. If TSVs for the atlas metadata are annoying or insufficiently readable, it can be addressed later, as opposed to adding the _description.json file, which is not idempotent.

One thing we did not address in this BEP038 (nor any other BEP) is to allow multiline strings in metadata. Templates and atlases really would need that (at minimum, a way of having their own README and LICENSE files). I'm curious about that in general.

oesteban · 2025-12-19T07:33:27Z

src/derivatives/atlas.md

+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


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

see

Formalize the concept of [{leading entities}_]{entity_plural}.{tsv,json} file(s) #2283

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.

src/derivatives/atlas.md

oesteban · 2025-12-19T07:36:10Z

src/derivatives/atlas.md

-}
+```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"]


why the github repo is dropped (out of curiosity, doesn't bother me)

damn AI, thank you the sharp human eye! will fix now.

I missed that both records point to github suit... will make sure having it all over

yarikoptic · 2025-12-20T02:16:53Z

One thing we did not address in this BEP038 (nor any other BEP) is to allow multiline strings in metadata. Templates and atlases really would need that (at minimum, a way of having their own README and LICENSE files). I'm curious about that in general.

good points, in particular for READMEs. If anything, I would have said to create atlas-<label>_README.md but
may be even under atlases/ folder (similar to stimuli/ etc) or under docs/ which we allow ATM but will not validate anything under.

yarikoptic · 2025-12-20T02:26:32Z

good points, in particular for READMEs. If anything, I would have said to create atlas-<label>_README.md but
may be even under atlases/ folder (similar to stimuli/ etc) or under docs/ which we allow ATM but will not validate anything under.

side topic -- I tend to use https://www.visidata.org/ @TheChymera once introduced me to **a lot ** and I love it. For that end, it is nice to include a column with paths, since then you could either open directory viewer if points to a folder or just open that text file (with zo IIRC). So we could have "extra_docs" or "README" column there pointing to wherever we like. I would be cautious of dumping all those in the root folder though.

That visidata tool is a godsend for BIDS users in console -- we should really promote it more! ;)

…adata 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 <[email protected]>

Replace atlas-<label>_description.json with atlases.tsv for atlas metadata, consistent with existing entity-specific TSV files (participants.tsv, sessions.tsv). Key changes: - atlases.tsv: placed at derivative dataset root or tpl-<label>/ directory - Metadata fields converted to snake_case column names - Array fields (authors, curators, funding, references_and_links) use JSON encoding Schema changes: - Add atlas_id and all atlas-specific columns to columns.yaml - Add atlases suffix to suffixes.yaml - Add Atlases rule to common_derivatives.yaml - Add atlases file rule to tables.yaml - Remove old atlas_description association, context, and metadata rules - Delete atlas.yaml check and file rules Documentation: - Update atlas.md with atlases.tsv section and updated examples - Add JSON-encoded array note - Replace all atlas-<label>_description.json references with atlases.tsv Closes: #2285 Related to: #2283 Related to: #1714 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

codecov · 2025-12-20T02:37:47Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.81%. Comparing base (e7ab432) to head (688a0be).

Additional details and impacted files

@@           Coverage Diff           @@
##           bep038    #2286   +/-   ##
=======================================
  Coverage   82.81%   82.81%           
=======================================
  Files          22       22           
  Lines        1693     1693           
=======================================
  Hits         1402     1402           
  Misses        291      291

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

yarikoptic requested a review from erdalkaraca as a code owner December 18, 2025 23:11

yarikoptic commented Dec 18, 2025

View reviewed changes

src/schema/objects/columns.yaml Outdated Show resolved Hide resolved

yarikoptic force-pushed the bep038-atlases_tsv branch from c1098d7 to bf7ece5 Compare December 18, 2025 23:46

yarikoptic mentioned this pull request Dec 18, 2025

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

Open

yarikoptic requested a review from effigies December 18, 2025 23:50

yarikoptic added the BEP label Dec 18, 2025

oesteban reviewed Dec 19, 2025

View reviewed changes

yarikoptic force-pushed the bep038-atlases_tsv branch from bf7ece5 to 058de33 Compare December 20, 2025 02:22

yarikoptic force-pushed the bep038-atlases_tsv branch from 058de33 to 58db0c6 Compare December 20, 2025 02:28

yarikoptic force-pushed the bep038-atlases_tsv branch from 58db0c6 to 688a0be Compare December 20, 2025 02:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

yarikoptic commented Dec 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

oesteban left a comment

Uh oh!

oesteban Dec 19, 2025

Uh oh!

yarikoptic Dec 20, 2025

Uh oh!

Uh oh!

oesteban Dec 19, 2025

Uh oh!

yarikoptic Dec 20, 2025

Uh oh!

yarikoptic Dec 20, 2025

Uh oh!

yarikoptic commented Dec 20, 2025

Uh oh!

yarikoptic commented Dec 20, 2025

Uh oh!

codecov bot commented Dec 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

yarikoptic commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

oesteban left a comment

Choose a reason for hiding this comment

Uh oh!

oesteban Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Dec 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

oesteban Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Dec 20, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Dec 20, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic commented Dec 20, 2025

Uh oh!

yarikoptic commented Dec 20, 2025

Uh oh!

codecov bot commented Dec 20, 2025

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

yarikoptic commented Dec 18, 2025 •

edited

Loading