FUGUE interface refactored.

Deeply reviewed the interface to use the new name_template system,
along with the correction of several issues. Also includes changes
of another PR, so close #856.

Author: oesteban

nipype/interfaces/fsl/preprocess.py

@@ -1159,34 +1159,27 @@ def _gen_filename(self, name):
 class FUGUEInputSpec(FSLCommandInputSpec):
     in_file = File(exists=True, argstr='--in=%s',
                    desc='filename of input volume')
+    shift_in_file = File(exists=True, argstr='--loadshift=%s',
+                         desc='filename for reading pixel shift volume')
+    phasemap_in_file = File(exists=True, argstr='--phasemap=%s',
+                            desc='filename for input phase image')
+    fmap_in_file = File(exists=True, argstr='--loadfmap=%s',
+                        desc='filename for loading fieldmap (rad/s)')
     unwarped_file = File(argstr='--unwarp=%s', desc='apply unwarping and save as filename',
-                         hash_files=False)
-    forward_warping = traits.Bool(
-        False, usedefault=True,
-        desc='apply forward warping instead of unwarping')
-    warped_file = File(argstr='--warp=%s',
-                       desc='apply forward warping and save as filename',
-                       hash_files=False)
-    phasemap_file = File(exists=True, argstr='--phasemap=%s',
-                         desc='filename for input phase image')
+                         xor=['warped_file'])
+    warped_file = File(argstr='--warp=%s', desc='apply forward warping and save as filename',
+                       xor=['unwarped_file'])
+
+    forward_warping = traits.Bool(False, usedefault=True, mandatory=True,
+                                  desc='apply forward warping instead of unwarping')
+
     dwell_to_asym_ratio = traits.Float(argstr='--dwelltoasym=%.10f',
                                        desc='set the dwell to asym time ratio')
     dwell_time = traits.Float(argstr='--dwell=%.10f',
-                              desc='set the EPI dwell time per phase-encode line - same as echo spacing - (sec)')
+                              desc=('set the EPI dwell time per phase-encode line - same as echo '
+                                    'spacing - (sec)'))
     asym_se_time = traits.Float(argstr='--asym=%.10f',
                                 desc='set the fieldmap asymmetric spin echo time (sec)')
-    fmap_out_file = File(argstr='--savefmap=%s',
-                     desc='filename for saving fieldmap (rad/s)', hash_files=False)
-    fmap_in_file = File(exists=True, argstr='--loadfmap=%s',
-                        desc='filename for loading fieldmap (rad/s)')
-
-    save_shift = traits.Bool(desc='output pixel shift volume')
-
-    shift_out_file = traits.File(argstr='--saveshift=%s',
-                           desc='filename for saving pixel shift volume', hash_files=False)
-
-    shift_in_file = File(exists=True, argstr='--loadshift=%s',
-                         desc='filename for reading pixel shift volume')
     median_2dfilter = traits.Bool(argstr='--median',
                                 desc='apply 2D median filtering')
     despike_2dfilter = traits.Bool(argstr='--despike',
@@ -1216,16 +1209,22 @@ class FUGUEInputSpec(FSLCommandInputSpec):
                         desc='apply intensity correction to unwarping (pixel shift method only)')
     icorr_only = traits.Bool(argstr='--icorronly', requires=['unwarped_file'],
                              desc='apply intensity correction only')
