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¶
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 inputsoutput_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 isFalse
).resource_monitor (bool) – If
False
, prevents resource-monitoring this interface IfTrue
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:
- 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¶
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¶
Bases: BaseInterface
- LibraryBaseInterface.imports = ()¶
- property LibraryBaseInterface.version¶
interfaces should implement a version property
MpiCommandLine¶
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 begining of command
SEMLikeCommandLine¶
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¶
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_valueThis 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¶
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).