[ENH] Clarify shape of PDT2 images and recommend acq entity for split PDw/T2w images

[effigies]

To briefly summarize the discussion in #223, PDT2 sequences are common in clinical settings, taking advantage of view-sharing processes to simultaneously acquire PDw and T2w volumes. It is currently ambiguous how these files should be named if the volumes are split into individual NIfTI files, which is the default behavior of BIDS converters such as dcm2niix.

It was initially proposed to add the echo- entity, which would be correct but unique among anatomical images. It was objected that clinical users may not easily recognize whether echo-1_PDT2 indicates the PDw or T2w image. On the other hand, it is possible to have PDw or T2w images in addition to PDT2 images, and recommendations for consistent unambiguous naming would be desirable.

This change intends to clarify that PDT2 images SHOULD be 4D with length 2. If PDT2 images are split, their suffixes SHOULD be PDw and T2w, respectively, and we suggest using the acq- parameter to indicate they come from the same source. @tiborauer suggested acq-partial; here I propose acq-PDT2 to be very explicit.

---

The expected impact of this is low, as PDT2 files are rare outside clinical contexts. None appear in OpenNeuro unless they have already been renamed according to the proposed convention.

The practical consequence for the validator are:

1. Add a warning if PDT2 images do not have 2 volumes. This is done in schema, and I do not currently intend to backport it to the legacy validator.
2. Remove support for PDT2map, a modality that is not believed to actually exist anywhere. This may need to be reverted and PDT2map re-added to the standard if it turns out that anybody is using it.

Closes #223.

[tiborauer]

Let me add a short elaboration. I suggested we do not have to treat these images any differently than other T2w and PDw images and use the acq field, as usual, to differentiate them. I suggested acq-partial only as an example and only if it their most relevant and distinctive feature (i.e., partial brain coverage), as suggested by @CPernet.
Similarly, I would not restrict or prescribe the value of acq field but only suggest them ("SHOULD") in line with its exiting use.

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (8bc376e) 87.90% compared to head (a145d9e) 87.90%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1448   +/-   ##
=======================================
  Coverage   87.90%   87.90%           
=======================================
  Files          14       14           
  Lines        1273     1273           
=======================================
  Hits         1119     1119           
  Misses        154      154           

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 in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[effigies]

Thanks Tibor. I agree. If there is a wording improvement to make that clearer, please feel free to suggest it.

[tiborauer]

I suggest:
and an acquisition entity MAY be used to distinguish the images from others with the same modality. For example, if the PD/T2 images cover only part of the brain, then acq-partial_PDw.nii and acq-partial_T2w.nii. If the PD/T2 images differ from other PDw and T2w images only in the sequence, then acq-PDT2_PDw.nii and acq-PDT2_T2w.nii.

[nicholst]

Thanks @effigies for creating this PR, and for updating it as per my comments in #223. I've reviewed it carefully and it looks good to me.

[agahkarakuzu]

Thank you @effigies for sending out this PR and @tiborauer @nicholst @CPernet for clarifying the use cases of this application, which were not completely resolved during the merging of BEP001.

This PR looks good to me and I think it adds to the clarity of the differentiation between weighted and quantitative use cases.

[effigies]

Thanks for the reviews, all!