enh: finalize connections and generate reports

Author: oesteban

dmriprep/config/reports-spec.yml

@@ -27,10 +27,30 @@ sections:
       overlaid on the participant's T1w template.
     subtitle: Surface reconstruction
 - name: Fieldmaps
-  ordering: session,run
+  ordering: session,run,fmapid
   reportlets:
+  - bids: {datatype: figures, desc: mapped, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. Some scanners produce a <em>B<sub>0</sub></em>
+      mapping of the field, using Spiral Echo Imaging (SEI) or postprocessing a "phase-difference"
+      acquisition. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    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: "Susceptibility-derived Distortion Correction (SDC): field inhomogeneity estimation"
+  - bids: {datatype: figures, desc: phasediff, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. A Gradient-Recalled Echo scheme for the 
+      mapping of the <em>B<sub>0</sub></em> inhomogeneities by subtracting the phase maps obtained at
+      two subsequent echoes. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    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: "Susceptibility-derived Distortion Correction (SDC): field inhomogeneity estimation"
   - bids: {datatype: figures, desc: pepolar, suffix: fieldmap}
-    caption: Inhomogeneities of the *B0* field introduce (oftentimes severe) spatial distortions
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
       along the phase-encoding direction of the image. Utilizing two or more images with different
       phase-encoding polarities (PEPolar) or directions, it is possible to estimate the inhomogeneity
       of the field. The plot below shows a reference EPI (echo-planar imaging) volume generated
@@ -44,11 +64,16 @@ sections:
   reportlets:
   - bids: {datatype: figures, desc: validation, suffix: dwi}
   - bids: {datatype: figures, desc: brain, suffix: mask}
-    caption: Average b=0 that serves for reference in early preprocessing steps.
-    descriptions: The reference b=0 is obtained as the voxel-wise median across
-      all b=0 found in the dataset, after accounting for signal drift.
-      The red contour shows the brain mask calculated using this reference b=0.
-    subtitle: Reference b=0 and brain mask
+    caption: Average <em>b=0</em> that serves for reference in early preprocessing steps.
+    descriptions: The reference <em>b=0</em> is obtained as the voxel-wise median across
+      all <em>b=0</em> found in the dataset, after accounting for signal drift.
+      The red contour shows the brain mask calculated using this reference <em>b=0</em>.
+    subtitle: Reference <em>b=0</em> and brain mask
+  - bids: {datatype: figures, desc: sdc, suffix: dwi}
+    caption: Susceptibility distortions correction (SDC).
+    description: The reportlet shows a <em>b=0</em> reference <em>before</em> and <em>after</em> correction.
+    static: false
+    subtitle: Unwarping of susceptibility distortions
   - bids: {datatype: figures, desc: coreg, suffix: dwi}
     caption: Diffusion-weighted data and anatomical data (EPI-space and T1w-space)
       were aligned with <code>mri_coreg</code> (FreeSurfer).

dmriprep/workflows/dwi/base.py

@@ -202,7 +202,10 @@ def _bold_reg_suffix(fallback):
         # fmt: on
 
     # REPORTING ############################################################
-    reportlets_wf = init_reportlets_wf(str(config.execution.output_dir))
+    reportlets_wf = init_reportlets_wf(
+        str(config.execution.output_dir),
+        sdc_report=has_fieldmap,
+    )
     # fmt: off
     workflow.connect([
         (inputnode, reportlets_wf, [("dwi_file", "inputnode.source_file")]),
@@ -225,6 +228,7 @@ def _bold_reg_suffix(fallback):
         # fmt: on
         return workflow
 
+    from niworkflows.interfaces import SimpleBeforeAfter
     from niworkflows.interfaces.utility import KeySelect
     from sdcflows.workflows.apply.registration import init_coeff2epi_wf
     from sdcflows.workflows.apply.correction import init_unwarp_wf
@@ -252,6 +256,12 @@ def _bold_reg_suffix(fallback):
             f"'IntendedFor' <{dwi_file}>, using {estimator_key[0]}"
         )
 
+    sdc_report = pe.Node(
+        SimpleBeforeAfter(before_label="Distorted", after_label="Corrected",),
+        name="sdc_report",
+        mem_gb=0.1,
+    )
+
     # fmt: off
     workflow.connect([
         (inputnode, output_select, [("fmap", "fmap"),
@@ -269,7 +279,12 @@ def _bold_reg_suffix(fallback):
         (dwi_reference_wf, unwarp_wf, [("outputnode.ref_image", "inputnode.distorted")]),
         (coeff2epi_wf, unwarp_wf, [
             ("outputnode.fmap_coeff", "inputnode.fmap_coeff")]),
-        (unwarp_wf, outputnode, [("outputnode.corrected", "dwi_reference")]),
+        (dwi_reference_wf, sdc_report, [("outputnode.ref_image", "before")]),
+        (unwarp_wf, sdc_report, [("outputnode.corrected", "after"),
+                                 ("outputnode.corrected_mask", "wm_seg")]),
+        (sdc_report, reportlets_wf, [("out_report", "inputnode.sdc_report")]),
+        (unwarp_wf, outputnode, [("outputnode.corrected", "dwi_reference"),
+                                 ("outputnode.corrected_mask", "dwi_mask")]),
     ])
     # fmt: on
 

dmriprep/workflows/dwi/outputs.py

@@ -5,15 +5,15 @@
 from ...interfaces import DerivativesDataSink
 
 
-def init_reportlets_wf(output_dir, name="reportlets_wf"):
+def init_reportlets_wf(output_dir, sdc_report=False, name="reportlets_wf"):
     """Set up a battery of datasinks to store reports in the right location."""
     from niworkflows.interfaces.masks import SimpleShowMaskRPT
 
     workflow = Workflow(name=name)
 
     inputnode = pe.Node(
         niu.IdentityInterface(
-            fields=["source_file", "dwi_ref", "dwi_mask", "validation_report"]
+            fields=["source_file", "dwi_ref", "dwi_mask", "validation_report", "sdc_report"]
         ),
         name="inputnode",
     )
@@ -44,4 +44,18 @@ def init_reportlets_wf(output_dir, name="reportlets_wf"):
         (mask_reportlet, ds_report_mask, [("out_report", "in_file")]),
     ])
     # fmt:on
+    if sdc_report:
+        ds_report_sdc = pe.Node(
+            DerivativesDataSink(
+                base_directory=output_dir, desc="sdc", suffix="dwi", datatype="figures"
+            ),
+            name="ds_report_sdc",
+            run_without_submitting=True,
+        )
+        # fmt:off
+        workflow.connect([
+            (inputnode, ds_report_sdc, [("source_file", "source_file"),
+                                        ("sdc_report", "in_file")]),
+        ])
+        # fmt:on
     return workflow