Home · Quickstart · User Guide and Examples · Interfaces Index · Developers · About · Nipy

# nipype.interfaces.base.core module

## Nipype interfaces core

Defines the `Interface` API and the body of the most basic interfaces. The I/O specifications corresponding to these base interfaces are found in the `specs` module.

### BaseInterface

Link to code

> Bases: `nipype.interfaces.base.core.Interface`

> Implement common interface functionality.

> - 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.

> nipype.interfaces.base.core.input_spec

>   points to the traited class for the inputs

>   Type

>     `nipype.interfaces.base.specs.TraitedSpec`

> nipype.interfaces.base.core.output_spec

>   points to the traited class for the outputs

>   Type

>     `nipype.interfaces.base.specs.TraitedSpec`

> nipype.interfaces.base.core._redirect_x

>   should be set to `True` when the interface requires connecting to a `$DISPLAY` (default is `False`).

>   Type

>     bool

> nipype.interfaces.base.core.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`).

>   Type

>     bool

> BaseInterface.aggregate_outputs(runtime=None, needed_outputs=None)

>   Collate expected outputs and apply output traits validation.

> BaseInterface.load_inputs_from_json(json_file, overwrite=True)

>   A convenient way to load pre-set inputs from a JSON file.

> BaseInterface.resource_monitor = True
> BaseInterface.run(cwd=None, ignore_exception=None, **inputs)

>   Execute this interface.

>   This interface will not raise an exception if runtime.returncode is non-zero.

>   Parameters

>     - cwd (specify a folder where the interface should be run) –

>     - inputs (allows the interface settings to be updated) –

>   Returns

>     results – A copy of the instance that was executed, provenance information and, if successful, results

>   Return type

>     `nipype.interfaces.base.support.InterfaceResult`

> BaseInterface.save_inputs_to_json(json_file)

>   A convenient way to save current inputs to a JSON file.

> property BaseInterface.version

>   interfaces should implement a version property

### CommandLine

Link to code

> Bases: BaseInterface

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

> param command

>   define base immutable command you wish to run

> type command

>   str

> param args

>   optional arguments passed to base command

> type args

>   str, optional

> 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'}}

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

> argsa unicode string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

> property CommandLine.cmd

>   sets base command, immutable

> property CommandLine.cmdline

>   command plus any arguments (args) validates arguments and generates command line

> CommandLine.raise_exception(runtime)
> classmethod CommandLine.set_default_terminal_output(output_type)

>   Set the default terminal output for CommandLine Interfaces.

>   This method is used to set default terminal output for CommandLine Interfaces. However, setting this will not update the output type for any existing instances. For these, assign the <instance>.terminal_output.

> property CommandLine.terminal_output
> CommandLine.version_from_command(flag='-v', cmd=None)

class nipype.interfaces.base.core.Interface

  Bases: `object`

  This is an abstract definition for Interface objects.

  It provides no functionality. It defines the necessary attributes and methods all Interface objects should have.

  aggregate_outputs(runtime=None, needed_outputs=None)

    Called to populate outputs

  property always_run

    Should the interface be always run even if the inputs were not changed? Only applies to interfaces being run within a workflow context.

  property can_resume

    Defines if the interface can reuse partial results after interruption. Only applies to interfaces being run within a workflow context.

  classmethod help(returnhelp=False)

    Prints class help

  input_spec = None

    The specification of the input, defined by a `HasTraits` class.

  output_spec = None

    The specification of the output, defined by a `HasTraits` class.

  run()

    Execute the command.

  property version

    interfaces should implement a version property

### LibraryBaseInterface

Link to code

> Bases: BaseInterface

> LibraryBaseInterface.imports = ()
> property LibraryBaseInterface.version

>   interfaces should implement a version property

### MpiCommandLine

Link to code

> Bases: CommandLine

> 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'

> argsa unicode string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

> n_procsan integer (int or long)

>   Num processors to specify to mpiexec. Do not specify if this is managed externally (e.g. through SGE).

> use_mpia boolean

>   Whether or not to run the command with mpiexec. (Nipype default value: `False`)

> property MpiCommandLine.cmdline

>   Adds ‘mpiexec’ to begining of command

class nipype.interfaces.base.core.PackageInfo

  Bases: `object`

  static parse_version(raw_info)
  classmethod version()
  version_cmd = None
  version_file = None

### SEMLikeCommandLine

Link to code

> Bases: CommandLine

> 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.

> argsa unicode string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

### SimpleInterface

Link to code

> Bases: BaseInterface

> 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 nipype.interfaces.base import (
>     ...     SimpleInterface, BaseInterfaceInputSpec, TraitedSpec)

>     >>> 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

### StdOutCommandLine

Link to code

> Bases: CommandLine

> argsa unicode string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

> out_filea pathlike object or string representing a file

>   Maps to a command-line argument: `> %s` (position: -1).