DOC: Improve documentation to delineate all options

Author: effigies

nipype/interfaces/afni/preprocess.py

@@ -2637,31 +2637,58 @@ class TShift(AFNICommand):
     Examples
     ========
 
+    Slice timing details may be specified explicitly via the ``slice_timing``
+    input:
+
     >>> from nipype.interfaces import afni
+    >>> TR = 2.5
     >>> tshift = afni.TShift()
     >>> tshift.inputs.in_file = 'functional.nii'
-    >>> tshift.inputs.tpattern = 'alt+z'
     >>> tshift.inputs.tzero = 0.0
+    >>> tshift.inputs.tr = '%.1fs' % TR
+    >>> tshift.inputs.slice_timing = list(np.arange(40) / TR)
     >>> tshift.cmdline
-    '3dTshift -prefix functional_tshift -tpattern alt+z -tzero 0.0 functional.nii'
-    >>> res = tshift.run()  # doctest: +SKIP
+    '3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'
 
-    Slice timings may be explicitly specified:
+    This method creates a ``slice_timing.1D`` file to be passed to ``3dTshift``.
+    A pre-existing slice-timing file may be used in the same way:
 
-    >>> TR = 2.5
     >>> tshift = afni.TShift()
     >>> tshift.inputs.in_file = 'functional.nii'
     >>> tshift.inputs.tzero = 0.0
     >>> tshift.inputs.tr = '%.1fs' % TR
-    >>> tshift.inputs.slice_timing = list(np.arange(40) / TR)
+    >>> tshift.inputs.slice_timing = 'slice_timing.1D'
     >>> tshift.cmdline
     '3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'
 
-    This will create the ``slice_timing.1D`` file in the working directory.
-    You may wish to remove this after running:
+    Alternatively, pre-specified slice timing patterns may be specified with the
+    ``tpattern`` input.
+    For example, to specify an alternating, ascending slice timing pattern:
 
-    >>> os.unlink('slice_timing.1D')
+    >>> tshift = afni.TShift()
+    >>> tshift.inputs.in_file = 'functional.nii'
+    >>> tshift.inputs.tzero = 0.0
+    >>> tshift.inputs.tr = '%.1fs' % TR
+    >>> tshift.inputs.tpattern = 'alt+z'
+    >>> tshift.cmdline
+    '3dTshift -prefix functional_tshift -tpattern alt+z -TR 2.5s -tzero 0.0 functional.nii'
+
+    For backwards compatibility, ``tpattern`` may also take filenames prefixed
+    with ``@``.
+    However, in this case, filenames are not validated, so this usage will be
+    deprecated in future versions of Nipype.
+
+    >>> tshift = afni.TShift()
+    >>> tshift.inputs.in_file = 'functional.nii'
+    >>> tshift.inputs.tzero = 0.0
+    >>> tshift.inputs.tr = '%.1fs' % TR
+    >>> tshift.inputs.tpattern = '@slice_timing.1D'
+    >>> tshift.cmdline
+    '3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'
+
+    In any configuration, the interface may be run as usual:
 
+    >>> res = tshift.run()  # doctest: +SKIP
     """
     _cmd = '3dTshift'
     input_spec = TShiftInputSpec

nipype/testing/data/slice_timing.1D

@@ -0,0 +1 @@
+0.0	0.4	0.8	1.2	1.6	2.0	2.4	2.8	3.2	3.6	4.0	4.4	4.8	5.2	5.6	6.0	6.4	6.8	7.2	7.6	8.0	8.4	8.8	9.2	9.6	10.0	10.4	10.8	11.2	11.6	12.0	12.4	12.8	13.2	13.6	14.0	14.4	14.8	15.2	15.6