[ENH] Add ParallelReductionFactorOutOfPlane to MRI metadata

[lukeje]

This pull request adds the attribute "ParallelReductionFactorOutOfPlane" (corresponding to the DICOM tag (0018,9155) "Parallel Reduction Factor out-of-plane") to the MRI schema to allow proper specification of parallel imaging in the out of plane direction.

This is necessary because 3D MRI sequences are often acquired with parallel imaging applied in both the in plane and out of plane directions, for example in this open dataset: https://doi.org/10.1016/j.dib.2019.104132, where an acceleration factor of 2 was used in plane and also out of plane (2 x 2 GRAPPA). This cannot be captured with the current schema, where only "ParallelReductionFactorInPlane" is defined.

Please note that "ParallelReductionFactorOutOfPlane" is distinct from and independent of the "MultibandAccelerationFactor", which defines acceleration by acquiring multiple non-adjacent slices in 2D sequences.

[codecov]

Codecov Report

Base: 88.39% // Head: 88.39% // No change to project coverage 👍

Coverage data is based on head (029f2c4) compared to base (3270d01).
Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1221   +/-   ##
=======================================
  Coverage   88.39%   88.39%           
=======================================
  Files          11       11           
  Lines        1086     1086           
=======================================
  Hits          960      960           
  Misses        126      126           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

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

[effigies]

This makes sense to me. I think it might make sense to change the heading for the table to just "Spatial encoding" and include the OutOfPlane parameter in the same table as InPlane. WDYT?

And what do you think about making the requirement level RECOMMENDED if `MRAcquisitionType` is `"3D"` , as I think it doesn't really have an interpretation for 2D sequences?

[lukeje]

@effigies I would be fine with combining the tables into one table under the heading "Spatial encoding". I was just trying to be minimally invasive as to what was there before.

Regarding making the requirement level conditional, how about OPTIONAL, but RECOMMENDED if `MRAcquisitionType` is `"3D"`? In general 2D sequences will always fully sample the excited slice (as collecting just k = 0 is sufficient to "spatially encode" one slice), but there are cases (e.g. multislab acquisitions, super-resolution imaging, gSlider) where one might impose different spatial encodings on the slices (slabs) in a 2D acquisition for later combination.

Let me know what you think, and I will have a go at implementing these changes.

[effigies]

My concern here is that if we take RECOMMENDED and OPTIONAL seriously, they have the following definitions:

3. SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

5. MAY This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

Consequently, the validator is beginning to warn on more missing RECOMMENDED values and we should be careful about adding to the list of fields that will alert the user.

Looking at the DICOM standard, the out-of-plane metadata is REQUIRED/OPTIONAL in the same conditions that In-plane is, so I think it's reasonable for them to have the same requirement level, which would be RECOMMENDED. I suppose my remaining question is if you know if this tag is ubiquitous in practice?

cc @neurolabusc for thoughts

[effigies]

Made some suggestions, as the tables are now generated directly from the rules/sidecars/*.yaml. See the rendered doc here: https://bids-specification--1221.org.readthedocs.build/en/1221/04-modality-specific-files/01-magnetic-resonance-imaging-data.html

[lukeje]

Thank you @effigies for pushing this forward. As the new metadata field is "RECOMMENDED", I added a brief clarification that ParallelReductionFactorOutOfPlane should typically be 1 for 2D sequences, and a brief bit of disambiguating text to distinguish it from MultibandAccelerationFactor.

Otherwise it is all good from my side.

[lukeje]

I suppose my remaining question is if you know if this tag is ubiquitous in practice?

According to @neurolabusc's dcm2niix documentation, it corresponds to AccelFact3D in Siemens DICOMs and is the second element of the Asset R Factors in GE DICOMs.

[effigies]

@bids-standard/maintainers Anybody up for a second review?