fix: clean up missing connections, fix sdc_unwarp workflow

The sdc_unwarp workflow contained a pretty weird FoV mask with a very
unclear objective.
For that reason, in this commit the FoV mask is replaced by a mask
calculated unwarping the original mask of the dataset.

Author: oesteban

sdcflows/workflows/base.py

@@ -19,7 +19,7 @@
 DEFAULT_MEMORY_MIN_GB = 0.01
 
 
-def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False, ignore=None):
+def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False):
     """
     Build a :abbr:`SDC (susceptibility distortion correction)` workflow.
 
@@ -66,7 +66,7 @@ def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False, ignore=No
 
     Outputs
     -------
-    epi_file
+    epi_corrected
         The EPI scan reference after unwarping.
     epi_mask
         The corresponding new mask after unwarping
@@ -87,28 +87,25 @@ def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False, ignore=No
         name='inputnode')
 
     outputnode = pe.Node(niu.IdentityInterface(
-        fields=['output_ref', 'epi_mask', 'epi_brain',
+        fields=['epi_corrected', 'epi_mask', 'epi_brain',
                 'out_warp', 'syn_ref', 'method']),
         name='outputnode')
 
     # No fieldmaps - forward inputs to outputs
-    ignored = False if ignore is None else 'fieldmaps' in ignore
-    if not fmaps or ignored:
+    if not fmaps:
         workflow.__postdesc__ = """\
-Susceptibility distortion correction (SDC) has been skipped because the
-dataset does not contain extra field map acquisitions correctly described
-with metadata, and the experimental SDC-SyN method was not explicitly selected.
+Susceptibility distortion correction (SDC) was omitted.
 """
         outputnode.inputs.method = 'None'
         workflow.connect([
-            (inputnode, outputnode, [('epi_file', 'output_ref'),
+            (inputnode, outputnode, [('epi_file', 'epi_corrected'),
                                      ('epi_mask', 'epi_mask'),
                                      ('epi_brain', 'epi_brain')]),
         ])
         return workflow
 
     workflow.__postdesc__ = """\
-Based on the estimated susceptibility distortion, an unwarped
+Based on the estimated susceptibility distortion, a corrected
 EPI (echo-planar imaging) reference was calculated for a more
 accurate co-registration with the anatomical reference.
 """
@@ -210,7 +207,7 @@ def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False, ignore=No
                 ('epi_brain', 'inputnode.in_reference_brain')]),
             (inputnode, sdc_unwarp_wf, [
                 ('epi_file', 'inputnode.in_reference'),
-                ('epi_brain', 'inputnode.in_reference_brain')]),
+                ('epi_mask', 'inputnode.in_reference_mask')]),
             (fmap_wf, fmap2field_wf, [
                 ('outputnode.fmap', 'inputnode.fmap'),
                 ('outputnode.fmap_ref', 'inputnode.fmap_ref'),
@@ -252,7 +249,7 @@ def init_sdc_estimate_wf(fmaps, epi_meta, omp_nthreads=1, debug=False, ignore=No
     workflow.connect([
         (sdc_unwarp_wf, outputnode, [
             ('outputnode.out_warp', 'out_warp'),
-            ('outputnode.out_reference', 'epi_file'),
+            ('outputnode.out_reference', 'epi_corrected'),
             ('outputnode.out_reference_brain', 'epi_brain'),
             ('outputnode.out_mask', 'epi_mask')]),
     ])

sdcflows/workflows/tests/test_base.py

@@ -74,10 +74,7 @@ def test_base(method):
     epi_meta = EPI_METADATA.copy()
 
     if method == 'skip':
-        wf = init_sdc_estimate_wf(fmaps=[], epi_meta=epi_meta)
-        assert wf.inputs.outputnode.method == 'None'
-
-        wf = init_sdc_estimate_wf(fmaps=fieldmaps, epi_meta=epi_meta, ignore=('fieldmaps', ))
+        wf = init_sdc_estimate_wf(fmaps=None, epi_meta=epi_meta)
         assert wf.inputs.outputnode.method == 'None'
 
         with pytest.raises(ValueError):

sdcflows/workflows/unwarp.py

@@ -1,25 +1,9 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""
-.. _sdc_unwarp :
-
-Unwarping
-~~~~~~~~~
-
-.. topic :: Abbreviations
-
-    fmap
-        fieldmap
-    VSM
-        voxel-shift map -- a 3D nifti where displacements are in pixels (not mm)
-    DFM
-        displacements field map -- a nifti warp file compatible with ANTs (mm)
-
-"""
+"""Apply the estimated fieldmap to perform susceptibility-derived distortion correction."""
 from nipype.pipeline import engine as pe
-from nipype.interfaces import fsl, utility as niu
+from nipype.interfaces import utility as niu
 from niworkflows.engine.workflows import LiterateWorkflow as Workflow
-from niworkflows.interfaces.images import FilledImageLike
 from niworkflows.interfaces.registration import ANTSApplyTransformsRPT
 from niworkflows.func.util import init_enhance_and_skullstrip_bold_wf
 
