Merge remote-tracking branch 'upstream/master' into fix/clirun

* upstream/master:
  fix errors in niftyreg workflows docstrings
  fixing the confounds doc build
  disable dummy test, close #1933
  force exit if any test failed
  [skip ci] Update CHANGES
  [FIX] Ensure build fails in Circle when tests fail
  Fixed description.
  fixing arg strings
  fixing expected output string
  naming fixes
  Added documentation and doctests.
  add qwarp

Author: satra

.circle/tests.sh

@@ -19,25 +19,33 @@ case ${CIRCLE_NODE_INDEX} in
   0)
     docker run --rm=false -it -e FSL_COURSE_DATA="/data/examples/nipype-fsl_course_data" -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_pytests.sh && \
     docker run --rm=false -it -e FSL_COURSE_DATA="/data/examples/nipype-fsl_course_data" -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py27 /usr/bin/run_pytests.sh && \
-    docker run --rm=false -it -v $WORKDIR:/work -w /src/nipype/doc nipype/nipype:py36 /usr/bin/run_builddocs.sh && \
+    docker run --rm=false -it -v $WORKDIR:/work -w /src/nipype/doc --entrypoint=/usr/bin/run_builddocs.sh nipype/nipype:py36 /usr/bin/run_builddocs.sh && \
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh test_spm Linear /data/examples/ workflow3d && \
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh test_spm Linear /data/examples/ workflow4d
+    exitcode=$?
     ;;
   1)
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_spm_dartel Linear /data/examples/ level1 && \
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_spm_dartel Linear /data/examples/ l2pipeline
+    exitcode=$?
     ;;
   2)
     docker run --rm=false -it -e NIPYPE_NUMBER_OF_CPUS=4 -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py27 /usr/bin/run_examples.sh fmri_spm_nested MultiProc /data/examples/ level1 && \
     docker run --rm=false -it -e NIPYPE_NUMBER_OF_CPUS=4 -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_spm_nested MultiProc /data/examples/ l2pipeline
+    exitcode=$?
     ;;
   3)
     docker run --rm=false -it -e NIPYPE_NUMBER_OF_CPUS=4 -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_spm_nested MultiProc /data/examples/ level1 && \
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_fsl_feeds Linear /data/examples/ l1pipeline && \
     docker run --rm=false -it -v $HOME/examples:/data/examples:ro -v $WORKDIR:/work -w /work nipype/nipype:py36 /usr/bin/run_examples.sh fmri_fsl_reuse Linear /data/examples/ level1_workflow
