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.

Attributes:

  • input_spec (nipype.interfaces.base.specs.TraitedSpec) – points to the traited class for the inputs

  • output_spec (nipype.interfaces.base.specs.TraitedSpec) – points to the traited class for the outputs

  • _redirect_x (bool) – should be set to True when the interface requires connecting to a $DISPLAY (default is False).

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

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

Parameters:

  • command (str) – define base immutable command you wish to run

  • args (str, 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'}}

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

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • environ (a 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)
property CommandLine.write_cmdline
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'
Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • environ (a 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_procs (an integer) – Num processors to specify to mpiexec. Do not specify if this is managed externally (e.g. through SGE).

  • use_mpi (a boolean) – Whether or not to run the command with mpiexec. (Nipype default value: False)

property MpiCommandLine.cmdline

Adds ‘mpiexec’ to beginning 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.

Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • environ (a 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

Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • environ (a 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_file (a pathlike object or string representing a file) – Maps to a command-line argument: > %s (position: -1).