@@ -31,10 +15,8 @@ def init_sdc_unwarp_wf(omp_nthreads, debug, name='sdc_unwarp_wf'):
     This workflow takes in a displacements field through which the
     input reference can be corrected for susceptibility-derived distortion.
 
-    It also calculates a new mask for the input dataset, which takes into
-    account the (corrected) distortions.
-    The mask is restricted to the field of view of the fieldmap since outside
-    of it corrections could not be performed.
+    It also calculates a new mask for the input dataset, after the distortions
+    have been accounted for.
 
     .. workflow ::
         :graph2use: orig
@@ -58,26 +40,26 @@ def init_sdc_unwarp_wf(omp_nthreads, debug, name='sdc_unwarp_wf'):
     in_warp : os.pathlike
         The :abbr:`DFM (displacements field map)` that corrects for
         susceptibility-derived distortions estimated elsewhere.
-    in_reference
+    in_reference : os.pathlike
         the reference image to be unwarped.
-    in_reference_brain
-        a skull-stripped version corresponding to the ``in_reference``.
+    in_reference_mask : os.pathlike
+        the reference image mask to be unwarped
 
     Outputs
     -------
-    out_reference
+    out_reference : str
         the ``in_reference`` after unwarping
-    out_reference_brain
+    out_reference_brain : str
         the ``in_reference`` after unwarping and skullstripping
-    out_warp
+    out_warp : str
         the ``in_warp`` field is forwarded for compatibility
-    out_mask
+    out_mask : str
         mask of the unwarped input file
 
     """
     workflow = Workflow(name=name)
     inputnode = pe.Node(niu.IdentityInterface(
-        fields=['in_warp', 'in_reference', 'in_reference_brain']),
+        fields=['in_warp', 'in_reference', 'in_reference_mask']),
         name='inputnode')
     outputnode = pe.Node(niu.IdentityInterface(
         fields=['out_reference', 'out_reference_brain', 'out_warp', 'out_mask']),
@@ -89,30 +71,29 @@ def init_sdc_unwarp_wf(omp_nthreads, debug, name='sdc_unwarp_wf'):
                                                       interpolation='LanczosWindowedSinc'),
                                name='unwarp_reference')
 
-    fieldmap_fov_mask = pe.Node(FilledImageLike(dtype='uint8'), name='fieldmap_fov_mask')
-    fmap_fov2ref_apply = pe.Node(ANTSApplyTransformsRPT(
-        generate_report=False, dimension=3, interpolation='NearestNeighbor',
-        float=True),
-        name='fmap_fov2ref_apply')
+    unwarp_mask = pe.Node(ANTSApplyTransformsRPT(
+        dimension=3, generate_report=False, float=True,
+        interpolation='NearestNeighbor'), name='unwarp_mask')
 
-    apply_fov_mask = pe.Node(fsl.ApplyMask(), name="apply_fov_mask")
     enhance_and_skullstrip_bold_wf = init_enhance_and_skullstrip_bold_wf(omp_nthreads=omp_nthreads,
                                                                          pre_mask=True)
     workflow.connect([
         (inputnode, unwarp_reference, [
             ('in_warp', 'transforms'),
             ('in_reference', 'reference_image'),
             ('in_reference', 'input_image')]),
-        (inputnode, fieldmap_fov_mask, [('in_warp', 'in_file')]),
-        (fieldmap_fov_mask, fmap_fov2ref_apply, [('out_file', 'input_image')]),
-        (inputnode, fmap_fov2ref_apply, [('in_reference', 'reference_image')]),
-        (fmap_fov2ref_apply, apply_fov_mask, [('output_image', 'mask_file')]),
-        (unwarp_reference, apply_fov_mask, [('output_image', 'in_file')]),
-        (apply_fov_mask, enhance_and_skullstrip_bold_wf, [('out_file', 'inputnode.in_file')]),
-        (apply_fov_mask, outputnode, [('out_file', 'out_reference')]),
+        (inputnode, unwarp_mask, [
+            ('in_warp', 'transforms'),
+            ('in_reference_mask', 'reference_image'),
+            ('in_reference_mask', 'input_image')]),
+        (unwarp_reference, enhance_and_skullstrip_bold_wf, [
+            ('output_image', 'inputnode.in_file')]),
+        (unwarp_mask, enhance_and_skullstrip_bold_wf, [
+            ('output_image', 'inputnode.pre_mask')]),
+        (inputnode, outputnode, [('in_warp', 'out_warp')]),
+        (unwarp_reference, outputnode, [('output_image', 'out_reference')]),
         (enhance_and_skullstrip_bold_wf, outputnode, [
             ('outputnode.mask_file', 'out_mask'),
             ('outputnode.skull_stripped_file', 'out_reference_brain')]),
-        (inputnode, outputnode, [('in_warp', 'out_warp')]),
     ])
     return workflow