+    exitcode=$?
     ;;
 esac
 
 cp ${WORKDIR}/tests/*.xml ${CIRCLE_TEST_REPORTS}/tests/
+
+# Exit with error if any of the tests failed
+if [ "$exitcode" != "0" ]; then exit 1; fi
 codecov -f "coverage*.xml" -s "${WORKDIR}/tests/" -R "${HOME}/nipype/" -F unittests -e CIRCLE_NODE_INDEX
 codecov -f "smoketest*.xml" -s "${WORKDIR}/tests/" -R "${HOME}/nipype/" -F smoketests -e CIRCLE_NODE_INDEX
+

CHANGES

@@ -1,6 +1,7 @@
 Upcoming Release
 =====================
 
+* FIX: Ensure build fails in Circle when tests fail (https://github.com/nipy/nipype/pull/1981)
 * ENH: Add interface to antsAffineInitializer (https://github.com/nipy/nipype/pull/1980)
 * ENH: AFNI motion parameter support for FrameWiseDisplacement (https://github.com/nipy/nipype/pull/1840)
 * ENH: Add ANTs KellyKapowski interface (https://github.com/nipy/nipype/pull/1845)

docker/files/run_pytests.sh

@@ -40,4 +40,6 @@ fi
 # Collect crashfiles
 find ${WORKDIR} -name "crash-*" -maxdepth 1 -exec mv {} ${WORKDIR}/crashfiles/ \;
 
+echo "Unit tests finished with exit code ${exit_code}"
 exit ${exit_code}
+

nipype/algorithms/confounds.py

@@ -330,7 +330,7 @@ class CompCorOutputSpec(TraitedSpec):
         desc='text file containing the noise components')
 
 class CompCor(BaseInterface):
-    '''
+    """
     Interface with core CompCor computation, used in aCompCor and tCompCor
 
     Example
@@ -342,7 +342,8 @@ class CompCor(BaseInterface):
     >>> ccinterface.inputs.num_components = 1
     >>> ccinterface.inputs.use_regress_poly = True
     >>> ccinterface.inputs.regress_poly_degree = 2
-    '''
+    
+    """
     input_spec = CompCorInputSpec
     output_spec = CompCorOutputSpec
     references_ = [{'entry': BibTeX("@article{compcor_2007,"
@@ -465,8 +466,11 @@ def _make_headers(self, num_col):
 
 
 class ACompCor(CompCor):
-    ''' Anatomical compcor; for input/output, see CompCor.
-    If the mask provided is an anatomical mask, CompCor == ACompCor '''
+    """
+    Anatomical compcor: for inputs and outputs, see CompCor.
+    When the mask provided is an anatomical mask, then CompCor
+    is equivalent to ACompCor.
+    """
 
     def __init__(self, *args, **kwargs):
         ''' exactly the same as compcor except the header '''
@@ -492,7 +496,7 @@ class TCompCorOutputSpec(CompCorInputSpec):
                          desc="voxels excedding the variance threshold"))
 
 class TCompCor(CompCor):
-    '''
+    """
     Interface for tCompCor. Computes a ROI mask based on variance of voxels.
 
     Example
@@ -505,7 +509,8 @@ class TCompCor(CompCor):
     >>> ccinterface.inputs.use_regress_poly = True
     >>> ccinterface.inputs.regress_poly_degree = 2
     >>> ccinterface.inputs.percentile_threshold = .03
-    '''
+    
+    """
 
     input_spec = TCompCorInputSpec
     output_spec = TCompCorOutputSpec
@@ -634,7 +639,8 @@ class TSNROutputSpec(TraitedSpec):
 
 
 class TSNR(BaseInterface):
-    """Computes the time-course SNR for a time series
+    """
+    Computes the time-course SNR for a time series
 
     Typically you want to run this on a realigned time-series.
 
@@ -719,80 +725,6 @@ def _run_interface(self, runtime):
     def _list_outputs(self):
         return self._results
 
-def is_outlier(points, thresh=3.5):
-    """
-    Returns a boolean array with True if points are outliers and False
-    otherwise.
-
-    Parameters:
-    -----------
-        points : An numobservations by numdimensions array of observations
-        thresh : The modified z-score to use as a threshold. Observations with
-            a modified z-score (based on the median absolute deviation) greater
-            than this value will be classified as outliers.
-
-    Returns:
-    --------
-        mask : A numobservations-length boolean array.
-
-    References:
-    ----------
-        Boris Iglewicz and David Hoaglin (1993), "Volume 16: How to Detect and
-        Handle Outliers", The ASQC Basic References in Quality Control:
-        Statistical Techniques, Edward F. Mykytka, Ph.D., Editor.
-    """
-    if len(points.shape) == 1:
-        points = points[:, None]
-    median = np.median(points, axis=0)
-    diff = np.sum((points - median) ** 2, axis=-1)
-    diff = np.sqrt(diff)
-    med_abs_deviation = np.median(diff)
-
-    modified_z_score = 0.6745 * diff / med_abs_deviation
-
-    timepoints_to_discard = 0
-    for i in range(len(modified_z_score)):
-        if modified_z_score[i] <= thresh:
-            break
-        else:
-            timepoints_to_discard += 1
-
-    return timepoints_to_discard
-
-
-def regress_poly(degree, data, remove_mean=True, axis=-1):
-    ''' returns data with degree polynomial regressed out.
-    Be default it is calculated along the last axis (usu. time).
-    If remove_mean is True (default), the data is demeaned (i.e. degree 0).
-    If remove_mean is false, the data is not.
-    '''
-    IFLOG.debug('Performing polynomial regression on data of shape ' + str(data.shape))
-
-    datashape = data.shape
-    timepoints = datashape[axis]
-
-    # Rearrange all voxel-wise time-series in rows
-    data = data.reshape((-1, timepoints))
-
-    # Generate design matrix
-    X = np.ones((timepoints, 1)) # quick way to calc degree 0
-    for i in range(degree):
-        polynomial_func = Legendre.basis(i + 1)
-        value_array = np.linspace(-1, 1, timepoints)
-        X = np.hstack((X, polynomial_func(value_array)[:, np.newaxis]))
-
-    # Calculate coefficients
-    betas = np.linalg.pinv(X).dot(data.T)
-
-    # Estimation
-    if remove_mean:
-        datahat = X.dot(betas).T
-    else: # disregard the first layer of X, which is degree 0
-        datahat = X[:, 1:].dot(betas[1:, ...]).T
-    regressed_data = data - datahat
-
-    # Back to original shape
-    return regressed_data.reshape(datashape)
 
 def compute_dvars(in_file, in_mask, remove_zerovariance=False,
                   intensity_normalization=1000):
@@ -921,3 +853,78 @@ def plot_confound(tseries, figsize, name, units=None,
     ax.set_ylim(ylim)
     ax.set_yticklabels([])
     return fig
+
+def is_outlier(points, thresh=3.5):
+    """
+    Returns a boolean array with True if points are outliers and False
+    otherwise.
+
+    :param nparray points: an numobservations by numdimensions numpy array of observations
+    :param float thresh: the modified z-score to use as a threshold. Observations with
+        a modified z-score (based on the median absolute deviation) greater
+        than this value will be classified as outliers.
+
+    :return: A bolean mask, of size numobservations-length array.
+
+    .. note:: References
+
+        Boris Iglewicz and David Hoaglin (1993), "Volume 16: How to Detect and
+        Handle Outliers", The ASQC Basic References in Quality Control:
+        Statistical Techniques, Edward F. Mykytka, Ph.D., Editor.
+
+    """
+    if len(points.shape) == 1:
+        points = points[:, None]
+    median = np.median(points, axis=0)
+    diff = np.sum((points - median) ** 2, axis=-1)
+    diff = np.sqrt(diff)
+    med_abs_deviation = np.median(diff)
+
+    modified_z_score = 0.6745 * diff / med_abs_deviation
+
+    timepoints_to_discard = 0
+    for i in range(len(modified_z_score)):
+        if modified_z_score[i] <= thresh:
+            break
+        else:
+            timepoints_to_discard += 1
+
+    return timepoints_to_discard
+
+
+def regress_poly(degree, data, remove_mean=True, axis=-1):
+    """
+    Returns data with degree polynomial regressed out.
+
+    :param bool remove_mean: whether or not demean data (i.e. degree 0),
+    :param int axis: numpy array axes along which regression is performed
+
+    """
+    IFLOG.debug('Performing polynomial regression on data of shape ' + str(data.shape))
+
+    datashape = data.shape
+    timepoints = datashape[axis]
+
+    # Rearrange all voxel-wise time-series in rows
+    data = data.reshape((-1, timepoints))
+
+    # Generate design matrix
+    X = np.ones((timepoints, 1)) # quick way to calc degree 0
+    for i in range(degree):
+        polynomial_func = Legendre.basis(i + 1)
+        value_array = np.linspace(-1, 1, timepoints)
+        X = np.hstack((X, polynomial_func(value_array)[:, np.newaxis]))
+
+    # Calculate coefficients
+    betas = np.linalg.pinv(X).dot(data.T)
+
+    # Estimation
+    if remove_mean:
+        datahat = X.dot(betas).T
+    else: # disregard the first layer of X, which is degree 0
+        datahat = X[:, 1:].dot(betas[1:, ...]).T
+    regressed_data = data - datahat
+
+    # Back to original shape
+    return regressed_data.reshape(datashape)
+

nipype/interfaces/afni/__init__.py

@@ -15,7 +15,7 @@
                          Maskave, Means, OutlierCount,
                          QualityIndex, ROIStats, Retroicor,
                          Seg, SkullStrip, TCorr1D, TCorrMap, TCorrelate,
-                         TShift, Volreg, Warp)
+                         TShift, Volreg, Warp, QwarpPlusMinus)
 from .svm import (SVMTest, SVMTrain)
 from .utils import (AFNItoNIFTI, Autobox, BrickStat, Calc, Copy,
                     Eval, FWHMx,

nipype/interfaces/afni/preprocess.py

@@ -2347,3 +2347,104 @@ class Warp(AFNICommand):
     _cmd = '3dWarp'
     input_spec = WarpInputSpec
     output_spec = AFNICommandOutputSpec
+
+
+class QwarpPlusMinusInputSpec(CommandLineInputSpec):
+    source_file = File(
+        desc='Source image (opposite phase encoding direction than base image).',
+        argstr='-source %s',
+        mandatory=True,
+        exists=True,
+        copyfile=False)
+    base_file = File(
+        desc='Base image (opposite phase encoding direction than source image).',
+        argstr='-base %s',
+        mandatory=True,
+        exists=True,
+        copyfile=False)
+    pblur = traits.List(traits.Float(),
+                        desc='The fraction of the patch size that'
+                             'is used for the progressive blur by providing a '
+                             'value between 0 and 0.25.  If you provide TWO '
+                             'values, the first fraction is used for '
+                             'progressively blurring the base image and the '
+                             'second for the source image.',
+                        argstr='-pblur %s',
+                        minlen=1,
+                        maxlen=2)
+    blur = traits.List(traits.Float(),
+                       desc="Gaussian blur the input images by (FWHM) voxels "
+                            "before doing the alignment (the output dataset "
+                            "will not be blurred). The default is 2.345 (for "
+                            "no good reason). Optionally, you can provide 2 "
+                            "values, and then the first one is applied to the "
+                            "base volume, the second to the source volume. A "
+                            "negative blur radius means to use 3D median "
+                            "filtering, rather than Gaussian blurring.  This "
+                            "type of filtering will better preserve edges, "
+                            "which can be important in alignment.",
+                       argstr='-blur %s',
+                       minlen=1,
+                       maxlen=2)
+    noweight = traits.Bool(
+        desc='If you want a binary weight (the old default), use this option.'
+             'That is, each voxel in the base volume automask will be'
+             'weighted the same in the computation of the cost functional.',
+        argstr='-noweight')
+    minpatch = traits.Int(
+        desc="Set the minimum patch size for warp searching to 'mm' voxels.",
+        argstr='-minpatch %d')
+    nopadWARP = traits.Bool(
+        desc='If for some reason you require the warp volume to'
+             'match the base volume, then use this option to have the output'
+             'WARP dataset(s) truncated.',
+        argstr='-nopadWARP')
+
+
+class QwarpPlusMinusOutputSpec(TraitedSpec):
+    warped_source = File(
+        desc='Undistorted source file.',
+        exists=True)
+    warped_base = File(
+        desc='Undistorted base file.',
+        exists=True)
+    source_warp = File(
+        desc="Field suceptibility correction warp (in 'mm') for source image.",
+        exists=True)
+    base_warp = File(
+        desc="Field suceptibility correction warp (in 'mm') for base image.",
+        exists=True)
+
+
+class QwarpPlusMinus(CommandLine):
+    """A version of 3dQwarp for performing field susceptibility correction 
+    using two images with opposing phase encoding directions.
+
+    For complete details, see the `3dQwarp Documentation.
+    <https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dQwarp.html>`_
+
+    Examples
+    ========
+
+    >>> from nipype.interfaces import afni
+    >>> qwarp = afni.QwarpPlusMinus()
+    >>> qwarp.inputs.source_file = 'sub-01_dir-LR_epi.nii.gz'
+    >>> qwarp.inputs.nopadWARP = True
+    >>> qwarp.inputs.base_file = 'sub-01_dir-RL_epi.nii.gz'
+    >>> qwarp.cmdline  # doctest: +ALLOW_UNICODE
+    '3dQwarp -prefix Qwarp.nii.gz -plusminus -base sub-01_dir-RL_epi.nii.gz -nopadWARP -source sub-01_dir-LR_epi.nii.gz'
+    >>> res = warp.run()  # doctest: +SKIP
+    
+    """
+    _cmd = '3dQwarp -prefix Qwarp.nii.gz -plusminus'
+    input_spec = QwarpPlusMinusInputSpec
+    output_spec = QwarpPlusMinusOutputSpec
+
+    def _list_outputs(self):
+        outputs = self.output_spec().get()
+        outputs['warped_source'] = os.path.abspath("Qwarp_PLUS.nii.gz")
+        outputs['warped_base'] = os.path.abspath("Qwarp_MINUS.nii.gz")
+        outputs['source_warp'] = os.path.abspath("Qwarp_PLUS_WARP.nii.gz")
+        outputs['base_warp'] = os.path.abspath("Qwarp_MINUS_WARP.nii.gz")
+
+        return outputs

nipype/testing/data/sub-01_dir-LR_epi.nii.gz

@@ -6,4 +6,8 @@ def test_nipype_info():
         get_info()
     except Exception as e:
         exception_not_raised = False
-    assert exception_not_raised
+    assert exception_not_raised
+
+# def test_fail_always():
+#     assert False
+