Add ConvertWarp interface

Author: oesteban

nipype/interfaces/fsl/__init__.py

@@ -16,7 +16,7 @@
                     ImageStats, FilterRegressor, Overlay, Slicer,
                     PlotTimeSeries, PlotMotionParams, ConvertXFM,
                     SwapDimensions, PowerSpectrum, Reorient2Std,
-                    Complex, InvWarp, WarpUtils)
+                    Complex, InvWarp, WarpUtils, ConvertWarp)
 
 from .epi import (PrepareFieldmap, TOPUP, ApplyTOPUP, Eddy, EPIDeWarp,
                   SigLoss, EddyCorrect)

nipype/interfaces/fsl/preprocess.py

@@ -678,17 +678,17 @@ def _list_outputs(self):
                                                       '_variance.ext', cwd=cwd)
             outputs['std_img'] = self._gen_fname(outputs['out_file'] +
                                                  '_sigma.ext', cwd=cwd)
-                                                  
+
         # The mean image created if -stats option is specified ('meanvol')
-        # is missing the top and bottom slices. Therefore we only expose the 
-        # mean image created by -meanvol option ('mean_reg') which isn't 
+        # is missing the top and bottom slices. Therefore we only expose the
+        # mean image created by -meanvol option ('mean_reg') which isn't
         # corrupted.
         # Note that the same problem holds for the std and variance image.
-                                                  
+
         if isdefined(self.inputs.mean_vol) and self.inputs.mean_vol:
             outputs['mean_img'] = self._gen_fname(outputs['out_file'] +
                                                   '_mean_reg.ext', cwd=cwd)
-                                                  
+
         if isdefined(self.inputs.save_mats) and self.inputs.save_mats:
             _, filename = os.path.split(outputs['out_file'])
             matpathname = os.path.join(cwd, filename + '.mat')

nipype/interfaces/fsl/tests/test_auto_ConvertWarp.py

@@ -0,0 +1,71 @@
+# AUTO-GENERATED by tools/checkspecs.py - DO NOT EDIT
+from nipype.testing import assert_equal
+from nipype.interfaces.fsl.utils import ConvertWarp
+
+def test_ConvertWarp_inputs():
+    input_map = dict(abswarp=dict(argstr='--abs',
+    xor=['relwarp'],
+    ),
+    args=dict(argstr='%s',
+    ),
+    cons_jacobian=dict(argstr='--constrainj',
+    ),
+    environ=dict(nohash=True,
+    usedefault=True,
+    ),
+    ignore_exception=dict(nohash=True,
+    usedefault=True,
+    ),
+    jacobian_max=dict(argstr='--jmax=%f',
+    ),
+    jacobian_min=dict(argstr='--jmin=%f',
+    ),
+    out_abswarp=dict(argstr='--absout',
+    xor=['out_relwarp'],
+    ),
+    out_file=dict(argstr='--out=%s',
+    genfile=True,
+    hash_files=False,
+    ),
+    out_relwarp=dict(argstr='--relout',
+    xor=['out_abswarp'],
+    ),
+    output_type=dict(),
+    postmat=dict(argstr='--postmat=%s',
+    ),
+    premat=dict(argstr='--premat=%s',
+    ),
+    reference=dict(argstr='--ref=%s',
+    mandatory=True,
+    ),
+    relwarp=dict(argstr='--rel',
+    xor=['abswarp'],
+    ),
+    shift_direction=dict(argstr='--shiftdir=%s',
+    requires=['shift_in_file'],
+    ),
+    shift_in_file=dict(argstr='--shiftmap=%s',
+    ),
+    terminal_output=dict(mandatory=True,
+    nohash=True,
+    ),
+    warp1=dict(argstr='--warp1=%s',
+    ),
+    warp2=dict(argstr='--warp2=%s',
+    ),
+    )
+    inputs = ConvertWarp.input_spec()
+
+    for key, metadata in input_map.items():
+        for metakey, value in metadata.items():
+            yield assert_equal, getattr(inputs.traits()[key], metakey), value
+
+def test_ConvertWarp_outputs():
+    output_map = dict(out_file=dict(),
+    )
+    outputs = ConvertWarp.output_spec()
+
+    for key, metadata in output_map.items():
+        for metakey, value in metadata.items():
+            yield assert_equal, getattr(outputs.traits()[key], metakey), value
+

nipype/interfaces/fsl/utils.py

@@ -1578,3 +1578,122 @@ def _gen_filename(self, name):
             return self._list_outputs()[name]
 
         return None
