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.
references_
= []¶
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)¶
-
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¶
-
output_spec
= None¶
-
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).