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

[yarikoptic]

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- entities
• cohorts.tsv: placed within tpl-/ directory, describes cohort- 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:

• Formalize concept of '{entity}-<label>_description.json' #2285
• Formalize the concept of [{leading entities}_]{entity_plural}.{tsv,json} file(s) #2283

Part of the larger

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

for independent consideration. Attn @bids-standard/bep038

[CPernet]

I have to say it annoys me to see this after a lot of work to get there .. but damn it works, and it is consistent with other parts of BIDS .. nice +1 👍 I cannot see any reason not to adopt that change @oesteban what do you think?

[oesteban]

I have to say it annoys me to see this after a lot of work to get there .. but damn it works, and it is consistent with other parts of BIDS .. nice +1 👍 I cannot see any reason not to adopt that change @oesteban what do you think?

I understand Yarik's points. Also, his proposal is "idempotent" (in the sense that it doesn't create anything that cannot be completed/modified later down the line, as opposed to our _description.json file that once introduced is hard to get rid of).

That said, Yarik's proposal opens a small hole for fields that require long descriptions, such as a custom license (that cannot be expressed with an identifier). Current BEP038 doesn't solve that problem (which is above its scope btw), but having JSON fields to stick that metadata is more reasonable than having them stuffed into the TSV column.

[yarikoptic]

such as a custom license (that cannot be expressed with an identifier). Current BEP038 doesn't solve that problem (which is above its scope btw), but having JSON fields to stick that metadata is more reasonable than having them stuffed into the TSV column.

isn't it a 80/20 rule concern? could likely be "custom: see LICENSE file" for those likely <20% cases?

[yarikoptic]

note that this one alone doesn't solve _descriptions.json for which there is a follow up

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

[codecov]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##           bep038    #2287   +/-   ##
=======================================
  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.

[oesteban]

such as a custom license (that cannot be expressed with an identifier). Current BEP038 doesn't solve that problem (which is above its scope btw), but having JSON fields to stick that metadata is more reasonable than having them stuffed into the TSV column.

isn't it a 80/20 rule concern? could likely be "custom: see LICENSE file" for those likely <20% cases?

It does apply, 80% of the licenses are custom. Universities used to weigh in and request nonstandard licenses be set.