[ENH] Recommend reporting of BigDelta and SmallDelta for DWI images

[kabilar]

Closes #2302

cc @satra @ayendiki @Tinggong

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.81%. Comparing base (1fd10bb) to head (6851fa9).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2309   +/-   ##
=======================================
  Coverage   82.81%   82.81%           
=======================================
  Files          22       22           
  Lines        1693     1693           
=======================================
  Hits         1402     1402           
  Misses        291      291           

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

[tsalo]

I believe that some large datasets have been using their own versions of this (e.g., HBCD has LargeDelta and SmallDelta), so it would be good to get input on the naming from some folks who might be doing something similar (@mharms, @Lestropie, @arokem).

[mharms]

BigDelta (rather than LargeDelta) and SmallDelta would be the commonly used colloquial terms.

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

[mharms]

Also, are BIDS timing parameters no longer all specified in seconds? (This proposal was specifying these parameters in msec).

[ayendiki]

BigDelta (rather than LargeDelta) and SmallDelta would be the commonly used colloquial terms.

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

That's exactly our use case for our imminent data release. There are 2 competing options right now: separate text files like bvec and bval, or a sequence of numbers in the JSON file. Would love to get a consensus that involves bvec, bval, TE, δ, Δ all being handled the same way.

[mharms]

Would love to get a consensus that involves bvec, bval, TE, δ, Δ all being handled the same way.

Well, the treatment of bvec and bval as separate text files is longstanding, and that presumably isn't going to change. Does the current standard support an array for TE, if the TE is changing as well?

[effigies]

Also, are BIDS timing parameters no longer all specified in seconds?

We have 42 fields with units s and only 3 with other time units (all ms):

󰅂 git grep 'unit: ' src/schema/objects/metadata.yaml | sed -e 's/: [ -]*/: /' | sort | uniq -c | sort -h 
      1 src/schema/objects/metadata.yaml: unit: cm
      1 src/schema/objects/metadata.yaml: unit: g/mL
      1 src/schema/objects/metadata.yaml: unit: mL
      1 src/schema/objects/metadata.yaml: unit: mL/s
      1 src/schema/objects/metadata.yaml: unit: mT.s/m
      1 src/schema/objects/metadata.yaml: unit: um
      1 src/schema/objects/metadata.yaml: unit: uT
      2 src/schema/objects/metadata.yaml: unit: arbitrary
      2 src/schema/objects/metadata.yaml: unit: cm/s
      2 src/schema/objects/metadata.yaml: unit: dB
      2 src/schema/objects/metadata.yaml: unit: MHz
      2 src/schema/objects/metadata.yaml: unit: mT/m
      3 src/schema/objects/metadata.yaml: unit: ms
      4 src/schema/objects/metadata.yaml: unit: ppm
      6 src/schema/objects/metadata.yaml: unit: degree
      6 src/schema/objects/metadata.yaml: unit: m
      8 src/schema/objects/metadata.yaml: unit: mm
     10 src/schema/objects/metadata.yaml: unit: Hz
     42 src/schema/objects/metadata.yaml: unit: s

There are two ASL metadata fields and one MRS field that use milliseconds (LabelingPulseDuration, LabelingPulseInterval, and EditPulse.PulseDuration). I don't know if there were discussions or if these flew under the radar. Possibly @HenkMutsaerts and @markmikkelsen will recall?

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

[kabilar]

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

Hi @mharms, I filed #2320 to handle this case. But there is some subsequent discussion in #2302 related to this that is also summarized by @ayendiki above.

[kabilar]

Does the current standard support an array for TE, if the TE is changing as well?

Yes, TE does allow for an array of numbers. Please see Timing parameters.

[kabilar]

Also, are BIDS timing parameters no longer all specified in seconds? (This proposal was specifying these parameters in msec).

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

Happy to switch to seconds if that is common across BIDS. I opted for milliseconds here since that is how δ and Δ (and TE) are reported in manuscripts.

[markmikkelsen]

There are two ASL metadata fields and one MRS field that use milliseconds (LabelingPulseDuration, LabelingPulseInterval, and EditPulse.PulseDuration). I don't know if there were discussions or if these flew under the radar. Possibly @HenkMutsaerts and @markmikkelsen will recall?

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

@effigies: EditPulse.PulseDuration is always reported in ms in the MRS literature, but given the vast majority of units of time in BIDS are reported in s, I wouldn't be opposed to changing it to s.

[markmikkelsen]

It's like with EchoTime and RepetitionTime: I personally always report them in ms in my papers, but they are reported in s in BIDS.

[markmikkelsen]

I can start a separate PR for this if needed.

[effigies]

No, that would break backwards compatibility. Tools could probably figure out the scale by looking at the value, but it's not worth having one interpretation in one version and another in another.

[kabilar]

Hi all, thanks for the feedback. I have updated this pull request. Next I will update #2320.

[effigies]

LGTM:

[effigies]

Makes sense from a BIDS/schema perspective. At least one positive review from a discussant and no objections would be appreciated.

My understanding of the state of the discussion is:

1. There is no standard way to encode these data in DICOM, so this PR is giving a name to these fields that will require manual (or automatic with specialized tooling) entry for the time being. The main concern here would be that we don't make life difficult if/when this does become standardized by DICOM. cc @mharms @neurolabusc for this
2. The field names follow common conventions in the DWI community, and the predominant (but not universal) BIDS convention of using seconds instead of ms.