[ENH] Add explicit wording on DICOM terms correspondence #1450

yarikoptic · 2023-03-17T14:54:30Z

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

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
~~might be worth establishing correspondence at the level of the schema.~~ DONE File a dedicated issue for this. Add support for relating to DICOM fields directly in the schema #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 Add support for relating to DICOM fields directly in the schema #1759 suggested schema can allow for easy extension to other relation targets. Not a concern for this PR IMHO

yarikoptic · 2023-04-27T17:17:58Z

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

tsalo · 2023-04-27T19:11:27Z

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

CPernet · 2023-05-04T18:08:55Z

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

yarikoptic · 2023-05-04T18:10:59Z

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 · 2024-03-30T20:05:01Z

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

Generalize BIDS common principles as a "data structure standard (DSS)" bids-2-devel#66
so eventually there might be a "Neuroimaging specific" section of common principles.

It somewhat also similar/relating to

first draft of general conventions page bids-extensions#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 · 2024-03-31T06:43:19Z

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 · 2024-03-31T12:15:08Z

Codecov Report

All modified and coverable lines are covered by tests ✅

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

❗ 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

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

yarikoptic · 2024-03-31T12:21:50Z

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 · 2024-03-31T12:23:25Z

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.

bendhouseart

lgtm 👍

yarikoptic · 2024-04-13T15:23:05Z

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"?

sappelhoff

Just a tiny wording tuning suggestion. And a general statement that this looks fine to me.

I am not deep enough into the MRI spec to do the final merge, however.

src/common-principles.md

sappelhoff · 2024-04-15T08:16:07Z

src/common-principles.md

+Many of such metadata entries are explicitly formalized in BIDS and could be found listed in the [Glossary](./glossary.md).
+Whenever formalizing a new metadata entry within BIDS, the name SHOULD correspond to the original DICOM Tag whenever the value is taken *as is* without any further harmonization.
+The description of the term in the schema then SHOULD describe such correspondence as "Corresponds to DICOM Tag ID1, ID2 `DICOM Tag Name`.".
+If value is harmonized, the description SHOULD describe such correspondence as "Based on DICOM Tag ID1, ID2 `DICOM Tag Name`.".


Suggested change

If value is harmonized, the description SHOULD describe such correspondence as "Based on DICOM Tag ID1, ID2 `DICOM Tag Name`.".

If the name is harmonized (against the previous recommendation), then the description SHOULD describe such correspondence as "Based on DICOM Tag ID1, ID2 `DICOM Tag Name`.".

it feels that it is two points here:

It might indeed be the name and/or the value which is "harmonized". Previous wording was aiming only for value harmonization, @sappelhoff , you propose to flip it to name here?

name harmonization: For the name-only (value stays the same) I do not immediately can come up with an example but potentially it could happen.

overall, good point, will think about it a little more.

Overall wording could be improved to make two cases more obvious (need to think more too, I have some dislike to suggested "against ..." formulation)

but potentially it could happen

then let's try to cover both 👍

I was mostly trying to streamline the language, please feel free to iterate!

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

effigies · 2024-04-25T02:47:55Z

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.

src/common-principles.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

effigies

Rendered:

CPernet approved these changes May 4, 2023

View reviewed changes

This was referenced Mar 31, 2024

[ENH] Use "Tag XXXX, YYYY" not "Tag (XXXX,YYYY)" for DICOM Tags #1758

Merged

DICOM tags yaml vs md #1028

Open

Add support for relating to DICOM fields directly in the schema #1759

Open

yarikoptic marked this pull request as ready for review March 31, 2024 12:16

yarikoptic requested a review from DimitriPapadopoulos as a code owner March 31, 2024 12:16

yarikoptic added 2 commits March 31, 2024 08:22

Add explicit wording on DICOM terms correspondence

8ccc10d

Extend to Based on for DICOM

a3e32b1

yarikoptic force-pushed the enh-dicoms branch from 535cf16 to a3e32b1 Compare March 31, 2024 12:22

bendhouseart approved these changes Apr 3, 2024

View reviewed changes

sappelhoff reviewed Apr 15, 2024

View reviewed changes

Update src/common-principles.md

db08106

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

yarikoptic commented Apr 25, 2024

View reviewed changes

src/common-principles.md Outdated Show resolved Hide resolved

Update avoiding "instructions to spec authors" language

49f686a

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

effigies approved these changes Apr 25, 2024

View reviewed changes

effigies merged commit d25a3fd into bids-standard:master Jun 17, 2024
23 of 24 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ENH] Add explicit wording on DICOM terms correspondence #1450

[ENH] Add explicit wording on DICOM terms correspondence #1450

yarikoptic commented Mar 17, 2023 •

edited

Loading

yarikoptic commented Apr 27, 2023 •

edited by sappelhoff

Loading

tsalo commented Apr 27, 2023

CPernet commented May 4, 2023

yarikoptic commented May 4, 2023

yarikoptic commented Mar 30, 2024 •

edited

Loading

CPernet commented Mar 31, 2024

codecov bot commented Mar 31, 2024 •

edited

Loading

yarikoptic commented Mar 31, 2024

yarikoptic commented Mar 31, 2024

bendhouseart left a comment

yarikoptic commented Apr 13, 2024

sappelhoff left a comment

sappelhoff Apr 15, 2024

yarikoptic Apr 15, 2024

sappelhoff Apr 15, 2024

effigies commented Apr 25, 2024

effigies left a comment

	If value is harmonized, the description SHOULD describe such correspondence as "Based on DICOM Tag ID1, ID2 `DICOM Tag Name`.".
	If the name is harmonized (against the previous recommendation), then the description SHOULD describe such correspondence as "Based on DICOM Tag ID1, ID2 `DICOM Tag Name`.".

[ENH] Add explicit wording on DICOM terms correspondence #1450

[ENH] Add explicit wording on DICOM terms correspondence #1450

Conversation

yarikoptic commented Mar 17, 2023 • edited Loading

yarikoptic commented Apr 27, 2023 • edited by sappelhoff Loading

tsalo commented Apr 27, 2023

CPernet commented May 4, 2023

yarikoptic commented May 4, 2023

yarikoptic commented Mar 30, 2024 • edited Loading

CPernet commented Mar 31, 2024

codecov bot commented Mar 31, 2024 • edited Loading

Codecov Report

yarikoptic commented Mar 31, 2024

yarikoptic commented Mar 31, 2024

bendhouseart left a comment

Choose a reason for hiding this comment

yarikoptic commented Apr 13, 2024

sappelhoff left a comment

Choose a reason for hiding this comment

sappelhoff Apr 15, 2024

Choose a reason for hiding this comment

yarikoptic Apr 15, 2024

Choose a reason for hiding this comment

sappelhoff Apr 15, 2024

Choose a reason for hiding this comment

effigies commented Apr 25, 2024

effigies left a comment

Choose a reason for hiding this comment

yarikoptic commented Mar 17, 2023 •

edited

Loading

yarikoptic commented Apr 27, 2023 •

edited by sappelhoff

Loading

yarikoptic commented Mar 30, 2024 •

edited

Loading

codecov bot commented Mar 31, 2024 •

edited

Loading