DOC: Improve report captions and update expected outputs in docs (#3137)

This PR focuses on non-fasttrack reports. If issues are found in the
fasttrack versions, we can deal with them after the alpha.

Author: effigies

docs/outputs.rst

@@ -131,10 +131,16 @@ If FreeSurfer reconstructions are used, the following surface files are generate
 
   sub-<subject_label>/
     anat/
-      sub-<subject_label>_hemi-[LR]_smoothwm.surf.gii
-      sub-<subject_label>_hemi-[LR]_pial.surf.gii
+      sub-<subject_label>_hemi-[LR]_white.surf.gii
       sub-<subject_label>_hemi-[LR]_midthickness.surf.gii
-      sub-<subject_label>_hemi-[LR]_inflated.surf.gii
+      sub-<subject_label>_hemi-[LR]_pial.surf.gii
+      sub-<subject_label>_hemi-[LR]_desc-reg_sphere.surf.gii
+      sub-<subject_label>_hemi-[LR]_space-fsLR_desc-reg_sphere.surf.gii
+      sub-<subject_label>_hemi-[LR]_space-fsLR_desc-msmsulc_sphere.surf.gii
+
+The registration spheres target ``fsaverage`` and ``fsLR`` spaces. If MSM
+is enabled (i.e., the ``--no-msm`` flag is not passed), then the ``msmsulc``
+spheres are generated and used for creating ``space-fsLR`` derivatives.
 
 And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's
 conformed space for surface reconstruction (``fsnative``) is stored in::
@@ -144,6 +150,27 @@ conformed space for surface reconstruction (``fsnative``) is stored in::
       sub-<subject_label>_from-fsnative_to-T1w_mode-image_xfm.txt
       sub-<subject_label>_from-T1w_to-fsnative_mode-image_xfm.txt
 
+Finally, cortical thickness, curvature, and sulcal depth maps are converted to GIFTI
+and CIFTI-2::
+
+  sub-<subject_label>/
+    anat/
+      sub-<subject_label>_hemi-[LR]_thickness.shape.gii
+      sub-<subject_label>_hemi-[LR]_curv.shape.gii
+      sub-<subject_label>_hemi-[LR]_sulc.shape.gii
+      sub-<subject_label>_space-fsLR_den-32k_thickness.dscalar.nii
+      sub-<subject_label>_space-fsLR_den-32k_curv.dscalar.nii
+      sub-<subject_label>_space-fsLR_den-32k_sulc.dscalar.nii
+
+.. warning::
+
+   GIFTI metric files follow the FreeSurfer conventions and are not modified
+   by *fMRIPrep* in any way.
+
+   The Human Connectome Project (HCP) inverts the sign of the curvature and
+   sulcal depth maps. For consistency with HCP, *fMRIPrep* follows these
+   conventions and masks the medial wall of CIFTI-2 dscalar files.
+
 .. _fsderivs:
 
 FreeSurfer derivatives
@@ -187,16 +214,63 @@ these will be indicated with ``[specifiers]``::
 
   sub-<subject_label>/
     func/
-      sub-<subject_label>_[specifiers]_space-<space_label>_boldref.nii.gz
       sub-<subject_label>_[specifiers]_space-<space_label>_desc-brain_mask.nii.gz
       sub-<subject_label>_[specifiers]_space-<space_label>_desc-preproc_bold.nii.gz
 
-Additionally, the following transforms are saved::
+.. note::
+
+   The mask file is part of the *minimal* processing level. The BOLD series
+   is only generated at the *full* processing level.
+
+**Motion correction outputs**.
+
+Head-motion correction (HMC) produces a reference image to which all volumes
+are aligned, and a corresponding transform that maps the original BOLD series
+to the reference image::
+
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_desc-hmc_boldref.nii.gz
+      sub-<subject_label>_[specifiers]_from-orig_to_boldref_mode-image_desc-hmc_xfm.nii.gz
+
+.. note::
+
+   Motion correction outputs are part of the *minimal* processing level.
+
+**Coregistration outputs**.
+
+Registration of the BOLD series to the T1w image generates a further reference
+image and affine transform::
 
   sub-<subject_label>/
     func/
-      sub-<subject_label>_[specifiers]_from-scanner_to-T1w_mode-image_xfm.txt
-      sub-<subject_label>_[specifiers]_from-T1w_to-scanner_mode-image_xfm.txt
+      sub-<subject_label>_[specifiers]_desc-coreg_boldref.nii.gz
+      sub-<subject_label>_[specifiers]_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
+
+.. note::
+
+   Coregistration outputs are part of the *minimal* processing level.
+
+**Fieldmap registration**.
+
+If a fieldmap is used for the correction of a BOLD series, then a registration
+is calculated between the BOLD series and the fieldmap. If, for example, the fieldmap
+is identified with ``"B0Identifier": "TOPUP"``, the generated transform will be named::
+
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_from-boldref_to-TOPUP_mode-image_xfm.nii.gz
+
+If the association is discovered through the ``IntendedFor`` field of the
+fieldmap metadata, then the transform will be given an auto-generated name::
+
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_from-boldref_to-auto000XX_mode-image_xfm.txt
+
+.. note::
+
+   Fieldmap registration outputs are part of the *minimal* processing level.
 
 **Regularly gridded outputs (images)**.
 Volumetric output spaces labels (``<space_label>`` above, and in the following) include

fmriprep/data/reports-spec.yml

@@ -82,7 +82,7 @@ sections:
       Overlaid on top of the co-registration results, the final BOLD mask is represented
       with a red contour for reference.
     static: false
-    subtitle: Alignment between the anatomical reference of the fieldmap and the target EPI (debug mode)
+    subtitle: Alignment between the anatomical reference of the fieldmap and the target EPI
   - bids: {datatype: figures, desc: fieldmap, suffix: bold}
     caption: Estimated fieldmap, as reconstructed on the target BOLD run space to allow
       the assessment of its alignment with the distorted data.
@@ -97,7 +97,9 @@ sections:
     subtitle: "Reconstructed <em>B<sub>0</sub></em> map in the corresponding run's space (debug mode)"
   - bids: {datatype: figures, desc: sdc, suffix: bold}
     caption: Results of performing susceptibility distortion correction (SDC) on the
-      EPI
+      BOLD reference image. The "distorted" image is the image that would be used to
+      align to the anatomical reference if SDC were not applied. The "corrected"
+      image is the image that was used.
     static: false
     subtitle: Susceptibility distortion correction
   - bids: {datatype: figures, desc: forcedsyn, suffix: bold}
@@ -118,37 +120,15 @@ sections:
       appear in the 100ms bin.
     static: false
     subtitle: T2* gray-matter values
-  - bids: {datatype: figures, desc: flirtnobbr, suffix: bold}
-    caption: <code>mri_coreg</code> (FreeSurfer) was used to generate transformations
-      from EPI space to T1 Space - BBR refinement using FSL <code>flirt</code> rejected.
-      Note that Nearest Neighbor interpolation is used in the reportlets in order to
-      highlight potential spin-history and other artifacts, whereas final images are
-      resampled using Lanczos interpolation.
-    static: false
-    subtitle: Alignment of functional and anatomical MRI data (volume based)
   - bids: {datatype: figures, desc: coreg, suffix: bold}
-    caption: <code>mri_coreg</code> (FreeSurfer) was used to generate transformations
-      from EPI space to T1 Space - <code>bbregister</code> refinement rejected. Note
-      that Nearest Neighbor interpolation is used in the reportlets in order to highlight
-      potential spin-history and other artifacts, whereas final images are resampled
-      using Lanczos interpolation.
-    static: false
-    subtitle: Alignment of functional and anatomical MRI data (volume based)
-  - bids: {datatype: figures, desc: flirtbbr, suffix: bold}
-    caption: FSL <code>flirt</code> was used to generate transformations from EPI-space
-      to T1w-space - The white matter mask calculated with FSL <code>fast</code> (brain
-      tissue segmentation) was used for BBR. Note that Nearest Neighbor interpolation
-      is used in the reportlets in order to highlight potential spin-history and other
-      artifacts, whereas final images are resampled using Lanczos interpolation.
-    static: false
-    subtitle: Alignment of functional and anatomical MRI data (surface driven)
-  - bids: {datatype: figures, desc: bbregister, suffix: bold}
-    caption: <code>bbregister</code> was used to generate transformations from EPI-space
-      to T1w-space. Note that Nearest Neighbor interpolation is used in the reportlets
-      in order to highlight potential spin-history and other artifacts, whereas final
-      images are resampled using Lanczos interpolation.
+    caption: This panel shows the alignment of the reference EPI (BOLD) image to the
+      anatomical (T1-weighted) image.
+      The reference EPI has been contrast enhanced and susceptibility-distortion
+      corrected (if applicable) for improved anatomical fidelity.
+      The anatomical image has been resampled into EPI space, as well as the
+      anatomical white matter mask, which appears as a red contour.
     static: false
-    subtitle: Alignment of functional and anatomical MRI data (surface driven)
+    subtitle: Alignment of functional and anatomical MRI data (coregistration)
   - bids: {datatype: figures, desc: rois, suffix: bold}
     caption: Brain mask calculated on the BOLD signal (red contour), along with the
       regions of interest (ROIs) used for the estimation of physiological and movement

fmriprep/workflows/bold/fit.py

@@ -354,6 +354,7 @@ def init_bold_fit_wf(
         ]),
         (outputnode, func_fit_reports_wf, [
             ("coreg_boldref", "inputnode.coreg_boldref"),
+            ("bold_mask", "inputnode.bold_mask"),
             ("boldref2anat_xfm", "inputnode.boldref2anat_xfm"),
         ]),
         (summary, func_fit_reports_wf, [("out_report", "inputnode.summary_report")]),

fmriprep/workflows/bold/outputs.py

@@ -195,6 +195,7 @@ def init_func_fit_reports_wf(
         "source_file",
         "sdc_boldref",
         "coreg_boldref",
+        "bold_mask",
         "boldref2anat_xfm",
         "boldref2fmap_xfm",
         "t1w_preproc",
@@ -368,7 +369,8 @@ def init_func_fit_reports_wf(
             ]),
             (inputnode, sdcreg_report, [
                 ('sdc_boldref', 'reference'),
-                ('fieldmap', 'fieldmap')
+                ('fieldmap', 'fieldmap'),
+                ('bold_mask', 'mask'),
             ]),
             (fmapref_boldref, sdcreg_report, [('output_image', 'moving')]),
             (inputnode, ds_sdcreg_report, [('source_file', 'source_file')]),