Merge pull request #2872 from nipreps/maint/coeff2epi-debugging

MAINT: Generate more verbose reports (here, showing fieldmaps) if running in debug mode

fmriprep/data/reports-spec.yml

@@ -66,7 +66,7 @@ sections:
       (for instance, T1w or T2w), it is possible to estimate the inhomogeneity of the field by means of nonlinear
       registration. The plot below shows a reference EPI (echo-planar imaging) volume generated
       using two or more EPI images with the same PE encoding, after alignment to the anatomical scan.
-    description: Hover on the panels with the mouse pointer to also visualize the intensity of the
+    description: Hover on the panels with the mouse pointer to also visualize the intensity of the 
       inhomogeneity of the field in Hertz.
     static: false
     subtitle: "Preprocessed estimation by nonlinear registration to an anatomical scan (&ldquo;<em>fieldmap-less</em>&rdquo;)"
@@ -76,17 +76,26 @@ sections:
   reportlets:
   - bids: {datatype: figures, desc: summary, suffix: bold}
   - bids: {datatype: figures, desc: validation, suffix: bold}
-  - bids: {datatype: figures, desc: fieldmap, suffix: bold}
+  - bids: {datatype: figures, desc: fmapCoreg, suffix: bold}
     caption: The estimated fieldmap was aligned to the corresponding EPI reference
-      with a rigid-registration process of the magnitude part of the fieldmap,
+      with a rigid-registration process of the anatomical reference of the fieldmap,
       using <code>antsRegistration</code>.
-      Overlaid on top of the co-registration results, the displacements along the
-      phase-encoding direction are represented in arbitrary units.
-      Please note that the color scale is centered around zero (i.e. full transparency),
-      but the extremes might be different (i.e., the maximum of red colors could be
-      orders of magnitude above or below the minimum of blue colors.)
+      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)
+  - bids: {datatype: figures, desc: fieldmap, suffix: bold}
+    caption: Estimated fieldmap, as reconstructed on the target BOLD run space to allow
+      the assessment of its alignement with the distorted data.
+      The anatomical reference is the fieldmap's reference moved into the target EPI's grid through
+      the estimated transformation.
+      In other words, this plot should be equivalent to that of the 
+      <em>Preprocessed estimation with varying Phase-Encoding (PE) blips</em> shown above in the
+      fieldmap section.
+      Therefore, the fieldmap should be positioned relative to the anatomical reference exactly
+      as it is positioned in the reportlet above.
     static: false
-    subtitle: Estimated fieldmap and alignment to the corresponding EPI reference
+    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

fmriprep/workflows/bold/base.py

@@ -1111,6 +1111,7 @@ def init_func_preproc_wf(bold_file, has_fieldmap=False):
     coeff2epi_wf = init_coeff2epi_wf(
         debug="fieldmaps" in config.execution.debug,
         omp_nthreads=config.nipype.omp_nthreads,
+        sloppy=config.execution.sloppy,
         write_coeff=True,
     )
     unwarp_wf = init_unwarp_wf(
@@ -1186,6 +1187,72 @@ def init_func_preproc_wf(bold_file, has_fieldmap=False):
     ])
     # fmt:on
 
+    if "fieldmaps" in config.execution.debug:
+        # Generate additional reportlets to assess SDC
+        from sdcflows.interfaces.reportlets import FieldmapReportlet
+
+        # First, one for checking the co-registration between fieldmap and EPI
+        sdc_coreg_report = pe.Node(
+            SimpleBeforeAfter(
+                before_label="Distorted target",
+                after_label="Fieldmap ref.",
+            ),
+            name="sdc_coreg_report",
+            mem_gb=0.1,
+        )
+        ds_report_sdc_coreg = pe.Node(
+            DerivativesDataSink(
+                base_directory=fmriprep_dir,
+                datatype="figures",
+                desc="fmapCoreg",
+                dismiss_entities=("echo",),
+                suffix="bold",
+            ),
+            name="ds_report_sdc_coreg",
+            run_without_submitting=True,
+        )
+
+        # Second, showing the fieldmap reconstructed from coefficients in the EPI space
+        fmap_report = pe.Node(FieldmapReportlet(), "fmap_report")
+
+        ds_fmap_report = pe.Node(
+            DerivativesDataSink(
+                base_directory=fmriprep_dir,
+                datatype="figures",
+                desc="fieldmap",
+                dismiss_entities=("echo",),
+                suffix="bold",
+            ),
+            name="ds_fmap_report",
+            run_without_submitting=True,
+        )
+
+        # fmt:off
+        workflow.connect([
+            (initial_boldref_wf, sdc_coreg_report, [
+                ("outputnode.ref_image", "before"),
+            ]),
+            (coeff2epi_wf, sdc_coreg_report, [
+                ("coregister.inverse_warped_image", "after"),
+            ]),
+            (final_boldref_wf, sdc_coreg_report, [
+                ("outputnode.bold_mask", "wm_seg"),
+            ]),
+            (inputnode, ds_report_sdc_coreg, [("bold_file", "source_file")]),
+            (sdc_coreg_report, ds_report_sdc_coreg, [("out_report", "in_file")]),
+            (unwarp_wf, fmap_report, [(("outputnode.fieldmap", pop_file), "fieldmap")]),
+            (coeff2epi_wf, fmap_report, [
+                ("coregister.inverse_warped_image", "reference"),
+            ]),
+            (final_boldref_wf, fmap_report, [
+                ("outputnode.bold_mask", "mask"),
+            ]),
+
+            (fmap_report, ds_fmap_report, [("out_report", "in_file")]),
+            (inputnode, ds_fmap_report, [("bold_file", "source_file")]),
+        ])
+        # fmt:on
+
     if not multiecho:
         # fmt:off
         workflow.connect([

setup.cfg

@@ -35,7 +35,7 @@ install_requires =
     psutil >= 5.4
     pybids >= 0.15.0
     requests
-    sdcflows ~= 2.1.1
+    sdcflows @ git+https://github.com/nipreps/sdcflows.git@master
     smriprep ~= 0.9.2
     tedana ~= 0.0.9
     templateflow >= 0.6