[ENH] Allow Levels field of column descriptions to be objects with TermURLs for each level

[Remi-Gau]

• closes allow Levels values (in sidecar for TSV files) to be objects #1573

[Remi-Gau]

@surchs @ericearl @alyssadai

[Remi-Gau]

@effigies am I correct that this is one aspect of the spec that has not been schemaified yet?

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (fc98780) 87.83% compared to head (c1da9bb) 87.83%.
Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1603   +/-   ##
=======================================
  Coverage   87.83%   87.83%           
=======================================
  Files          16       16           
  Lines        1356     1356           
=======================================
  Hits         1191     1191           
  Misses        165      165           

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

[Remi-Gau]

Should the examples of the json sidecar for participants.tsv and for phenotypic assessments be updated to also include this way of describing levels?

[surchs]

Do we expect BIDS users to know what TermURL expects? How about:

Suggested change

	or with an object containing the fields `Description` and `TermURL`
	or with an object containing the fields `Description` and `TermURL`.
	If you use the object format, the value of the `TermURL` key should
	be a URL to a term from a controlled vocabulary that describes the
	level. For example: https://www.ncbi.nlm.nih.gov/mesh/68008297 for
	"male". The value of the `Description` key should then correspond
	to the human readable name of this term (or to the preferred name
	if several options exist in the controlled vocabulary). For example: "Male".

[effigies]

If we're going to improve the definition of TermURL, we should do it in https://bids-specification.readthedocs.io/en/stable/glossary.html#termurl-metadata so it appears in the glossary and any tables it's defined in.

https://bids-specification.readthedocs.io/en/stable/glossary.html#termurl-metadata

[Remi-Gau]

I could only transfer one sentence to the TermURL generic definition, the rest of @surchs suggestion feels too specific to this example I think.

[effigies]

@effigies am I correct that this is one aspect of the spec that has not been schemaified yet?

Correct. It's a weird state because what we really need to say is that, if the suffix is TSV, then additional properties of sidecars have the form of an object with certain allowed terms. It would have been much more convenient if we had made the column descriptions an object in a single field. (Further, there generally aren't rules against extra metadata, so it's actually that we need to create a typed metadata field dynamically based on the headers in the TSV.)

[surchs]

🎉 thanks a lot @Remi-Gau. One free bagel on us!

[sappelhoff]

LGTM! Thanks a lot @Remi-Gau

[Remi-Gau]

thanks @sappelhoff @surchs @effigies for the reviews