Improve consistency in referring to BOLD reference in reports

[effigies]

What would you like to see added in fMRIPrep?

Via @mharms

The Functional sections in the HTML report would be clearer if they used a more consistent terminology for the EPI/BOLD reference, and one which allows for the possibly that the reference is actually the “SBRef”. Currently, those sections use the phrases “target EPI”, “EPI reference”, “BOLD reference image”, and “reference EPI (BOLD) image”.

Do you have any interest in helping implement the feature?

Yes

Additional information / screenshots

No response

[effigies]

Also, it would be helpful if text for the “Susceptibility distortion correction” section explained what the red contour represents [like the text does for the following “Alignment of functional and anatomical MRI data (coregistration)” section].

[mharms]

Related to this, it seems difficult currently to know exactly what was used as the "BOLD reference", esp. in the context of "SBRef" and wanting to check whether the SBRef got used or not. In addition to making the precise "BOLD reference" clearer in the html report, it would be helpful if one could make this determination from the associated json files, since it seems (at least intuitively) that the original _sbref.nii.gz should be mentioned at some point as a raw "Source" file in one of the json's if it got used?

[mharms]

And perhaps this is getting too far afield from the original issue, but I'm not sure if what follows is intended or not in the context of using a separate "SBRef" series/recon as the "BOLD reference":

I noticed that these two files:

*_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
*__desc-coreg_boldref.json

both have a *_boldref.nii.gz listed as their "Sources" file, which seems appropriate and makes sense to me, because it is the boldref itself (whatever that happens to be) that is getting co-registered to the T1w scan.

But the following do not:

*_desc-hmc_boldref.json
*_from-boldref_to-auto00001_mode-image_xfm.json
*_space-T1w_boldref.json
*_space-MNI152NLin6Asym_boldref.json

Instead those 4 have *_bold.nii.gz listed as their first (and perhaps only) "Sources" file. In the context of an SBRef as the boldref, which is a completely separate series, not derived from the _bold.nii.gz itself in that situation, shouldn't those 4 files instead be listing the _boldref.nii.gz as the first "Sources" file (and possibly even referring instead directly to the original _sbref.nii.gz itself)?

[effigies]

Just some notes:

*_desc-hmc_boldref.json

This one is actually derived from the original BOLD and is used for head motion correction. It is correct.

*_from-boldref_to-auto00001_mode-image_xfm.json

Fixed in the upcoming release.

*_space-T1w_boldref.json

This currently has:

{
  "Sources": [
    "bids:raw:sub-100185/func/sub-100185_task-machinegame_run-01_bold.nii.gz",
    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_desc-coreg_boldref.nii.gz",
    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt",
    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_desc-fmap_xfm.txt",
    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt"
  ]
}

It should be:

 {
   "Sources": [
-    "bids:raw:sub-100185/func/sub-100185_task-machinegame_run-01_bold.nii.gz",
     "bids::sub-100185/func/sub-100185_task-machinegame_run-01_desc-coreg_boldref.nii.gz",
-    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt",
-    "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_desc-fmap_xfm.txt",
     "bids::sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt"
+    "bids::sub-100185/anat/sub-100185_desc-preproc_T1w.nii.gz"
   ]
 }

*_space-MNI152NLin6Asym_boldref.json

This currently has:

{
  "Sources": [
    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-1_bold.nii.gz",
    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-2_bold.nii.gz",
    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-3_bold.nii.gz",
    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_desc-coreg_boldref.nii.gz",
    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt",
    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-boldref_to-auto00000_mode-image_desc-fmap_xfm.txt",
    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt",
    "bids:anat:sub-02/anat/sub-02_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5",
    "bids:templateflow:tpl-MNI152NLin2009cAsym/tpl-MNI152NLin2009cAsym_res-02_T1w.nii.gz"
  ]
}

It should be:

 {
   "Sources": [
-    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-1_bold.nii.gz",
-    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-2_bold.nii.gz",
-    "bids:raw:sub-02/func/sub-02_task-cuedSGT_run-01_echo-3_bold.nii.gz",
     "bids::sub-02/func/sub-02_task-cuedSGT_run-01_desc-coreg_boldref.nii.gz",
-    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt",
-    "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-boldref_to-auto00000_mode-image_desc-fmap_xfm.txt",
     "bids::sub-02/func/sub-02_task-cuedSGT_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt",
     "bids:anat:sub-02/anat/sub-02_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5",
     "bids:templateflow:tpl-MNI152NLin2009cAsym/tpl-MNI152NLin2009cAsym_res-02_T1w.nii.gz"
   ]
 }

Will open a new issue with these notes.

[mharms]

Just some notes:

*_desc-hmc_boldref.json

This one is actually derived from the original BOLD and is used for head motion correction. It is correct.

*_from-boldref_to-auto00001_mode-image_xfm.json

So, the generic label "boldref" can sometimes refer to the sbref and other times to a volume (or perhaps mean across volumes) from the bold itself? If so, that's very confusing.