[ENH] Add explicit wording on DICOM terms correspondence

[yarikoptic]

I was under impression that we had such wording somewhere but I failed to find. Such aspect came up during recent presentation by @rordenlab to SC,

and we already have lots of metadata fields formalized that way

❯ git grep DICOM | grep -i -e based -e correspond
src/modality-specific-files/magnetic-resonance-imaging-data.md:Volume types are defined in the following table, based on DICOM Tag 0018, 9257 `ASL Context`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9073 `Acquisition Duration`.
src/schema/objects/metadata.yaml:    Based on DICOM Tag 0018, 925F `ASL Bolus Cut-off Delay Time`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 925C `ASL Bolus Cut-off Flag`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 925E `ASL Bolus Cut-off Technique`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 1048 `Contrast/Bolus Ingredient`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0054, 1322 `Dose Calibration Factor`.
src/schema/objects/metadata.yaml:    For Siemens, this corresponds to DICOM field 0019, 1018 (in ns).
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0081 `Echo Time`
src/schema/objects/metadata.yaml:    Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`.
src/schema/objects/metadata.yaml:    This corresponds to DICOM Tag 0018, 1242 `Actual Frame Duration` converted
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 101A `Hardcopy Device Software Version`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 1074 `Radionuclide Total Dose`.
src/schema/objects/metadata.yaml:    This corresponds to DICOM Tag 0018, 1072 `Contrast/Bolus Start Time`
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0082 `Inversion Time`
src/schema/objects/metadata.yaml:    Based on DICOM macro C.8.13.5.14.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9258 `ASL Pulse Train Duration`.
src/schema/objects/metadata.yaml:    Based on DICOM macro C.8.13.5.14.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9255 `ASL Slab Orientation`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9254 `ASL Slab Thickness`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0023 `MR Acquisition Type`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9020 `Magnetization Transfer`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0087 `Magnetic Field Strength`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 1077 `Radiopharmaceutical Specific Activity`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9078 `Parallel Acquisition Technique`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9069 `Parallel Reduction Factor In-plane`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9155 `Parallel Reduction Factor out-of-plane`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9081 `Partial Fourier`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9036 `Partial Fourier Direction`.
src/schema/objects/metadata.yaml:    Based on DICOM Tags 0018, 9079 `Inversion Times` and 0018, 0082
src/schema/objects/metadata.yaml:    This does not correspond to a tag in the DICOM ontology.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`,
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0022 `Scan Options`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0024 `Sequence Name`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 9259 `ASL Crusher Flag`.
src/schema/objects/metadata.yaml:    Corresponds to DICOM Tag 0018, 925A `ASL Crusher Flow Limit`.
src/schema/objects/suffixes.yaml:    Based on DICOM macro C.8.13.5.14.
src/schema/rules/checks/asl.yaml:      `*_aslcontext.tsv`. Corresponds to DICOM Tag 0018,9258 `ASL Pulse Train Duration`.
src/schema/rules/checks/asl.yaml:      Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`.
src/schema/rules/checks/asl.yaml:      Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`.
src/schema/rules/checks/asl.yaml:      Based on DICOM Tags 0018,9079 Inversion Times and 0018,0082 InversionTime.
src/schema/rules/checks/asl.yaml:      Based on DICOM Tags 0018,9079 Inversion Times and 0018,0082 InversionTime.
src/schema/rules/checks/asl.yaml:      Corresponds to DICOM Tag 0018,9258 `ASL Pulse Train Duration`.
src/schema/rules/sidecars/asl.yaml:          bolus cut-off saturation pulses are provided. Based on DICOM Tag
src/schema/rules/sidecars/asl.yaml:          Corresponds to DICOM Tag 0018,925E `ASL Bolus Cut-off Technique`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0070 `Manufacturer`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 1010 `Station Name`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0018, 1020 `Software Versions`.
src/schema/rules/sidecars/mri.yaml:          for the acquisition, specified in seconds. Corresponds to DICOM Tag
src/schema/rules/sidecars/mri.yaml:          Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. The data
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0080 `InstitutionName`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0081 `InstitutionAddress`.
src/schema/rules/sidecars/mri.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 1040 `Institutional Department Name`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0070 `Manufacturer`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name`.
src/schema/rules/sidecars/pet.yaml:        Corresponds to DICOM Tag 0054, 1001 `Units`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0080 `InstitutionName`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 0081 `InstitutionAddress`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0008, 1040 `Institutional Department Name`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
src/schema/rules/sidecars/pet.yaml:        Corresponds to DICOM Tags (0008,0105) `Mapping Resource` and
src/schema/rules/sidecars/pet.yaml:        Corresponds to DICOM Tags (0008,0104) `CodeValue` and (0008,0104) `CodeMeaning`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0008,0034) `Intervention Drug Name`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0008,0028) `Intervention Drug Dose`.
src/schema/rules/sidecars/pet.yaml:        Corresponds to a combination of DICOM Tags (0008,0027) `Intervention Drug Stop Time`
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0018,1072) `Radiopharmaceutical Start Time`.
src/schema/rules/sidecars/pet.yaml:        Corresponds to DICOM Tag (0018,1073) `Radiopharmaceutical Stop Time`
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0008,0022) `Acquisition Date`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: This corresponds to DICOM Tag (0054,1101) `Attenuation Correction Method`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0054,1323) `Scatter Fraction Factor`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0054,1321) `Decay Factor`.
src/schema/rules/sidecars/pet.yaml:      description_addendum: Corresponds to DICOM Tag (0054,1322) `Dose Calibration Factor`.

but it seems lacking formalization of that.

Possible TODOs

• [x] extend for "Based on"
• find some other location than Imaging files since DICOMs could be the source of other data types (e.g., physio). What about RFing into a dedicated section Data converted from DICOM files or alike preceding specific Imaging files?
  • no feedback was received -- decided to not bother on this for now
• [x] ~~might be worth establishing correspondence at the level of the schema.~~ DONE File a dedicated issue for this. https://github.com/bids-standard/bids-specification/issues/1759
• Per @robertoostenveld correct note: later we might find similar correspondences to other formats/standards (e.g. NWB/Zarr) so wording might need to be adjusted later on, and aforementioned issue might want to mention that so relationship specification is not "assuming" DICOM only.
  • correct, that is why in #1759 suggested schema can allow for easy extension to other relation targets. Not a concern for this PR IMHO

[yarikoptic]

Dear ~~@bids-maintenance~~ @bids-standard/maintainers ppl, what do you think about proposed change in general?

[tsalo]

I like the proposal, although it almost seems like it should go in contributing docs?

[CPernet]

here is our mapping for PET https://github.com/openneuropet/PET2BIDS/blob/main/metadata/dicom2bids.json

[yarikoptic]

I like the proposal, although it almost seems like it should go in contributing docs?

I think pretty much all of the common principles are pertinent to contributing. I have added an item to TODOs from @effigies that we might want even to list/enforce them at the level of schema.

[yarikoptic]

I like the proposal, although it almost seems like it should go in contributing docs?

Thank you @tsalo for having a look. Looking at https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md -- they are really oriented toward our setup/technologies and formats used for development of BIDS specification. Common principles on the other hand formulate base principles of BIDS as a standard and composition of its elements. After re-reviewing CONTRIBUTING and common principles -- I think it is a good location ATM.

ATM because it relates to the idea/effort of reducing domain specificity in common principles for BIDS 2.0

• https://github.com/bids-standard/bids-2-devel/issues/66 so eventually there might be a "Neuroimaging specific" section of common principles.

It somewhat also similar/relating to

• https://github.com/bids-standard/bids-extensions/pull/26

some of which IMHO should actually be described in bids-specification itself since they are "common principles" behind some choices made within context of BIDS itself after such BEPs are merged. But "bids-extensions" document is not a good place for this PR since, echoing above said, more about "common principles" for what is already in BIDS, or what could be added outside of full fledged BEP mechanism.

[CPernet]

we do use 'Corresponds to DICOM Tags' in the spec so to me it makes sense to have it in common principles as you did -- see for instance https://bids-specification.readthedocs.io/en/stable/modality-specific-files/positron-emission-tomography.html#radiochemistry

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 87.93%. Comparing base (bd08602) to head (db08106). Report is 56 commits behind head on master.

:exclamation: Current head db08106 differs from pull request most recent head 49f686a. Consider uploading reports for the commit 49f686a to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1450   +/-   ##
=======================================
  Coverage   87.93%   87.93%           
=======================================
  Files          16       16           
  Lines        1351     1351           
=======================================
  Hits         1188     1188           
  Misses        163      163           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[yarikoptic]

I don't get how these changes could trigger CI fails which didn't happen within e.g. recent #1758 ... may be I will rebase for a good measure.

[yarikoptic]

Thank you @CPernet for the feedback. I have pushed another change for "Based on" and consider this PR "ready for review and potentially merge". If agree with it -- give a blessing please ;) I also filed a number of related issues/PRs which reference this one.

[yarikoptic]

Got 2 approvals, was out here for almost a year... any @bids-standard/maintainers who could do the final look and do the honors of clicking "Merge"?

[effigies]

I was pinged a long time ago, and I suppose I should comment. I don't really like instructions to spec writers in the spec. This seems to fit better in a contribution guide. Perhaps a way to rewrite this that would feel more spec-like would be:

Currently defined metadata fields are listed in the Glossary. Where possible, DICOM Tags are adopted directly as BIDS metadata terms, indicated with "Corresponds to DICOM Tag ID1, ID2 DICOM Tag Name.". When harmonization has been deemed necessary, this is indicated in the BIDS term description with "Based on DICOM Tag ID1, ID2 DICOM Tag Name.".

This way it indicates to readers what to expect, and indirectly instructs writers how to write these two cases.