multiple fixes and new features

* ApplyTopup is now called with correct arguments when the reversed
  encoding image is only one b0
* Added documentation
* Deprecated old workflows in nipype.workflows.dmri.fsl (added warnings in
  both documentation and code)
* Updated CHANGES

Author: oesteban

CHANGES

@@ -1,6 +1,8 @@
 Next Release
 ============
 
+* ENH: Deep revision of worflows for correction of dMRI artifacts. New dmri_preprocessing
+       example.
 * ENH: New Freesurfer interface: MRIPretess
 * ENH: New miscelaneous interface: AddCSVRow
 * ENH: FUGUE interface has been refactored to use the name_template system, 3 examples 

nipype/workflows/dmri/fsl/epi.py

@@ -4,17 +4,22 @@
 import nipype.interfaces.utility as niu
 import nipype.interfaces.fsl as fsl
 import os
+import warnings
 
 def create_dmri_preprocessing(name='dMRI_preprocessing', use_fieldmap=True, fieldmap_registration=False):
-    """Creates a workflow that chains the necessary pipelines to
+    """
+    Creates a workflow that chains the necessary pipelines to
     correct for motion, eddy currents, and, if selected, susceptibility
     artifacts in EPI dMRI sequences.
 
-    .. warning::
+    .. deprecated:: 0.9.3
+      Use :func:`nipype.workflows.dmri.preprocess.epi.all_fmb_pipeline` or
+      :func:`nipype.workflows.dmri.preprocess.epi.all_peb_pipeline` instead.
+
 
-    IMPORTANT NOTICE: this workflow rotates the b-vectors, so please be adviced
-    that not all the dicom converters ensure the consistency between the resulting
-    nifti orientation and the b matrix table (e.g. dcm2nii checks it).
+    .. warning:: This workflow rotates the b-vectors, so please be
+      advised that not all the dicom converters ensure the consistency between the resulting
+      nifti orientation and the b matrix table (e.g. dcm2nii checks it).
 
 
     Example
