[SCHEMA] Add full object definitions for valid values in schema

[tsalo]

• Closes Support full object definitions for valid values in schema #904

This PR adds new information to the schema, but should not affect how it is rendered in the specification.

will simplify finding a solution for:

• Formalize how channel types are shared between modalities that use channels.tsv files. #1436
• [SCHEMA] Refactor channel types #1126

I'm not going to write a rendering function based on tags in this PR. I think it can go in a future one.

Changes proposed:

• Convert certain valid values (enums) in the schema to full objects. Specifically, these object definitions contain "name" and "description" fields. In most cases, they're still nested within the parent object definitions, rather than stored as distinct objects and referenced in the objects that use them.

To do:

• Ensure that the schema rendering and searching functions can handle the fact that many lists of strings are now lists of objects.
• Fill in the TODOs. I may need to ask for help in describing some (many?) of the values.
• Think about tackling Render valid value restrictions in tables based on object definitions in schema #912 in this PR as well. Dropped in favor of [ENH] Render valid value restrictions in tables based on object definitions in schema #921.

[tsalo]

What do the different PCASLType values mean?

[tsalo]

Should we describe the different SampleOrigin values?

[tsalo]

What do the different SpoilingType values mean?

[tsalo]

Should we describe the different TissueOrigin values?

[codecov]

Codecov Report

Patch coverage: 79.54% and project coverage change: -0.18 ⚠️

Comparison is base (f2cea0f) 88.00% compared to head (41189dc) 87.83%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #919      +/-   ##
==========================================
- Coverage   88.00%   87.83%   -0.18%     
==========================================
  Files          16       16              
  Lines        1326     1356      +30     
==========================================
+ Hits         1167     1191      +24     
- Misses        159      165       +6     

Impacted Files	Coverage Δ
tools/schemacode/bidsschematools/render/utils.py	85.18% <0.00%> (ø)
tools/schemacode/bidsschematools/schema.py	79.61% <81.81%> (-0.18%)	⬇️
tools/schemacode/bidsschematools/rules.py	98.96% <83.33%> (-1.04%)	⬇️
tools/schemacode/bidsschematools/render/text.py	95.53% <87.50%> (-1.10%)	⬇️

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[tsalo]

I'm not sure if these values should be enumerated here. I took them from https://bids-specification.readthedocs.io/en/stable/99-appendices/08-coordinate-systems.html#nonstandard-coordinate-system-identifiers and https://bids-specification.readthedocs.io/en/stable/99-appendices/08-coordinate-systems.html#non-template-coordinate-system-identifiers.

[effigies]

Noting that this would be a backwards incompatible change (cf #1013), but easily handled by detecting a list of single-keyed objects to a list of keys.

[effigies]

The Phase/SliceEncodingDirection values are slightly weirdly worded. Would something like this work?

Alternately, we at least should use phase/slice in both lines.

[sappelhoff]

I have reviewed this PR and I approve of it, thanks a lot for this work.

Just one question:

For some items you have added the comment

# TODO: Add definitions for these values.

While other items don't have such a comment, yet they are not converted to the "new form" either, e.g.:

  enum:
    - IODINE
    - GADOLINIUM
    - CARBON DIOXIDE
    - BARIUM
    - XENON

Shouldn't we just add information for all enums (except those that only have "n/a")?

Or is that kind of superfluous? (e.g., for m, cm, mm enums ... meter, centimeter ...)

[tsalo]

Thanks for reviewing @sappelhoff!

While other items don't have such a comment, yet they are not converted to the "new form" either

Those could be enums that were added after I started this PR, or they might even be ones I just missed in my original pass-through.

Shouldn't we just add information for all enums (except those that only have "n/a")?

I think some are self-explanatory (e.g., I don't know if I want to write descriptions for all of the allowed values for the handedness column, since they include l, L, left, Left, LEFT, etc.), but I do think most valid values could use a description. I think we can tackle that in future PRs though, since this one adds in the infrastructure we need to make that work.

[sappelhoff]

ok, great. I am going to merge this today and then do follow up PRs:

1. rendering the channel type tables in the modality sections from the schema
2. creating a new appendix page rendering ALL channel types (and putting links to this appendix below the modality ch type tables)
3. adding remaining enums (or adding comments saying that we won't add them as of now ... for cases where such comments are not currently there already)

[tsalo]

Thanks!

[sappelhoff]

thanks a lot again @tsalo!