+
+
+
+
+class ConvertWarpInputSpec(FSLCommandInputSpec):
+    reference = File(exists=True, argstr='--ref=%s', mandatory=True,
+                     desc=('Name of a file in target space of the full transform.'))
+
+    out_file = File(genfile=True, hash_files=False, argstr='--out=%s',
+                    desc=('Name of output file, containing warps that are the combination of all '
+                          'those given as arguments. The format of this will be a field-file (rather '
+                          'than spline coefficients) with any affine components included.'))
+
+    premat = File(exists=True, argstr='--premat=%s',
+                  desc='filename for pre-transform (affine matrix)')
+
+    warp1 = File(exists=True, argstr='--warp1=%s',
+                 desc=('Name of file containing warp-fields/coefficients. This could e.g. be a '
+                       'fnirt-transform from a subjects structural scan to an average of a group '
+                       'of subjects.'))
+
+    warp2 = File(exists=True, argstr='--warp2=%s',
+                 desc=('Name of file containing warp-fields/coefficients. This could e.g. be a '
+                       'fnirt-transform from the average of a group of subjects to some standard '
+                       'space (e.g. MNI152).'))
+
+    postmat = File(exists=True, argstr='--postmat=%s',
+                   desc=('Name of file containing an affine transform. It could e.g. be an affine '
+                         'transform that maps the MNI152-space into a better approximation to the '
+                         'Talairach-space (if indeed there is one).'))
+
+    shift_in_file = File(exists=True, argstr='--shiftmap=%s',
+                         desc=('Name of file containing a "shiftmap", a non-linear transform with '
+                               'displacements only in one direction. This would typically be a '
+                               'fieldmap that has been pre-processed using fugue that maps a '
+                               'subjects functional (EPI) data onto an undistorted space (i.e. a space '
+                               'that corresponds to his/her true anatomy).'))
+
+    shift_direction = traits.Enum('-y','y','x','-x','z','-z',
+                                  argstr="--shiftdir=%s", requires=['shift_in_file'],
+                                  desc=('Indicates the direction that the distortions from '
+                                        '--shiftmap goes. It depends on the direction and '
+                                        'polarity of the phase-encoding in the EPI sequence.'))
+
+    cons_jacobian = traits.Bool(False, argstr='--constrainj',
+                                desc=('Constrain the Jacobian of the warpfield to lie within specified '
+                                      'min/max limits.'))
+
+    jacobian_min = traits.Float(argstr='--jmin=%f',
+                                desc=('Minimum acceptable Jacobian value for '
+                                      'constraint (default 0.01)'))
+    jacobian_max = traits.Float(argstr='--jmax=%f',
+                                desc=('Maximum acceptable Jacobian value for '
+                                      'constraint (default 100.0)'))
+
+    abswarp = traits.Bool(argstr='--abs', xor=['relwarp'],
+                          desc=('If set it indicates that the warps in --warp1 and --warp2 should be '
+                                'interpreted as absolute. I.e. the values in --warp1/2 are the '
+                                'coordinates in the next space, rather than displacements. This flag '
+                                'is ignored if --warp1/2 was created by fnirt, which always creates '
+                                'relative displacements.'))
+
+    relwarp = traits.Bool(argstr='--rel', xor=['abswarp'],
+                          desc=('If set it indicates that the warps in --warp1/2 should be interpreted '
+                                'as relative. I.e. the values in --warp1/2 are displacements from the '
+                                'coordinates in the next space.'))
+
+    out_abswarp = traits.Bool(argstr='--absout', xor=['out_relwarp'],
+                          desc=('If set it indicates that the warps in --out should be relative, i.e. '
+                                'the vaulues in --out are displacements from the coordinates in --ref.'))
+
+    out_relwarp = traits.Bool(argstr='--relout', xor=['out_abswarp'],
+                          desc=('If set it indicates that the warps in --out should be relative, i.e. '
+                                'the vaulues in --out are displacements from the coordinates in --ref.'))
+
+
+class ConvertWarpOutputSpec(TraitedSpec):
+    out_file = File(exists=True,
+                    desc=('Name of output file, containing the warp as field or coefficients.'))
+
+
+class ConvertWarp(FSLCommand):
+    """Use FSL `convertwarp <http://fsl.fmrib.ox.ac.uk/fsl/fsl-4.1.9/fnirt/warp_utils.html>`_
+    for combining multiple transforms into one.
+
+
+    Examples::
+
+    >>> from nipype.interfaces.fsl import ConvertWarp
+    >>> warputils = ConvertWarp()
+    >>> warputils.inputs.warp1 = "warpfield.nii"
+    >>> warputils.inputs.reference = "T1.nii"
+    >>> warputils.inputs.relwarp = True
+    >>> warputils.cmdline # doctest: +ELLIPSIS
+    'convertwarp --out=.../T1_concatwarps.nii.gz --ref=T1.nii --rel --warp1=warpfield.nii'
+    >>> res = invwarp.run() # doctest: +SKIP
+    """
+
+    input_spec = ConvertWarpInputSpec
+    output_spec = ConvertWarpOutputSpec
+
+    _cmd = 'convertwarp'
+
+    def _list_outputs(self):
+        outputs = self.output_spec().get()
+        outputs['out_file'] = self.inputs.out_file
+
+        if not isdefined(outputs['out_file']):
+            outputs['out_file'] = self._gen_fname(self.inputs.reference,
+                                                  suffix='_concatwarps')
+
+        outputs['out_file'] = os.path.abspath(outputs['out_file'])
+        return outputs
+
+    def _gen_filename(self, name):
+        if name == 'out_file':
+            return self._list_outputs()[name]
+
+        return None