@@ -54,12 +59,16 @@ def create_dmri_preprocessing(name='dMRI_preprocessing', use_fieldmap=True, fiel
 
 
     Optional arguments::
+
         use_fieldmap - True if there are fieldmap files that should be used (default True)
         fieldmap_registration - True if registration to fieldmap should be performed (default False)
 
 
     """
 
+    warnings.warn(('This workflow is deprecated from v.1.0.0, use of available '
+                  'nipype.workflows.dmri.preprocess.epi.all_*'), DeprecationWarning)
+
     pipeline = pe.Workflow(name=name)
 
     inputnode = pe.Node(niu.IdentityInterface(
@@ -118,10 +127,12 @@ def create_motion_correct_pipeline(name='motion_correct'):
     (Leemans et al. 2009 - http://www.ncbi.nlm.nih.gov/pubmed/19319973),
     making use of the rotation matrix obtained by FLIRT.
 
-    .. deprecated:: 1.0.0.
-      Use :func:`nipype.workflows.dmri.preprocess.epi.motion_correct` instead
 
-    .. warning:: IMPORTANT NOTICE: this workflow rotates the b-vectors, so please be adviced
+    .. deprecated:: 0.9.3
+      Use :func:`nipype.workflows.dmri.preprocess.epi.hmc_pipeline` instead.
+
+
+    .. warning:: This workflow rotates the b-vectors, so please be adviced
       that not all the dicom converters ensure the consistency between the resulting
       nifti orientation and the b matrix table (e.g. dcm2nii checks it).
 
@@ -148,6 +159,10 @@ def create_motion_correct_pipeline(name='motion_correct'):
 
     """
 
+    warnings.warn(('This workflow is deprecated from v.1.0.0, use '
+                  'nipype.workflows.dmri.preprocess.epi.hmc_pipeline instead'),
+                  DeprecationWarning)
+
     inputnode = pe.Node(
         niu.IdentityInterface(
             fields=['in_file', 'ref_num', 'in_bvec']),
@@ -184,7 +199,13 @@ def create_motion_correct_pipeline(name='motion_correct'):
 
 
 def create_eddy_correct_pipeline(name='eddy_correct'):
-    """Creates a pipeline that replaces eddy_correct script in FSL. It takes a
+    """
+
+    .. deprecated:: 0.9.3
+      Use :func:`nipype.workflows.dmri.preprocess.epi.ecc_pipeline` instead.
+
+
+    Creates a pipeline that replaces eddy_correct script in FSL. It takes a
     series of diffusion weighted images and linearly co-registers them to one
     reference image. No rotation of the B-matrix is performed, so this pipeline
     should be executed after the motion correction pipeline.
@@ -207,6 +228,10 @@ def create_eddy_correct_pipeline(name='eddy_correct'):
         outputnode.eddy_corrected
     """
 
+    warnings.warn(('This workflow is deprecated from v.1.0.0, use '
+                  'nipype.workflows.dmri.preprocess.epi.ecc_pipeline instead'),
+                  DeprecationWarning)
+
     inputnode = pe.Node(
         niu.IdentityInterface(fields=['in_file', 'ref_num']),
                         name='inputnode')
@@ -238,6 +263,11 @@ def create_eddy_correct_pipeline(name='eddy_correct'):
 
 def fieldmap_correction(name='fieldmap_correction', nocheck=False):
     """
+
+    .. deprecated:: 0.9.3
+      Use :func:`nipype.workflows.dmri.preprocess.epi.sdc_fmb` instead.
+
+
     Fieldmap-based retrospective correction of EPI images for the susceptibility distortion
     artifact (Jezzard et al., 1995). Fieldmap images are assumed to be already registered
     to EPI data, and a brain mask is required.
@@ -247,7 +277,6 @@ def fieldmap_correction(name='fieldmap_correction', nocheck=False):
     available as of FSL 5.0.
 
 
-
     Example
     -------
 
@@ -283,6 +312,10 @@ def fieldmap_correction(name='fieldmap_correction', nocheck=False):
 
     """
 
+    warnings.warn(('This workflow is deprecated from v.1.0.0, use '
+                  'nipype.workflows.dmri.preprocess.epi.sdc_fmb instead'),
+                  DeprecationWarning)
+
     inputnode = pe.Node(niu.IdentityInterface(
                         fields=['in_file',
                         'in_mask',
@@ -361,8 +394,13 @@ def fieldmap_correction(name='fieldmap_correction', nocheck=False):
 
 def topup_correction( name='topup_correction' ):
     """
-        Corrects for susceptibilty distortion of EPI images when one reverse encoding dataset has
-        been acquired
+
+    .. deprecated:: 0.9.3
+      Use :func:`nipype.workflows.dmri.preprocess.epi.sdc_peb` instead.
+
+
+    Corrects for susceptibilty distortion of EPI images when one reverse encoding dataset has
+    been acquired
 
 
     Example
@@ -375,18 +413,26 @@ def topup_correction( name='topup_correction' ):
     >>> nipype_epicorrect.inputs.inputnode.ref_num = 0
     >>> nipype_epicorrect.run() # doctest: +SKIP
 
+
     Inputs::
+
         inputnode.in_file_dir - EPI volume acquired in 'forward' phase encoding
         inputnode.in_file_rev - EPI volume acquired in 'reversed' phase encoding
         inputnode.encoding_direction - Direction encoding of in_file_dir
         inputnode.ref_num - Identifier of the reference volumes (usually B0 volume)
 
+
     Outputs::
 
         outputnode.epi_corrected
 
 
     """
+
+    warnings.warn(('This workflow is deprecated from v.1.0.0, use '
+                  'nipype.workflows.dmri.preprocess.epi.sdc_peb instead'),
+                  DeprecationWarning)
+
     pipeline = pe.Workflow(name=name)
 
     inputnode = pe.Node(niu.IdentityInterface(
@@ -436,11 +482,18 @@ def topup_correction( name='topup_correction' ):
 
 
 def create_epidewarp_pipeline(name='epidewarp', fieldmap_registration=False):
-    """ Replaces the epidewarp.fsl script (http://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)
+    """
+    Replaces the epidewarp.fsl script (http://www.nmr.mgh.harvard.edu/~greve/fbirn/b0/epidewarp.fsl)
     for susceptibility distortion correction of dMRI & fMRI acquired with EPI sequences and the fieldmap
     information (Jezzard et al., 1995) using FSL's FUGUE. The registration to the (warped) fieldmap
     (strictly following the original script) is available using fieldmap_registration=True.
 
+
+    .. warning:: This workflow makes use of ``epidewarp.fsl`` a script of FSL deprecated long
+      time ago. The use of this workflow is not recommended, use
+      :func:`nipype.workflows.dmri.preprocess.epi.sdc_fmb` instead.
+
+
     Example
     -------
 
@@ -480,6 +533,9 @@ def create_epidewarp_pipeline(name='epidewarp', fieldmap_registration=False):
 
     """
 
+    warnings.warn(('This workflow reproduces a deprecated FSL script.'),
+                  DeprecationWarning)
+
     inputnode = pe.Node(niu.IdentityInterface(fields=['in_file',
                                                                    'fieldmap_mag',
                                                                    'fieldmap_pha',

nipype/workflows/dmri/preprocess/epi.py

@@ -519,25 +519,22 @@ def sdc_peb(name='peb_correction',
     topup.inputs.encoding_direction = [epi_params['enc_dir'], altepi_params['enc_dir']]
     topup.inputs.readout_times = [epi_params['echospacing']/(1.0*epi_params['acc_factor']),
                                   altepi_params['echospacing']/(1.0*altepi_params['acc_factor'])]
-    unwarp = pe.Node(fsl.ApplyTOPUP(in_index=[1,2]), name='unwarp')
-    dwi_comb = pe.Node(niu.Merge(2), name='DWIcomb')
+    unwarp = pe.Node(fsl.ApplyTOPUP(in_index=[1], method='jac'), name='unwarp')
 
     wf = pe.Workflow(name=name)
     wf.connect([
          (inputnode,  b0_ref,     [('in_file','in_file'),
                                    (('ref_num', _checkrnum),'t_min')])
         ,(inputnode,  b0_alt,     [('alt_file','in_file'),
                                    (('ref_num', _checkrnum),'t_min')])
-        ,(inputnode,  dwi_comb,   [('in_file','in1'),
-                                   ('alt_file','in2') ] )
-        ,(b0_ref,     b0_comb,    [('roi_file','in1')] )
-        ,(b0_alt,     b0_comb,    [('roi_file','in2')] )
-        ,(b0_comb,    b0_merge,   [('out', 'in_files')] )
+        ,(b0_ref,     b0_comb,    [('roi_file','in1')])
+        ,(b0_alt,     b0_comb,    [('roi_file','in2')])
+        ,(b0_comb,    b0_merge,   [('out', 'in_files')])
         ,(b0_merge,   topup,      [('merged_file','in_file')])
         ,(topup,      unwarp,     [('out_fieldcoef','in_topup_fieldcoef'),
                                    ('out_movpar','in_topup_movpar'),
                                    ('out_enc_file','encoding_file')])
-        ,(dwi_comb,   unwarp,     [('out','in_files')])
+        ,(inputnode,  unwarp,     [('in_file','in_files')])
         ,(unwarp,     outputnode, [('out_corrected','out_file')])
     ])
     return wf