Home · Quickstart · Documentation · About · Nipy

# interfaces.base.core

## BaseInterface

Link to code

Implements common interface functionality.

### Implements

- Initializes inputs/outputs from input_spec/output_spec
- Provides help based on input_spec and output_spec
- Checks for mandatory inputs before running an interface
- Runs an interface and returns results
- Determines which inputs should be copied or linked to cwd

This class does not implement aggregate_outputs, input_spec or output_spec. These should be defined by derived classes.

This class cannot be instantiated.

### Relevant Interface attributes

`input_spec` points to the traited class for the inputs `output_spec` points to the traited class for the outputs `_redirect_x` should be set to `True` when the interface requires

> connecting to a `$DISPLAY` (default is `False`).

`resource_monitor` if `False` prevents resource-monitoring this
  interface, if `True` monitoring will be enabled IFF the general Nipype config is set on (`resource_monitor = true`).

Inputs:

    [Mandatory]

    [Optional]
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run

Outputs:

    None

## CommandLine

Link to code

Wraps command None

Implements functionality to interact with command line programs class must be instantiated with a command argument

### Parameters

command : string
  define base immutable command you wish to run
args : string, optional
  optional arguments passed to base command

### Examples

    >>> import pprint
    >>> from nipype.interfaces.base import CommandLine
    >>> cli = CommandLine(command='ls', environ={'DISPLAY': ':1'})
    >>> cli.inputs.args = '-al'
    >>> cli.cmdline
    'ls -al'

# Use get_traitsfree() to check all inputs set >>> pprint.pprint(cli.inputs.get_traitsfree()) # doctest: {‘args’: ‘-al’,

> ‘environ’: {‘DISPLAY’: ‘:1’}, ‘ignore_exception’: False}

    >>> cli.inputs.get_hashval()[0][0]
    ('args', '-al')
    >>> cli.inputs.get_hashval()[1]
    '11c37f97649cd61627f4afe5136af8c0'

Inputs:

    [Mandatory]

    [Optional]
    args: (a unicode string)
            Additional parameters to the command
            flag: %s
    environ: (a dictionary with keys which are a newbytes or None or a
             newstr or None and with values which are a newbytes or None or a
             newstr or None, nipype default value: {})
            Environment variables
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run
    terminal_output: (u'stream' or u'allatonce' or u'file' or u'none')
            Control terminal output: `stream` - displays to terminal immediately
            (default), `allatonce` - waits till command is finished to display
            output, `file` - writes output to file, `none` - output is ignored

Outputs:

    None

## MpiCommandLine

Link to code

Wraps command None

Implements functionality to interact with command line programs that can be run with MPI (i.e. using ‘mpiexec’).

### Examples

    >>> from nipype.interfaces.base import MpiCommandLine
    >>> mpi_cli = MpiCommandLine(command='my_mpi_prog')
    >>> mpi_cli.inputs.args = '-v'
    >>> mpi_cli.cmdline
    'my_mpi_prog -v'

    >>> mpi_cli.inputs.use_mpi = True
    >>> mpi_cli.inputs.n_procs = 8
    >>> mpi_cli.cmdline
    'mpiexec -n 8 my_mpi_prog -v'

Inputs:

    [Mandatory]

    [Optional]
    args: (a unicode string)
            Additional parameters to the command
            flag: %s
    environ: (a dictionary with keys which are a newbytes or None or a
             newstr or None and with values which are a newbytes or None or a
             newstr or None, nipype default value: {})
            Environment variables
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run
    n_procs: (an integer (int or long))
            Num processors to specify to mpiexec. Do not specify if this is
            managed externally (e.g. through SGE)
    terminal_output: (u'stream' or u'allatonce' or u'file' or u'none')
            Control terminal output: `stream` - displays to terminal immediately
            (default), `allatonce` - waits till command is finished to display
            output, `file` - writes output to file, `none` - output is ignored
    use_mpi: (a boolean, nipype default value: False)
            Whether or not to run the command with mpiexec

Outputs:

    None

## SEMLikeCommandLine

Link to code

Wraps command None

In SEM derived interface all outputs have corresponding inputs. However, some SEM commands create outputs that are not defined in the XML. In those cases one has to create a subclass of the autogenerated one and overload the _list_outputs method. _outputs_from_inputs should still be used but only for the reduced (by excluding those that do not have corresponding inputs list of outputs.

Inputs:

    [Mandatory]

    [Optional]
    args: (a unicode string)
            Additional parameters to the command
            flag: %s
    environ: (a dictionary with keys which are a newbytes or None or a
             newstr or None and with values which are a newbytes or None or a
             newstr or None, nipype default value: {})
            Environment variables
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run
    terminal_output: (u'stream' or u'allatonce' or u'file' or u'none')
            Control terminal output: `stream` - displays to terminal immediately
            (default), `allatonce` - waits till command is finished to display
            output, `file` - writes output to file, `none` - output is ignored

Outputs:

    None

## SimpleInterface

Link to code

An interface pattern that allows outputs to be set in a dictionary called `_results` that is automatically interpreted by `_list_outputs()` to find the outputs.

When implementing `_run_interface`, set outputs with:

    self._results[out_name] = out_value

This can be a way to upgrade a `Function` interface to do type checking.

### Examples

    >>> from .specs import TraitedSpec
    >>> tmp = getfixture('tmpdir')
    >>> old = tmp.chdir() # changing to a temporary directory

    >>> def double(x):
    ...    return 2 * x
    ~~~
    >>> class DoubleInputSpec(BaseInterfaceInputSpec):
    ...     x = traits.Float(mandatory=True)
    ~~~
    >>> class DoubleOutputSpec(TraitedSpec):
    ...     doubled = traits.Float()
    ~~~
    >>> class Double(SimpleInterface):
    ...     input_spec = DoubleInputSpec
    ...     output_spec = DoubleOutputSpec
    ~~~
    ...     def _run_interface(self, runtime):
    ...          self._results['doubled'] = double(self.inputs.x)
    ...          return runtime

    >>> dbl = Double()
    >>> dbl.inputs.x = 2
    >>> dbl.run().outputs.doubled
    4.0

    >>> os.chdir(old.strpath)

Inputs:

    [Mandatory]

    [Optional]
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run

Outputs:

    None

## StdOutCommandLine

Link to code

Wraps command None

Inputs:

    [Mandatory]

    [Optional]
    args: (a unicode string)
            Additional parameters to the command
            flag: %s
    environ: (a dictionary with keys which are a newbytes or None or a
             newstr or None and with values which are a newbytes or None or a
             newstr or None, nipype default value: {})
            Environment variables
    ignore_exception: (a boolean, nipype default value: False)
            Print an error message instead of throwing an exception in case the
            interface fails to run
    out_file: (a file name)
            flag: > %s, position: -1
    terminal_output: (u'stream' or u'allatonce' or u'file' or u'none')
            Control terminal output: `stream` - displays to terminal immediately
            (default), `allatonce` - waits till command is finished to display
            output, `file` - writes output to file, `none` - output is ignored

Outputs:

    None

## `run_command()`

Link to code

Run a command, read stdout and stderr, prefix with timestamp.

The returned runtime contains a merged stdout+stderr log with timestamps