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.

class nipype.interfaces.base.core.BaseInterface(from_file=None, resource_monitor=None, ignore_exception=False, **inputs)

Bases: 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).

aggregate_outputs(runtime=None, needed_outputs=None)

Collate expected outputs and apply output traits validation.

load_inputs_from_json(json_file, overwrite=True)

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

resource_monitor = True
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

save_inputs_to_json(json_file)

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

property version

interfaces should implement a version property

class nipype.interfaces.base.core.CommandLine(command=None, terminal_output=None, write_cmdline=False, **inputs)

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 cmd

sets base command, immutable

property cmdline

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

raise_exception(runtime)
classmethod 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 terminal_output
version_from_command(flag='-v', cmd=None)
property 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

class nipype.interfaces.base.core.LibraryBaseInterface(check_import=True, *args, **kwargs)

Bases: BaseInterface

imports = ()
property version

interfaces should implement a version property

class nipype.interfaces.base.core.MpiCommandLine(command=None, terminal_output=None, write_cmdline=False, **inputs)

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 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
class nipype.interfaces.base.core.SEMLikeCommandLine(command=None, terminal_output=None, write_cmdline=False, **inputs)

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: {})

class nipype.interfaces.base.core.SimpleInterface(from_file=None, resource_monitor=None, **inputs)

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
class nipype.interfaces.base.core.StdOutCommandLine(command=None, terminal_output=None, write_cmdline=False, **inputs)

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