[ENH] Recommend controlled vocabulary for age Units, clarify that it can be overloaded

[yarikoptic]

Of high relevance to @bids-standard/bep032 effort, but also potentially to @bids-standard/bep036 and others.

• Most recent relevant discussion is in Formalize participants' age to actually allow for other than year units/durations  #1633 (comment)
• Ultimately closes Formalize participants' age to actually allow for other than year units/durations  #1633
• Reincarnated Clarify that age Units could be overriden + that type is number OR "89+" string #1791 which was partially addressed elsewhere
• and relates to freshly filed Does not validate the column value "Format" if "Description" is set bids-validator#386 as we might need to adjust this depending on the solution there.

TODOs/Notes

• it will make some bids-example datasets invalid since they use "years" for "Units" instead of "year", submitted 'Units' value must be singular, not plural (year not years) bids-examples#553
• Review/fix for that test fix. Unclear why NOW it became applicable/failing
  • we ran into this since this is presumably the first rule adding custom checks on the column definition (not sidecar) .json files? (according to claude). But reworked test selection seems became too cumbersome
  • no more changes to tests -- validating against .tsv
• For BIDS 2.0 make 'warning' into 'error' there Units not being from allowed values. Added to TODOs of BIDS-2.0 #1775

[effigies]

Some comments. Overall, I think this is a good push and will help clarity, but needs to be done in a backwards compatible way.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.07%. Comparing base (6764039) to head (5c6c320).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2400   +/-   ##
=======================================
  Coverage   83.07%   83.07%           
=======================================
  Files          22       22           
  Lines        1696     1696           
=======================================
  Hits         1409     1409           
  Misses        287      287           

☔ 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]

@effigies I forced pushed rebase on master with tune up the the testing... if you see how to improve it please share (even if an idea). according to claude this is "AgeUnits rule is the first to access json.age in participants.json" and thus we started to hit in this test for sidecar json files.

[yarikoptic]

done, rewritten, force pushed, I think we have converged!

[effigies]

Just for the sake of considering alternatives, the ISO 8601 standard for durations is P47Y1M8D and such-like. We could allow someone to use "Format": "ISO8601-Duration" and define the regex /P(\d+Y)?(\d+M)?.../ to validate those durations.

That would be using an existing standard instead of creating our own controlled vocabulary inspired by the standard, so I think it's worth considering, if only to record a reason for rejecting it.

My reasons would be:

1. Existing practice is to use decimal durations, and providing a common set of unit names is more practical than suggesting everybody learn to read and write ISO strings.
2. Including it as an optional unit (e.g., "Units": "ISO8601") would be a burden on dataset consumers.

[yarikoptic]

yeap, search reminded me mentioning it in original

• Formalize participants' age to actually allow for other than year units/durations  #1633

FWIW, I think adopting standard for durations makes sense. I will extract your comment into an issue

[yarikoptic]

@ericearl I would like to invite you to review this PR since somewhat relates to @bids-standard/bep036 and thus could be of interest for feedback or just approval ;) @julia-pfarr also might be of interest to you as a liaison to the world of all the participants.tsv annotations of neurobagels ;)

[ericearl]

Find a resolution to my one comment, and it looks good!

[effigies]

Two approvals. This can be merged on/after Thursday, April 23, to ensure there's enough time for people to review since the last significant edit.

[julia-pfarr]

Looks good! FYI: Neurobagel uses age in years with different formats (float (31.5), range (30-35), euro (31,5), bounded (30+), iso8601 (31Y6M))

[yarikoptic]

Two approvals. This can be merged on/after Thursday, April 23, to ensure there's enough time for people to review since the last significant edit.

coolio, today is May 07 so let's proceed!