Merge pull request #2568 from mvdoc/nf/dwidenoise

ENH: add interface for MRTrix3's dwidenoise

Author: effigies

nipype/interfaces/mrtrix3/__init__.py

@@ -5,7 +5,8 @@
 
 from .utils import (Mesh2PVE, Generate5tt, BrainMask, TensorMetrics,
                     ComputeTDI, TCK2VTK, MRMath, MRConvert, DWIExtract)
-from .preprocess import ResponseSD, ACTPrepareFSL, ReplaceFSwithFIRST
+from .preprocess import (ResponseSD, ACTPrepareFSL, ReplaceFSwithFIRST,
+                         DWIDenoise)
 from .tracking import Tractography
 from .reconst import FitTensor, EstimateFOD
 from .connectivity import LabelConfig, LabelConvert, BuildConnectome

nipype/interfaces/mrtrix3/preprocess.py

@@ -11,6 +11,70 @@
 from .base import MRTrix3BaseInputSpec, MRTrix3Base
 
 
+class DWIDenoiseInputSpec(MRTrix3BaseInputSpec):
+    in_file = File(
+        exists=True,
+        argstr='%s',
+        position=-2,
+        mandatory=True,
+        desc='input DWI image')
+    mask = File(
+        exists=True,
+        argstr='-mask %s',
+        position=1,
+        desc='mask image')
+    extent = traits.Tuple((traits.Int, traits.Int, traits.Int),
+        argstr='-extent %d,%d,%d',
+        desc='set the window size of the denoising filter. (default = 5,5,5)')
+    noise = File(
+        argstr='-noise %s',
+        desc='noise map')
+    out_file = File(name_template='%s_denoised',
+        name_source='in_file',
+        keep_extension=True,
+        argstr="%s",
+        position=-1,
+        desc="the output denoised DWI image")
+
+class DWIDenoiseOutputSpec(TraitedSpec):
+    out_file = File(desc="the output denoised DWI image", exists=True)
+
+class DWIDenoise(MRTrix3Base):
+    """
+    Denoise DWI data and estimate the noise level based on the optimal
+    threshold for PCA.
+
+    DWI data denoising and noise map estimation by exploiting data redundancy
+    in the PCA domain using the prior knowledge that the eigenspectrum of
+    random covariance matrices is described by the universal Marchenko Pastur
+    distribution.
+
+    Important note: image denoising must be performed as the first step of the
+    image processing pipeline. The routine will fail if interpolation or
+    smoothing has been applied to the data prior to denoising.
+
+    Note that this function does not correct for non-Gaussian noise biases.
+
+    For more information, see
+    <https://mrtrix.readthedocs.io/en/latest/reference/commands/dwidenoise.html>
+
+    Example
+    -------
+
+    >>> import nipype.interfaces.mrtrix3 as mrt
+    >>> denoise = mrt.DWIDenoise()
+    >>> denoise.inputs.in_file = 'dwi.mif'
+    >>> denoise.inputs.mask = 'mask.mif'
+    >>> denoise.cmdline                               # doctest: +ELLIPSIS
+    'dwidenoise -mask mask.mif dwi.mif dwi_denoised.mif'
+    >>> denoise.run()                                 # doctest: +SKIP
+    """
+
+    _cmd = 'dwidenoise'
+    input_spec = DWIDenoiseInputSpec
+    output_spec = DWIDenoiseOutputSpec
+
+
 class ResponseSDInputSpec(MRTrix3BaseInputSpec):
     algorithm = traits.Enum(
         'msmt_5tt',

nipype/interfaces/mrtrix3/tests/test_auto_DWIDenoise.py

@@ -0,0 +1,61 @@
+# AUTO-GENERATED by tools/checkspecs.py - DO NOT EDIT
+from __future__ import unicode_literals
+from ..preprocess import DWIDenoise
+
+
+def test_DWIDenoise_inputs():
+    input_map = dict(
+        args=dict(argstr='%s', ),
+        bval_scale=dict(argstr='-bvalue_scaling %s', ),
+        environ=dict(
+            nohash=True,
+            usedefault=True,
+        ),
+        extent=dict(argstr='-extent %d,%d,%d', ),
+        grad_file=dict(argstr='-grad %s', ),
+        grad_fsl=dict(argstr='-fslgrad %s %s', ),
+        ignore_exception=dict(
+            deprecated='1.0.0',
+            nohash=True,
+            usedefault=True,
+        ),
+        in_bval=dict(),
+        in_bvec=dict(argstr='-fslgrad %s %s', ),
+        in_file=dict(
+            argstr='%s',
+            mandatory=True,
+            position=-2,
+        ),
+        mask=dict(
+            argstr='-mask %s',
+            position=1,
+        ),
+        noise=dict(argstr='-noise %s', ),
+        nthreads=dict(
+            argstr='-nthreads %d',
+            nohash=True,
+        ),
+        out_file=dict(
+            argstr='%s',
+            keep_extension=True,
+            name_source='in_file',
+            name_template='%s_denoised',
+            position=-1,
+        ),
+        terminal_output=dict(
+            deprecated='1.0.0',
+            nohash=True,
+        ),
+    )
+    inputs = DWIDenoise.input_spec()
+
+    for key, metadata in list(input_map.items()):
+        for metakey, value in list(metadata.items()):
+            assert getattr(inputs.traits()[key], metakey) == value
+def test_DWIDenoise_outputs():
+    output_map = dict(out_file=dict(), )
+    outputs = DWIDenoise.output_spec()
+
+    for key, metadata in list(output_map.items()):
+        for metakey, value in list(metadata.items()):
+            assert getattr(outputs.traits()[key], metakey) == value