-    mask_file = File(exists=True, argstr='--mask=%s',
-                     desc='filename for loading valid mask')
-    save_unmasked_fmap = traits.Bool(argstr='--unmaskfmap',
-                                     requires=['fmap_out_file'],
-                                     desc='saves the unmasked fieldmap when using --savefmap')
-    save_unmasked_shift = traits.Bool(argstr='--unmaskshift',
-                                      requires=['save_shift'],
+    mask_file = File(exists=True, argstr='--mask=%s', desc='filename for loading valid mask')
+    nokspace = traits.Bool(False, argstr='--nokspace', desc='do not use k-space forward warping')
+
+    # Special outputs: shift (voxel shift map, vsm)
+    save_shift = traits.Bool(False, desc='write pixel shift volume')
+    shift_out_file = File(argstr='--saveshift=%s', desc='filename for saving pixel shift volume')
+    save_unmasked_shift = traits.Bool(argstr='--unmaskshift', xor=['save_shift'],
                                       desc='saves the unmasked shiftmap when using --saveshift')
-    nokspace = traits.Bool(
-        argstr='--nokspace', desc='do not use k-space forward warping')
+
+    # Special outputs: fieldmap (fmap)
+    save_fmap = traits.Bool(False, desc='write field map volume')
+    fmap_out_file = File(argstr='--savefmap=%s', desc='filename for saving fieldmap (rad/s)')
+    save_unmasked_fmap = traits.Bool(False, argstr='--unmaskfmap', xor=['save_fmap'],
+                                     desc='saves the unmasked fieldmap when using --savefmap')
+
+
 
 
 class FUGUEOutputSpec(TraitedSpec):
@@ -1238,87 +1237,121 @@ class FUGUEOutputSpec(TraitedSpec):
 class FUGUE(FSLCommand):
     """Use FSL FUGUE to unwarp epi's with fieldmaps
 
-    Examples
-    --------
+    Example (unwarping an input image, the shift map is known) ::
 
     >>> from nipype.interfaces.fsl.preprocess import FUGUE
     >>> fugue = FUGUE()
-    >>> fugue.inputs.forward_warping = True
     >>> fugue.inputs.in_file = 'epi.nii'
     >>> fugue.inputs.mask_file = 'epi_mask.nii'
-    >>> fugue.inputs.shift_in_file = 'image.nii'  # Previously computed with fugue as well
+    >>> fugue.inputs.shift_in_file = 'vsm.nii'  # Previously computed with fugue as well
     >>> fugue.inputs.unwarp_direction = 'y'
     >>> fugue.cmdline #doctest: +ELLIPSIS
-    'fugue --in=epi.nii --mask=epi_mask.nii --loadshift=image.nii --unwarpdir=y --warp=.../epi_warped.nii.gz'
+    'fugue --in=epi.nii --mask=epi_mask.nii --loadshift=vsm.nii --unwarpdir=y --unwarp=.../epi_unwarped.nii.gz'
     >>> fugue.run() #doctest: +SKIP
 
-    """
 
-    _cmd = 'fugue'
-    input_spec = FUGUEInputSpec
-    output_spec = FUGUEOutputSpec
+    Example (warping an input image, shift map is known) ::
 
-    def __init__(self, **kwargs):
-        super(FUGUE, self).__init__(**kwargs)
-        warn(
-            'This interface has not been fully tested. Please report any failures.')
-
-    def _list_outputs(self):
-        outputs = self._outputs().get()
+    >>> from nipype.interfaces.fsl.preprocess import FUGUE
+    >>> fugue = FUGUE()
+    >>> fugue.inputs.forward_warping = True
+    >>> fugue.inputs.in_file = 'epi.nii'
+    >>> fugue.inputs.mask_file = 'epi_mask.nii'
+    >>> fugue.inputs.shift_in_file = 'vsm.nii'  # Previously computed with fugue as well
+    >>> fugue.inputs.unwarp_direction = 'y'
+    >>> fugue.cmdline #doctest: +ELLIPSIS
+    'fugue --in=epi.nii --mask=epi_mask.nii --loadshift=vsm.nii --unwarpdir=y --warp=.../epi_warped.nii.gz'
+    >>> fugue.run() #doctest: +SKIP
 
-        if isdefined(self.inputs.forward_warping) and self.inputs.forward_warping:
-            out_field = 'warped_file'
-            self.inputs.unwarped_file = Undefined
-            outputs.pop('unwarped_file')
-        else:
-            out_field = 'unwarped_file'
-            outputs.pop('warped_file')
 
-        out_file = getattr(self.inputs, out_field)
-        if not isdefined(out_file):
-            if isdefined(self.inputs.in_file):
-                out_file = self._gen_fname(self.inputs.in_file,
-                                           suffix='_'+out_field[:-5])
-        if isdefined(out_file):
-            outputs[out_field] = os.path.abspath(out_file)
-        if isdefined(self.inputs.fmap_out_file):
-            outputs['fmap_out_file'] = os.path.abspath(
-                self.inputs.fmap_out_file)
-        if isdefined(self.inputs.shift_out_file):
-            outputs['shift_out_file'] = os.path.abspath(
-                self.inputs.shift_out_file)
+    Example (computing the vsm, unwrapped phase map is known) ::
 
-        return outputs
+    >>> from nipype.interfaces.fsl.preprocess import FUGUE
+    >>> fugue = FUGUE()
+    >>> fugue.inputs.phasemap_in_file = 'epi_phasediff.nii'
+    >>> fugue.inputs.mask_file = 'epi_mask.nii'
+    >>> fugue.inputs.dwell_to_asym_ratio = 0.77e-3 / 2.46e-3
+    >>> fugue.inputs.unwarp_direction = 'y'
+    >>> fugue.inputs.save_shift = True
+    >>> fugue.cmdline #doctest: +ELLIPSIS
+    'fugue --dwelltoasym=0.7000000000 --mask=epi_mask.nii --phasemap=epi_phasediff.nii --saveshift=.../epi_phasediff_vsm.nii.gz --unwarpdir=y'
+    >>> fugue.run() #doctest: +SKIP
 
-    def _gen_filename(self, name):
-        is_fwd = isdefined(self.inputs.forward_warping) and self.inputs.forward_warping
 
-        if (is_fwd and name=='warped_file') or (not is_fwd and name=='unwarped_file'):
-            return self._list_outputs()[name]
+    """
 
-        return None
+    _cmd = 'fugue'
+    input_spec = FUGUEInputSpec
+    output_spec = FUGUEOutputSpec
 
     def _parse_inputs(self, skip=None):
         if skip is None:
             skip = []
 
-        if not isdefined(self.inputs.save_shift) or not self.inputs.save_shift:
-            skip += ['shift_out_file']
-        else:
-            if not isdefined(self.inputs.shift_out_file):
-                self.inputs.shift_out_file = self._gen_fname(
-                    self.inputs.in_file, suffix='_vsm')
+        input_phase = isdefined(self.inputs.phasemap_in_file)
+        input_vsm = isdefined(self.inputs.shift_in_file)
+        input_fmap = isdefined(self.inputs.fmap_in_file)
+
+        if not input_phase and not input_vsm and not input_fmap:
+            raise RuntimeError('Either phasemap_in_file, shift_in_file or fmap_in_file must be set.')
 
         if not isdefined(self.inputs.in_file):
             skip += ['unwarped_file', 'warped_file']
-        elif self.inputs.forward_warping:
-            if not isdefined(self.inputs.warped_file):
-                self.inputs.warped_file = self._gen_fname(
-                    self.inputs.in_file, suffix='_warped')
-        elif not self.inputs.forward_warping:
-            if not isdefined(self.inputs.unwarped_file):
-                self.inputs.unwarped_file = self._gen_fname(
-                    self.inputs.in_file, suffix='_unwarped')
+        else:
+            if self.inputs.forward_warping:
+                skip += ['unwarped_file']
+                trait_spec = self.inputs.trait('warped_file')
+                trait_spec.name_template = "%s_warped"
+                trait_spec.name_source = ['in_file']
+                trait_spec.output_name = 'warped_file'
+            else:
+                skip += ['warped_file']
+                trait_spec = self.inputs.trait('unwarped_file')
+                trait_spec.name_template = "%s_unwarped"
+                trait_spec.name_source = ['in_file']
+                trait_spec.output_name = 'unwarped_file'
+
+        # Handle shift output
+        vsm_save_masked = isdefined(self.inputs.save_shift) and self.inputs.save_shift
+        vsm_save_unmasked = isdefined(self.inputs.save_unmasked_shift) \
+                            and self.inputs.save_unmasked_shift
+
+        if (vsm_save_masked or vsm_save_unmasked) and not isdefined(self.inputs.shift_out_file):
+            trait_spec = self.inputs.trait('shift_out_file')
+            trait_spec.output_name = 'shift_out_file'
+
+            if vsm_save_unmasked:
+                trait_spec.name_template = '%s_vsm_unmasked'
+            else:
+                trait_spec.name_template = '%s_vsm'
+
+            if input_fmap:
+                trait_spec.name_source = ['fmap_in_file']
+            elif input_phase:
+                trait_spec.name_source = ['phasemap_in_file']
+            else:
+                trait_spec.name_source = ['shift_in_file']
+
+        # Handle fieldmap output
+        fmap_save_masked = isdefined(self.inputs.save_fmap) and self.inputs.save_shift
+        fmap_save_unmasked = isdefined(self.inputs.save_unmasked_fmap) and \
+                             self.inputs.save_unmasked_fmap
+
+        if (fmap_save_masked or fmap_save_unmasked) and not isdefined(self.inputs.fmap_out_file):
+            trait_spec = self.inputs.trait('fmap_out_file')
+            trait_spec.output_name = 'fmap_out_file'
+
+            if fmap_save_unmasked:
+                trait_spec.name_template = '%s_fieldmap_unmasked'
+            else:
+                trait_spec.name_template = '%s_fieldmap'
+
+            if input_vsm:
+                trait_spec.name_source = ['shift_in_file']
+            elif input_phase:
+                trait_spec.name_source = ['phasemap_in_file']
+            else:
+                trait_spec.name_source = ['fmap_in_file']
 
         return super(FUGUE, self)._parse_inputs(skip=skip)
 

nipype/interfaces/fsl/tests/test_auto_FUGUE.py

@@ -21,9 +21,9 @@ def test_FUGUE_inputs():
     fmap_in_file=dict(argstr='--loadfmap=%s',
     ),
     fmap_out_file=dict(argstr='--savefmap=%s',
-    hash_files=False,
     ),
-    forward_warping=dict(usedefault=True,
+    forward_warping=dict(mandatory=True,
+    usedefault=True,
     ),
     fourier_order=dict(argstr='--fourier=%d',
     ),
@@ -53,21 +53,21 @@ def test_FUGUE_inputs():
     ),
     phase_conjugate=dict(argstr='--phaseconj',
     ),
-    phasemap_file=dict(argstr='--phasemap=%s',
+    phasemap_in_file=dict(argstr='--phasemap=%s',
     ),
     poly_order=dict(argstr='--poly=%d',
     ),
+    save_fmap=dict(),
     save_shift=dict(),
     save_unmasked_fmap=dict(argstr='--unmaskfmap',
-    requires=['fmap_out_file'],
+    xor=['save_fmap'],
     ),
     save_unmasked_shift=dict(argstr='--unmaskshift',
-    requires=['save_shift'],
+    xor=['save_shift'],
     ),
     shift_in_file=dict(argstr='--loadshift=%s',
     ),
     shift_out_file=dict(argstr='--saveshift=%s',
-    hash_files=False,
     ),
     smooth2d=dict(argstr='--smooth2=%.2f',
     ),
@@ -79,10 +79,10 @@ def test_FUGUE_inputs():
     unwarp_direction=dict(argstr='--unwarpdir=%s',
     ),
     unwarped_file=dict(argstr='--unwarp=%s',
-    hash_files=False,
+    xor=['warped_file'],
     ),
     warped_file=dict(argstr='--warp=%s',
-    hash_files=False,
+    xor=['unwarped_file'],
     ),
     )
     inputs = FUGUE.input_spec()