Sort out terminal_output

CHANGES

@@ -1,10 +1,11 @@
 Upcoming release
 ================
 
+* ENH: Improve terminal_output feature (https://github.com/nipy/nipype/pull/2209)
+* ENH: Simple interface to FSL std2imgcoords (https://github.com/nipy/nipype/pull/2209, prev #1398)
 * ENH: Centralize virtual/physical $DISPLAYs (https://github.com/nipy/nipype/pull/#2203)
 * ENH: New ResourceMonitor - replaces resource profiler (https://github.com/nipy/nipype/pull/#2200)
 
-
 0.13.1 (May 20, 2017)
 =====================
 

doc/devel/interface_specs.rst

@@ -159,6 +159,70 @@ generated depending on inputs, by the tool.  OutputSpecs inherit from
 ``interfaces.base.TraitedSpec`` directly.
 
 
+Controlling outputs to terminal
+-------------------------------
+
+It is very likely that the software wrapped within the interface writes
+to the standard output or the standard error of the terminal.
+Interfaces provide a means to access and retrieve these outputs, by
+using the ``terminal_output`` attribute: ::
+
+  import nipype.interfaces.fsl as fsl
+  mybet = fsl.BET(from_file='bet-settings.json')
+  mybet.terminal_output = 'file_split'
+
+In the example, the ``terminal_output = 'file_split'`` will redirect the
+standard output and the standard error to split files (called
+``stdout.nipype`` and ``stderr.nipype`` respectively).
+The possible values for ``terminal_output`` are:
+
+*file*
+    Redirects both standard output and standard error to the same file
+    called ``output.nipype``.
+    Messages from both streams will be overlapped as they arrive to
+    the file.
+
+*file_split*
+    Redirects the output streams separately, to ``stdout.nipype``
+    and ``stderr.nipype`` respectively, as described in the example.
+
+*file_stdout*
+    Only the standard output will be redirected to ``stdout.nipype``
+    and the standard error will be discarded.
+
+*file_stderr*
+    Only the standard error will be redirected to ``stderr.nipype``
+    and the standard output will be discarded.
+
+*stream*
+    Both output streams are redirected to the current logger printing
+    their messages interleaved and immediately to the terminal.
+
+*allatonce*
+    Both output streams will be forwarded to a buffer and stored
+    separately in the `runtime` object that the `run()` method returns.
+    No files are written nor streams printed out to terminal.
+
+*none*
+    Both outputs are discarded
+
+In all cases, except for the ``'none'`` setting of ``terminal_output``,
+the ``run()`` method will return a "runtime" object that will contain
+the streams in the corresponding properties (``runtime.stdout``
+for the standard output, ``runtime.stderr`` for the standard error, and
+``runtime.merged`` for both when streams are mixed, eg. when using the
+*file* option). ::
+
+  import nipype.interfaces.fsl as fsl
+  mybet = fsl.BET(from_file='bet-settings.json')
+  mybet.terminal_output = 'file_split'
+  ...
+  result = mybet.run()
+  result.runtime.stdout
+  ' ... captured standard output ...'
+
+
+
 Traited Attributes
 ------------------
 

doc/users/interface_tutorial.rst

@@ -10,7 +10,7 @@ Specifying input settings
 The nipype interface modules provide a Python interface to external
 packages like FSL_ and SPM_.  Within the module are a series of Python
 classes which wrap specific package functionality.  For example, in
-the fsl module, the class :class:`nipype.interfaces.fsl.Bet` wraps the
+the fsl module, the class :class:`nipype.interfaces.fsl.BET` wraps the
 ``bet`` command-line tool.  Using the command-line tool, one would
 specify input settings using flags like ``-o``, ``-m``, ``-f <f>``, etc...
 However, in nipype, options are assigned to Python attributes and can

doc/users/saving_workflows.rst

@@ -82,20 +82,20 @@ This will create a file "outputtestsave.py" with the following content:
 	bet2.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	bet2.inputs.ignore_exception = False
 	bet2.inputs.output_type = 'NIFTI_GZ'
-	bet2.inputs.terminal_output = 'stream'
+	bet2.terminal_output = 'stream'
 	# Node: testsave.bet
 	bet = Node(BET(), name="bet")
 	bet.iterables = ('frac', [0.3, 0.4])
 	bet.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	bet.inputs.ignore_exception = False
 	bet.inputs.output_type = 'NIFTI_GZ'
-	bet.inputs.terminal_output = 'stream'
+	bet.terminal_output = 'stream'
 	# Node: testsave.maths
 	maths = Node(ImageMaths(), name="maths")
 	maths.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	maths.inputs.ignore_exception = False
 	maths.inputs.output_type = 'NIFTI_GZ'
-	maths.inputs.terminal_output = 'stream'
+	maths.terminal_output = 'stream'
 	testsave.connect(bet2, ('mask_file', func), maths, "in_file2")
 	testsave.connect(bet, "mask_file", maths, "in_file")
 	testsave.connect(testfunc, "output", maths, "op_string")

examples/fmri_ants_openfmri.py

@@ -218,7 +218,7 @@ def create_reg_workflow(name='registration'):
     warpmean.inputs.input_image_type = 0
     warpmean.inputs.interpolation = 'Linear'
     warpmean.inputs.invert_transform_flags = [False, False]
-    warpmean.inputs.terminal_output = 'file'
+    warpmean.terminal_output = 'file'
 
     register.connect(inputnode, 'target_image_brain', warpmean, 'reference_image')
     register.connect(inputnode, 'mean_image', warpmean, 'input_image')
@@ -234,7 +234,7 @@ def create_reg_workflow(name='registration'):
     warpall.inputs.input_image_type = 0
     warpall.inputs.interpolation = 'Linear'
     warpall.inputs.invert_transform_flags = [False, False]
-    warpall.inputs.terminal_output = 'file'
+    warpall.terminal_output = 'file'
 
     register.connect(inputnode, 'target_image_brain', warpall, 'reference_image')
     register.connect(inputnode, 'source_files', warpall, 'input_image')
@@ -428,7 +428,7 @@ def create_fs_reg_workflow(name='registration'):
     warpmean.inputs.input_image_type = 0
     warpmean.inputs.interpolation = 'Linear'
     warpmean.inputs.invert_transform_flags = [False, False]
-    warpmean.inputs.terminal_output = 'file'
+    warpmean.terminal_output = 'file'
     warpmean.inputs.args = '--float'
     # warpmean.inputs.num_threads = 4
     # warpmean.plugin_args = {'sbatch_args': '--mem=4G -c 4'}
@@ -443,7 +443,7 @@ def create_fs_reg_workflow(name='registration'):
     warpall.inputs.input_image_type = 0
     warpall.inputs.interpolation = 'Linear'
     warpall.inputs.invert_transform_flags = [False, False]
-    warpall.inputs.terminal_output = 'file'
+    warpall.terminal_output = 'file'
     warpall.inputs.args = '--float'
     warpall.inputs.num_threads = 2
     warpall.plugin_args = {'sbatch_args': '--mem=6G -c 2'}

examples/rsfmri_vol_surface_preprocessing.py

@@ -547,7 +547,7 @@ def create_reg_workflow(name='registration'):
     warpmean.inputs.input_image_type = 3
     warpmean.inputs.interpolation = 'Linear'
     warpmean.inputs.invert_transform_flags = [False, False]
-    warpmean.inputs.terminal_output = 'file'
+    warpmean.terminal_output = 'file'
     warpmean.inputs.args = '--float'
     warpmean.inputs.num_threads = 4
 
@@ -767,7 +767,7 @@ def merge_files(in1, in2):
     warpall.inputs.input_image_type = 3
     warpall.inputs.interpolation = 'Linear'
     warpall.inputs.invert_transform_flags = [False, False]
-    warpall.inputs.terminal_output = 'file'
+    warpall.terminal_output = 'file'
     warpall.inputs.reference_image = target_file
     warpall.inputs.args = '--float'
     warpall.inputs.num_threads = 1

examples/rsfmri_vol_surface_preprocessing_nipy.py

@@ -482,7 +482,7 @@ def create_reg_workflow(name='registration'):
     warpmean.inputs.input_image_type = 3
     warpmean.inputs.interpolation = 'Linear'
     warpmean.inputs.invert_transform_flags = [False, False]
-    warpmean.inputs.terminal_output = 'file'
+    warpmean.terminal_output = 'file'
     warpmean.inputs.args = '--float'
     warpmean.inputs.num_threads = 4
     warpmean.plugin_args = {'sbatch_args': '-c%d' % 4}
@@ -704,7 +704,7 @@ def merge_files(in1, in2):
     warpall.inputs.input_image_type = 3
     warpall.inputs.interpolation = 'Linear'
     warpall.inputs.invert_transform_flags = [False, False]
-    warpall.inputs.terminal_output = 'file'
+    warpall.terminal_output = 'file'
     warpall.inputs.reference_image = target_file
     warpall.inputs.args = '--float'
     warpall.inputs.num_threads = 2

nipype/interfaces/afni/preprocess.py

@@ -1676,13 +1676,13 @@ class OutlierCountInputSpec(CommandLineInputSpec):
         False,
         usedefault=True,
         argstr='-autoclip',
-        xor=['in_file'],
+        xor=['mask'],
         desc='clip off small voxels')
     automask = traits.Bool(
         False,
         usedefault=True,
         argstr='-automask',
-        xor=['in_file'],
+        xor=['mask'],
         desc='clip off small voxels')
     fraction = traits.Bool(
         False,
@@ -1718,28 +1718,19 @@ class OutlierCountInputSpec(CommandLineInputSpec):
     out_file = File(
         name_template='%s_outliers',
         name_source=['in_file'],
-        argstr='> %s',
         keep_extension=False,
-        position=-1,
         desc='capture standard output')
 
 
 class OutlierCountOutputSpec(TraitedSpec):
-    out_outliers = File(
-        exists=True,
-        desc='output image file name')
-    out_file = File(
-        name_template='%s_tqual',
-        name_source=['in_file'],
-        argstr='> %s',
-        keep_extension=False,
-        position=-1,
-        desc='capture standard output')
+    out_outliers = File(exists=True,
+                        desc='output image file name')
+    out_file = File(desc='capture standard output')
 
 
 class OutlierCount(CommandLine):
-    """Calculates number of 'outliers' a 3D+time dataset, at each
-    time point, and writes the results to stdout.
+    """Calculates number of 'outliers' at each time point of a
+    a 3D+time dataset.
 
     For complete details, see the `3dToutcount Documentation
     <https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dToutcount.html>`_
@@ -1751,28 +1742,42 @@ class OutlierCount(CommandLine):
     >>> toutcount = afni.OutlierCount()
     >>> toutcount.inputs.in_file = 'functional.nii'
     >>> toutcount.cmdline  # doctest: +ELLIPSIS +ALLOW_UNICODE
-    '3dToutcount functional.nii > functional_outliers'
+    '3dToutcount functional.nii'
     >>> res = toutcount.run()  # doctest: +SKIP
 
     """
 
     _cmd = '3dToutcount'
     input_spec = OutlierCountInputSpec
     output_spec = OutlierCountOutputSpec
+    _terminal_output = 'file_split'
 
     def _parse_inputs(self, skip=None):
         if skip is None:
             skip = []
 
+        # This is not strictly an input, but needs be
+        # set before run() is called.
+        if self.terminal_output == 'none':
+            self.terminal_output = 'file_split'
+
         if not self.inputs.save_outliers:
             skip += ['outliers_file']
         return super(OutlierCount, self)._parse_inputs(skip)
 
+    def _run_interface(self, runtime):
+        runtime = super(OutlierCount, self)._run_interface(runtime)
+
+        # Read from runtime.stdout or runtime.merged
+        with open(op.abspath(self.inputs.out_file), 'w') as outfh:
+            outfh.write(runtime.stdout or runtime.merged)
+        return runtime
+
     def _list_outputs(self):
         outputs = self.output_spec().get()
+        outputs['out_file'] = op.abspath(self.inputs.out_file)
         if self.inputs.save_outliers:
             outputs['out_outliers'] = op.abspath(self.inputs.outliers_file)
-        outputs['out_file'] = op.abspath(self.inputs.out_file)
         return outputs
 
 
@@ -1880,13 +1885,10 @@ class ROIStatsInputSpec(CommandLineInputSpec):
         desc='execute quietly',
         argstr='-quiet',
         position=1)
-    terminal_output = traits.Enum(
-        'allatonce',
+    terminal_output = traits.Enum('allatonce', deprecated='1.0.0',
         desc='Control terminal output:`allatonce` - waits till command is '
              'finished to display output',
-        nohash=True,
-        mandatory=True,
-        usedefault=True)
+        nohash=True)
 
 
 class ROIStatsOutputSpec(TraitedSpec):
@@ -1915,6 +1917,7 @@ class ROIStats(AFNICommandBase):
 
     """
     _cmd = '3dROIstats'
+    _terminal_output = 'allatonce'
     input_spec = ROIStatsInputSpec
     output_spec = ROIStatsOutputSpec
 

nipype/interfaces/afni/tests/test_auto_ABoverlap.py

@@ -24,13 +24,17 @@ def test_ABoverlap_inputs():
     ),
     no_automask=dict(argstr='-no_automask',
     ),
+    num_threads=dict(nohash=True,
+    usedefault=True,
+    ),
     out_file=dict(argstr=' |& tee %s',
     position=-1,
     ),
     outputtype=dict(),
     quiet=dict(argstr='-quiet',
     ),
-    terminal_output=dict(nohash=True,
+    terminal_output=dict(deprecated='1.0.0',
+    nohash=True,
     ),
     verb=dict(argstr='-verb',
     ),

nipype/interfaces/afni/tests/test_auto_AFNICommand.py

@@ -12,12 +12,16 @@ def test_AFNICommand_inputs():
     ignore_exception=dict(nohash=True,
     usedefault=True,
     ),
+    num_threads=dict(nohash=True,
+    usedefault=True,
+    ),
     out_file=dict(argstr='-prefix %s',
     name_source=['in_file'],
     name_template='%s_afni',
     ),
     outputtype=dict(),
-    terminal_output=dict(nohash=True,
+    terminal_output=dict(deprecated='1.0.0',
+    nohash=True,
     ),
     )
     inputs = AFNICommand.input_spec()

nipype/interfaces/afni/tests/test_auto_AFNICommandBase.py

@@ -12,7 +12,8 @@ def test_AFNICommandBase_inputs():
     ignore_exception=dict(nohash=True,
     usedefault=True,
     ),
-    terminal_output=dict(nohash=True,
+    terminal_output=dict(deprecated='1.0.0',
+    nohash=True,
     ),
     )
     inputs = AFNICommandBase.input_spec()

nipype/interfaces/afni/tests/test_auto_AFNIPythonCommand.py

@@ -12,12 +12,16 @@ def test_AFNIPythonCommand_inputs():
     ignore_exception=dict(nohash=True,
     usedefault=True,
     ),
+    num_threads=dict(nohash=True,
+    usedefault=True,
+    ),
     out_file=dict(argstr='-prefix %s',
     name_source=['in_file'],
     name_template='%s_afni',
     ),
     outputtype=dict(),
-    terminal_output=dict(nohash=True,
+    terminal_output=dict(deprecated='1.0.0',
+    nohash=True,
     ),
     )
     inputs = AFNIPythonCommand.input_spec()

nipype/interfaces/afni/tests/test_auto_AFNItoNIFTI.py

@@ -22,6 +22,9 @@ def test_AFNItoNIFTI_inputs():
     newid=dict(argstr='-newid',
     xor=['oldid'],
     ),
+    num_threads=dict(nohash=True,
+    usedefault=True,
+    ),
     oldid=dict(argstr='-oldid',
     xor=['newid'],
     ),
@@ -33,7 +36,8 @@ def test_AFNItoNIFTI_inputs():
     outputtype=dict(),
     pure=dict(argstr='-pure',
     ),
-    terminal_output=dict(nohash=True,
+    terminal_output=dict(deprecated='1.0.0',
+    nohash=True,
     ),
     )
     inputs = AFNItoNIFTI.input_spec()