Merge branch 'enh/FSLb0calc' of https://github.com/oesteban/nipype into oesteban-enh/FSLb0calc

Author: chrisgorgo

CHANGES

@@ -2,6 +2,7 @@ Upcoming release 0.13
 =====================
 
 * ENH: Add a DVARS calculation interface (https://github.com/nipy/nipype/pull/1606)
+* ENH: New interface to b0calc of FSL-POSSUM (https://github.com/nipy/nipype/pull/1399)
 * ENH: Convenient load/save of interface inputs (https://github.com/nipy/nipype/pull/1591)
 * ENH: Add a Framewise Displacement calculation interface (https://github.com/nipy/nipype/pull/1604)
 * FIX: Use builtins open and unicode literals for py3 compatibility (https://github.com/nipy/nipype/pull/1572)
@@ -124,14 +125,14 @@ Release 0.11.0 (September 15, 2015)
 * FIX: Bug crashed 'make api' (https://github.com/nipy/nipype/pull/1026)
 * ENH: Updated antsIntroduction to handle RA and RI registrations (https://github.com/nipy/nipype/pull/1009)
 * ENH: Updated N4BiasCorrection input spec to include weight image and spline order. Made
-	   argument formatting consistent. Cleaned ants.segmentation according to PEP8.
-	   (https://github.com/nipy/nipype/pull/990/files)
+     argument formatting consistent. Cleaned ants.segmentation according to PEP8.
+     (https://github.com/nipy/nipype/pull/990/files)
 * ENH: SPM12 Normalize interface (https://github.com/nipy/nipype/pull/986)
 * FIX: Utility interface test dir (https://github.com/nipy/nipype/pull/986)
 * FIX: IPython engine directory reset after crash (https://github.com/nipy/nipype/pull/987)
 * ENH: Resting state fMRI example with NiPy realignment and no SPM (https://github.com/nipy/nipype/pull/992)
 * FIX: Corrected Freesurfer SegStats _list_outputs to avoid error if summary_file is
-	   undefined (issue #994)(https://https://github.com/nipy/nipype/pull/996)
+     undefined (issue #994)(https://https://github.com/nipy/nipype/pull/996)
 * FIX: OpenfMRI support and FSL 5.0.7 changes (https://github.com/nipy/nipype/pull/1006)
 * FIX: Output prefix in SPM Normalize with modulation (https://github.com/nipy/nipype/pull/1023)
 * ENH: Usability improvements in cluster environments (https://github.com/nipy/nipype/pull/1025)
@@ -213,11 +214,11 @@ Release 0.9.0 (December 20, 2013)
 * ENH: AFNI interfaces refactor, prefix, suffix are replaced by
        "flexible_%s_templates"
 * ENH: New SPM interfaces:
-		- spm.ResliceToReference,
-		- spm.DicomImport
+    - spm.ResliceToReference,
+    - spm.DicomImport
 * ENH: New AFNI interfaces:
-		- afni.AFNItoNIFTI
-		- afni.TCorr1D
+    - afni.AFNItoNIFTI
+    - afni.TCorr1D
 * ENH: Several new interfaces related to Camino were added:
         - camino.SFPICOCalibData
         - camino.Conmat
@@ -231,13 +232,13 @@ Release 0.9.0 (December 20, 2013)
         - mrtrix.FindShPeaks
         - mrtrix.Directions2Amplitude
 * ENH: New FSL interfaces:
-		- fsl.PrepareFieldmap
-		- fsl.TOPUP
-		- fsl.ApplyTOPUP
-		- fsl.Eddy
+    - fsl.PrepareFieldmap
+    - fsl.TOPUP
+    - fsl.ApplyTOPUP
+    - fsl.Eddy
 * ENH: New misc interfaces:
-		- FuzzyOverlap,
-		- P2PDistance
+    - FuzzyOverlap,
+    - P2PDistance
 * ENH: New workflows: nipype.workflows.dmri.fsl.epi.[fieldmap_correction&topup_correction]
 * ENH: Added simplified outputname generation for command line interfaces.
 * ENH: Allow ants use a single mask image
@@ -295,7 +296,7 @@ Release 0.7.0 (Dec 18, 2012)
        afni.AutoTcorrelate, DcmStack
 * ENH: New workflows: ants template building (both using 'ANTS' and the new 'antsRegistration')
 * ENH: New examples: how to use ANTS template building workflows (smri_ants_build_tmeplate),
-	  how to set SGE specific options (smri_ants_build_template_new)
+    how to set SGE specific options (smri_ants_build_template_new)
 * ENH: added no_flatten option to Merge
 * ENH: added versioning option and checking to traits
 * ENH: added deprecation metadata to traits
@@ -357,9 +358,9 @@ Release 0.5 (Mar 10, 2012)
 * API: Canned workflows are now all under a different package structure
 * API: SpecifyModel event_info renamed to event_files
 * API: DataGrabber is always being rerun (unless overwrite is set to False on
-	   Node level)
+     Node level)
 * API: "stop_on_first_rerun" does not stop for DataGrabber (unless overwrite is
-	   set to True on Node level)
+     set to True on Node level)
 * API: Output prefix can be set for spm nodes (SliceTiming, Realign, Coregister,
        Normalize, Smooth)
 

nipype/interfaces/fsl/__init__.py

@@ -30,3 +30,5 @@
 from .maths import (ChangeDataType, Threshold, MeanImage, ApplyMask,
                     IsotropicSmooth, TemporalFilter, DilateImage, ErodeImage,
                     SpatialFilter, UnaryMaths, BinaryMaths, MultiImageMaths)
+
+from .possum import B0Calc

nipype/interfaces/fsl/possum.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+"""
+The possum module provides classes for interfacing with `POSSUM
+<http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/POSSUM>`_ command line tools.
+Please, check out the link for pertinent citations using POSSUM.
+
+  .. Note:: This was written to work with FSL version 5.0.6.
+
+  .. testsetup::
+    # Change directory to provide relative paths for doctests
+    import os
+    filepath = os.path.dirname( os.path.realpath( __file__ ) )
+    datadir = os.path.realpath(os.path.join(filepath, '../../testing/data'))
+    os.chdir(datadir)
+
+"""
+
+from .base import FSLCommand, FSLCommandInputSpec
+from ..base import TraitedSpec, File, traits
+
+
+class B0CalcInputSpec(FSLCommandInputSpec):
+    in_file = File(exists=True, mandatory=True, argstr='-i %s', position=0,
+                   desc='filename of input image (usually a tissue/air segmentation)')
+    out_file = File(argstr='-o %s', position=1, name_source=['in_file'],
+                    name_template='%s_b0field', output_name='out_file',
+                    desc='filename of B0 output volume')
+
+    x_grad = traits.Float(0.0, argstr='--gx=%0.4f',
+                          desc='Value for zeroth-order x-gradient field (per mm)')
+    y_grad = traits.Float(0.0, argstr='--gy=%0.4f',
+                          desc='Value for zeroth-order y-gradient field (per mm)')
+    z_grad = traits.Float(0.0, argstr='--gz=%0.4f',
+                          desc='Value for zeroth-order z-gradient field (per mm)')
+
+    x_b0 = traits.Float(0.0, argstr='--b0x=%0.2f', xor=['xyz_b0'],
+                        desc='Value for zeroth-order b0 field (x-component), in Tesla')
+    y_b0 = traits.Float(0.0, argstr='--b0y=%0.2f', xor=['xyz_b0'],
+                        desc='Value for zeroth-order b0 field (y-component), in Tesla')
+    z_b0 = traits.Float(1.0, argstr='--b0=%0.2f', xor=['xyz_b0'],
+                        desc='Value for zeroth-order b0 field (z-component), in Tesla')
+
+    xyz_b0 = traits.Tuple(
+        traits.Float, traits.Float, traits.Float,
+        argstr='--b0x=%0.2f --b0y=%0.2f --b0=%0.2f', xor=['x_b0', 'y_b0', 'z_b0'],
+        desc='Zeroth-order B0 field in Tesla')
+
+    delta = traits.Float(-9.45e-6, argstr='-d %e',
+                         desc='Delta value (chi_tissue - chi_air)')
+    chi_air = traits.Float(
+        4.0e-7, argstr='--chi0=%e', desc='susceptibility of air')
+    compute_xyz = traits.Bool(False, argstr='--xyz',
+                              desc='calculate and save all 3 field components (i.e. x,y,z)')
+    extendboundary = traits.Float(1.0, argstr='--extendboundary=%0.2f',
+                                  desc='Relative proportion to extend voxels at boundary')
+    directconv = traits.Bool(False, argstr='--directconv',
+                             desc='use direct (image space) convolution, not FFT')
+
+
+class B0CalcOutputSpec(TraitedSpec):
+    out_file = File(exists=True, desc='filename of B0 output volume')
+
+
+class B0Calc(FSLCommand):
+
+    """
+    B0 inhomogeneities occur at interfaces of materials with different magnetic susceptibilities,
+    such as tissue-air interfaces. These differences lead to distortion in the local magnetic field,
+    as Maxwell’s equations need to be satisfied. An example of B0 inhomogneity is the first volume
+    of the 4D volume ```$FSLDIR/data/possum/b0_ppm.nii.gz```.
+
+    Examples
+    --------
+
+    >>> from nipype.interfaces.fsl import B0Calc
+    >>> b0calc = B0Calc()
+    >>> b0calc.inputs.in_file = 'tissue+air_map.nii'
+    >>> b0calc.inputs.z_b0 = 3.0
+    >>> b0calc.cmdline  # doctest: +IGNORE_UNICODE
+    'b0calc -i tissue+air_map.nii -o tissue+air_map_b0field.nii.gz --b0=3.00'
+
+    """
+
+    _cmd = 'b0calc'
+    input_spec = B0CalcInputSpec
+    output_spec = B0CalcOutputSpec

nipype/interfaces/fsl/tests/test_auto_B0Calc.py

@@ -0,0 +1,71 @@
+# AUTO-GENERATED by tools/checkspecs.py - DO NOT EDIT
+from ....testing import assert_equal
+from ..possum import B0Calc
+
+
+def test_B0Calc_inputs():
+    input_map = dict(args=dict(argstr='%s',
+    ),
+    chi_air=dict(argstr='--chi0=%e',
+    ),
+    compute_xyz=dict(argstr='--xyz',
+    ),
+    delta=dict(argstr='-d %e',
+    ),
+    directconv=dict(argstr='--directconv',
+    ),
+    environ=dict(nohash=True,
+    usedefault=True,
+    ),
+    extendboundary=dict(argstr='--extendboundary=%0.2f',
+    ),
+    ignore_exception=dict(nohash=True,
+    usedefault=True,
+    ),
+    in_file=dict(argstr='-i %s',
+    mandatory=True,
+    position=0,
+    ),
+    out_file=dict(argstr='-o %s',
+    name_source=['in_file'],
+    name_template='%s_b0field',
+    output_name='out_file',
+    position=1,
+    ),
+    output_type=dict(),
+    terminal_output=dict(nohash=True,
+    ),
+    x_b0=dict(argstr='--b0x=%0.2f',
+    xor=['xyz_b0'],
+    ),
+    x_grad=dict(argstr='--gx=%0.4f',
+    ),
+    xyz_b0=dict(argstr='--b0x=%0.2f --b0y=%0.2f --b0=%0.2f',
+    xor=['x_b0', 'y_b0', 'z_b0'],
+    ),
+    y_b0=dict(argstr='--b0y=%0.2f',
+    xor=['xyz_b0'],
+    ),
+    y_grad=dict(argstr='--gy=%0.4f',
+    ),
+    z_b0=dict(argstr='--b0=%0.2f',
+    xor=['xyz_b0'],
+    ),
+    z_grad=dict(argstr='--gz=%0.4f',
+    ),
+    )
+    inputs = B0Calc.input_spec()
+
+    for key, metadata in list(input_map.items()):
+        for metakey, value in list(metadata.items()):
+            yield assert_equal, getattr(inputs.traits()[key], metakey), value
+
+
+def test_B0Calc_outputs():
+    output_map = dict(out_file=dict(),
+    )
+    outputs = B0Calc.output_spec()
+
+    for key, metadata in list(output_map.items()):
+        for metakey, value in list(metadata.items()):
+            yield assert_equal, getattr(outputs.traits()[key], metakey), value