populse_mia.user_interface.pipeline_manager.process_mia¶

Module for managing and running processes within the Populse_mia framework.

This module provides specialized classes and methods to handle the execution and completion of processes within the Populse_mia framework. It includes functionalities for managing process attributes, handling database interactions, and ensuring proper inheritance of metadata tags. The module supports various process types, including those from mia_processes, Nipype, and Capsul.

Contains:

Class:

MIAProcessCompletionEngine
MIAProcessCompletionEngineFactory
ProcessMIA

Classes

`MIAProcessCompletionEngine`(process, name, ...)	A specialized completion engine for all processes within the Populse_mia context.
`MIAProcessCompletionEngineFactory`()	Specialization of the ProcessCompletionEngineFactory for the Populse Mia context.
`ProcessMIA`(args, *kwargs)	Extends the Capsul Process class to customize execution for Mia bricks.

class populse_mia.user_interface.pipeline_manager.process_mia.Pipeline(autoexport_nodes_parameters=None, **kwargs)[source]¶

Bases: Process

Pipeline containing Process nodes, and links between node parameters.

A Pipeline is normally subclassed, and its pipeline_definition() method is overloaded to define its nodes and links. pipeline_definition() will be called by the pipeline constructor.

from capsul.pipeline import Pipeline

class MyPipeline(Pipeline):

  def pipeline_definition(self):
      self.add_process('proc1', 'my_toolbox.my_process1')
      self.add_process('proc2', 'my_toolbox.my_process2')
      self.add_switch('main_switch', ['in1', 'in2'], ['out1', 'out2'])
      self.add_link('proc1.out1->main_switch.in1_switch_out1')
      self.add_link('proc1.out2->main_switch.in1_switch_out2')
      self.add_link('proc2.out1->main_switch.in2_switch_out1')
      self.add_link('proc2.out1->main_switch.in2_switch_out2')

After execution of pipeline_definition(), the inner nodes parameters which are not connected will be automatically exported to the parent pipeline, with names prefixed with their process name, unless they are listed in a special “do_not_export” list (passed to add_process() or stored in the pipeline instance).

>>> pipeline = MyPipeline()
>>> print(pipeline.proc1_input)
<undefined>

Nodes

A pipeline is made of nodes, and links between their parameters. Several types of nodes may be part of a pipeline:

process nodes (pipeline_nodes.ProcessNode) are the leaf nodes which represent actual processing bricks.
pipeline nodes (pipeline_nodes.PipelineNode) are sub-pipelines which allow to reuse an existing pipeline within another one
switch nodes (pipeline_nodes.Switch) allows to select values between several possible inputs. The switch mechanism also allows to select between several alternative processes or processing branches.
iterative process (:py:class:process_iteration.ProcessIteration`) represent parallel processing of the same pipeline on a set of parameters.

Note that you normally do not instantiate these nodes explicitly when building a pipeline. Rather programmers may call the add_process(), add_switch(), add_iterative_process() methods.

Nodes activation

Pipeline nodes may be enabled or disabled. Disabling a node will trigger a global pipeline nodes activation step, where all nodes which do not form a complete chain will be inactive. This way a branch may be disabled by disabling one of its nodes. This process is used by the switch system, which allows to select one processing branch between several, and disables the unselected ones.

Pipeline steps

Pipelines may define execution steps: they are user-oriented groups of nodes that are to be run together, or disabled together for runtime execution. They are intended to allow partial, or step-by-step execution. They do not work like the nodes enabling mechanism described above.

Steps may be defined within the pipeline_definition() method. See add_pipeline_step().

Note also that pipeline steps only act at the highest level: if a sub-pipeline has disabled steps, they will not be taken into account in the higher level pipeline execution, because executing by steps a part of a sub-pipeline within the context of a higher one does generally not make sense.

Main methods

pipeline_definition()
add_process()
add_switch()
add_custom_node()
add_iterative_process()
add_optional_output_switch()
add_processes_selection()
add_link()
remove_link()
export_parameter()
autoexport_nodes_parameters()
add_pipeline_step()
define_pipeline_steps()
define_groups_as_steps()
remove_pipeline_step()
enable_all_pipeline_steps()
disabled_pipeline_steps_nodes()
get_pipeline_step_nodes()
find_empty_parameters()
count_items()

nodes¶

a dictionary containing the pipeline nodes and where the pipeline node name is ‘’

Type:: dict {node_name: node}

workflow_list¶

a list of ordered nodes that can be executed

Type:: list

workflow_repr¶

a string representation of the workflow list <node_i>-><node_i+1>

Type:: str

Note

Type ‘Pipeline.help()’ for a full description of this process parameters.
Type ‘<Pipeline>.get_input_spec()’ for a full description of this process input trait types.
Type ‘<Pipeline>.get_output_spec()’ for a full description of this process output trait types.

_doc_path = 'api/pipeline.html#pipeline'¶

do_autoexport_nodes_parameters = True¶

hide_nodes_activation = True¶

__init__(autoexport_nodes_parameters=None, **kwargs)[source]¶

Initialize the Pipeline class

Parameters:: autoexport_nodes_parameters (bool) – if True (default) nodes containing pipeline plugs are automatically exported.

pipeline_definition()[source]¶

Define pipeline structure, nodes, sub-pipelines, switches, and links.

This method should be overloaded in subclasses, it does nothing in the base Pipeline class.

autoexport_nodes_parameters(include_optional=False)[source]¶

Automatically export nodes plugs to the pipeline.

Some parameters can be explicitly preserved from exportation if they are listed in the pipeline “do_not_export” variable (list or set).

Parameters:: include_optional (bool (optional)) – If True (the default), optional plugs are not exported Exception: optional output plugs of switches are exported (otherwise they are useless). It should probably be any single output plug of a node.

add_trait(name, trait)[source]¶

Add a trait to the pipeline

Parameters:

name (str (mandatory)) – the trait name
trait (trait instance (mandatory)) – the trait we want to add

remove_trait(name)[source]¶

Remove a trait to the pipeline

Parameters:: name (str (mandatory)) – the trait name

reorder_traits(names)[source]¶: Reimplementation of Controller method reorder_traits() so that we also reorder the pipeline node plugs.

_make_subprocess_context_name(name)[source]¶: build full contextual name on process instance

_set_subprocess_context_name(process, name)[source]¶: set full contextual name on process instance

add_process(name, process, do_not_export=None, make_optional=None, inputs_to_copy=None, inputs_to_clean=None, skip_invalid=False, **kwargs)[source]¶

Add a new node in the pipeline

Note about invalid nodes:

A pipeline can typically offer alternatives (through a switch) to different algorithmic nodes, which may have different dependencies, or may be provided through external modules, thus can be missing. To handle this, Capsul can be telled that a process node can be invalid (or missing) without otherwise interfering the rest of the pipeline. This is done using the “skip_invalid” option. When used, the process to be added is tested, and if its instantiation fails, it will not be added in the pipeline, but will not trigger an error. Instead the missing node will be marked as “allowed invalid”, and links and exports built using this node will silently do nothing. thus the pipeline will work normally, without the invalid node.

Such nodes are generally gathered through a switch mechanism. However the switch inputs should be restricted to actually available nodes. The recommended method is to check that nodes have actually been added in the pipeline. Then links can be made normally as if the nodes were all present:

self.add_process('method1', 'module1.Module1', skip_invalid=True)
self.add_process('method2', 'module2.Module2', skip_invalid=True)
self.add_process('method3', 'module3.Module3', skip_invalid=True)

input_params = [n for n in ['method1', 'method2', 'method3']
                if n in self.nodes]
self.add_switch('select_method', input_params, 'output')

self.add_link('method1.input->select_method.method1_switch_output')
self.add_link('method2.input->select_method.method2_switch_output')
self.add_link('method3.input->select_method.method3_switch_output')

A last note about invalid nodes:

When saving a pipeline (through the graphical editor typically), missing nodes will not be saved because they are not actually in the pipeline. So be careful to save only pipelines with full features.

Parameters:

name (str (mandatory)) – the node name (has to be unique).
process (Process (mandatory)) – the process we want to add. May be a string (‘module.process’), a process instance or a class.
do_not_export (list of str (optional)) – a list of plug names that we do not want to export.
make_optional (list of str (optional)) – a list of plug names that we do not want to export.
inputs_to_copy (list of str (optional)) – a list of item to copy.
inputs_to_clean (list of str (optional)) – a list of temporary items.
skip_invalid (bool) – if True, if the process is failing (cannot be instantiated), don’t throw an exception but instead don’t insert the node, and mark it as such in order to make add_link() to also silently do nothing. This option is useful for optional process nodes which may or may not be available depending on their dependencies, typically in a switch offering several alternative methods.

remove_node(node_name)[source]¶: Remove a node from the pipeline

add_iterative_process(name, process, iterative_plugs=None, do_not_export=None, make_optional=None, inputs_to_copy=None, inputs_to_clean=None, **kwargs)[source]¶

Add a new iterative node in the pipeline.

Parameters:

name (str (mandatory)) – the node name (has to be unique).
process (Process or str (mandatory)) – the process we want to add.
iterative_plugs (list of str (optional)) – a list of plug names on which we want to iterate. If None, all plugs of the process will be iterated.
do_not_export (list of str (optional)) – a list of plug names that we do not want to export.
make_optional (list of str (optional)) – a list of plug names that we do not want to export.
inputs_to_copy (list of str (optional)) – a list of item to copy.
inputs_to_clean (list of str (optional)) – a list of temporary items.

call_process_method(process_name, method, *args, **kwargs)[source]¶

Call a method of a process previously added with add_process or add_iterative_process.

Parameters:

process_name (str (mandatory)) – name given to the process node.
method (str (mandatory)) – name of the method to call.

add_switch(name, inputs, outputs, export_switch=True, make_optional=(), output_types=None, switch_value=None, opt_nodes=None)[source]¶

Add a switch node in the pipeline

Parameters:

name (str (mandatory)) – name for the switch node (has to be unique)
inputs (list of str (mandatory)) – names for switch inputs. Switch activation will select amongst them. Inputs names will actually be a combination of input and output, in the shape “input_switch_output”. This behaviour is needed when there are several outputs, and thus several input groups.
outputs (list of str (mandatory)) – names for outputs.
export_switch (bool (optional)) – if True, export the switch trigger to the parent pipeline with name as parameter name
make_optional (sequence (optional)) – list of optional outputs. These outputs will be made optional in the switch output. By default they are mandatory.
output_types (sequence of traits (optional)) – If given, this sequence should have the same size as outputs. It will specify each switch output parameter type (as a standard trait). Input parameters for each input block will also have this type.
switch_value (str (optional)) – Initial value of the switch parameter (one of the inputs names). Defaults to 1st input.
opt_nodes (bool or list) – tells that switch values are node names, and some of them may be optional and missing. In such a case, missing nodes are not added as inputs. If a list is passed, then it is a list of node names which length should match the number of inputs, and which order tells nodes related to inputs (in case inputs names are not directly node names).

Examples

>>> pipeline.add_switch('group_switch', ['in1', 'in2'],
                        ['out1', 'out2'])

will create a switch with 4 inputs and 2 outputs: inputs: “in1_switch_out1”, “in2_switch_out1”, “in1_switch_out2”, “in2_switch_out2” outputs: “out1”, “out2”

See also add_pipeline_step()

Parameters:: steps (dict or preferably OrderedDict or SortedDictionary (mandatory)) – The steps dict keys are steps names, the values are lists of nodes names forming the step.

add_pipeline_step(step_name, nodes, enabled=True)[source]¶

Add a step definition to the pipeline (see also define_steps).

Steps are groups of pipeline nodes, which may be disabled at runtime. They are normally defined in a logical order regarding the workflow streams. They are different from pipelines in that steps are purely virtual groups, they do not have parameters.

Disabling a step acts differently as the pipeline node activation: other nodes are not inactivated according to their dependencies. Instead, those steps are not run.

Parameters:

step_name (string (mandatory)) – name of the new step
nodes (list or sequence) – nodes contained in the step (Node instances)
enabled (bool (optional)) – initial state of the step

remove_pipeline_step(step_name)[source]¶: Remove the given step

disabled_pipeline_steps_nodes()[source]¶

List nodes disabled for runtime execution

Returns:: disabled_nodes – list of pipeline nodes (Node instances) which will not run in a workflow created from this pipeline state.
Return type:: list

get_pipeline_step_nodes(step_name)[source]¶: Get the nodes in the given pipeline step

enable_all_pipeline_steps()[source]¶: Set all defined steps (using add_step() or define_steps()) to be enabled. Useful to reset the pipeline state after it has been changed.

_change_processes_selection(selection_name, selection_group)[source]¶

add_processes_selection(selection_parameter, selection_groups, value=None)[source]¶

Add a processes selection switch definition to the pipeline.

Selectors are a “different” kind of switch: one pipeline node set in a group is enabled, the others are disabled.

The selector has 2 levels:

selection_parameter selects a group.

A group contains a set of nodes which will be activated together. Groups are mutually exclusive.

Parameters:

selection_parameter (string (mandatory)) – name of the selector parameter: the parameter is added in the pipeline, and its value is the name of the selected group.
selection_groups (dict or OrderedDict) – nodes groups contained in the selector : {group_name: [Node names]}
value (str (optional)) – initial state of the selector (default: 1st group)

get_processes_selections()[source]¶: Get process_selection groups names (corresponding to selection parameters on the pipeline)

get_processes_selection_groups(selection_parameter)[source]¶: Get groups names involved in a processes selection switch

get_processes_selection_nodes(selection_parameter, group)[source]¶: Get nodes names involved in a processes selection switch with value group

set_study_config(study_config)[source]¶: Set a StudyConfig for the process. Note that it can only be done once: once a non-null StudyConfig has been assigned to the process, it should not change.

define_groups_as_steps(exclusive=True)[source]¶

Define parameters groups according to which steps they are connected to.

Parameters:: exclusive (bool (optional)) – if True, a parameter is assigned to a single group, the first step it is connected to. If False, a parameter is assigned all steps groups it is connected to.

check_requirements(environment='global', message_list=None)[source]¶

Reimplementation for pipelines of capsul.process.process.Process.check_requirements

A pipeline will return a list of unique configuration values.

rename_node(old_node_name, new_node_name)[source]¶

Change the name of the selected node and updates the pipeline.

Parameters:

old_node_name (str) – old node name
new_node_name (str) – new node name

class populse_mia.user_interface.pipeline_manager.process_mia.Process(**kwargs)[source]¶

Bases: Controller

A process is an atomic component that contains a processing.

A process is typically an object with typed parameters, and an execution function. Parameters are described using Enthought traits through Soma-Base Controller base class.

In addition to describing its parameters, a Process must implement its execution function, either through a python method, by overloading _run_process(), or through a commandline execution, by overloading get_commandline(). The second way allows to run on a remote processing machine which has not necessary capsul, nor python, installed.

Parameters are declared or queried using the traits API, and their values are in the process instance variables:

from __future__ import print_function
from capsul.api import Process
import traits.api as traits

class MyProcess(Process):

    # a class trait
    param1 = traits.Str('def_param1')

    def __init__(self):
        super(MyProcess, self).__init__()
        # declare an input param
        self.add_trait('param2', traits.Int())
        # declare an output param
        self.add_trait('out_param', traits.File(output=True))

    def _run_process(self):
        with open(self.out_param, 'w') as f:
            print('param1:', self.param1, file=f)
            print('param2:', self.param2, file=f)

# run it with parameters
MyProcess()(param2=12, out_param='/tmp/log.txt')

Note about the File and Directory traits

The File trait type represents a file parameter. A file is actually two things: a filename (string), and the file itself (on the filesystem). For an input it is OK not to distinguish them, but for an output, there are two different cases:

the file (on the filesystem) is an output, but the filename (string) is given as an input: this is the classical “commandline” behavior, when we tell the program where it should write its output file.
the file is an output, and the filename is also an output: this is rather a “function return value” behavior: the process determines internally where it should write the file, and tells as an output where it did.

To distinguish these two cases, in Capsul we normally add in the File or Directory trait a property input_filename which is True when the filename is an input, and False when the filename is an output:

self.add_trait('out_file',
               traits.File(output=True, input_filename=False))

However, as most of our processes are based on the “commandline behavior” (the filename is an input) and we often forget to specify the input_filename parameter, the default is the “filename is an input” behavior, when not specified.

Attributes

name¶

the class name.

Type:: str

id¶

the string description of the class location (ie., module.class).

Type:: str

log_file¶

if None, the log will be generated in the current directory otherwise it will be written in log_file path.

Type:: str (default None)

Note

Type ‘Process.help()’ for a full description of this process parameters.
Type ‘<Process>.get_input_spec()’ for a full description of this process input trait types.
Type ‘<Process>.get_output_spec()’ for a full description of this process output trait types.

__init__(**kwargs)[source]¶: Initialize the Process class.

add_trait(name, trait)[source]¶: Ensure that trait.output and trait.optional are set to a boolean value before calling parent class add_trait.

run(**kwargs)[source]¶: Obsolete: use self.__call__ instead

_run_process()[source]¶

Runs the processings when the instance is called.

Either this _run_process() or get_commandline() must be defined in derived classes.

Note that _run_process() is called as a python function, on a Process instance. When using remote processing (cluster for instance), this means that the commandline which will run needs to be able to re- instantiate the same process: the process thus has to be stored in a file or python module which can be accessed from the remote machine, and python / capsul correctly installed and available on it.

get_commandline() at the contrary, can implement commandlines which are completely independent from Capsul, and from python.

Note

If both methods are not defined in the derived class a NotImplementedError error is raised.

On the other side, if both methods are overloaded, the process behavior in local sequential computing mode and in Soma-Workflow modes may be different.

_before_run_process()[source]¶: This method is called by StudyConfig.run() before calling _run_process(). By default, it does nothing but can be overridden in derived classes.

_after_run_process(run_process_result)[source]¶: This method is called by StudyConfig.run() after calling _run_process(). It is expected to return the final result of the process. By default, it does nothing but can be overridden in derived classes.

_get_log(exec_info)[source]¶

Method that generate the logging structure from the execution information and class attributes.

Parameters:: exec_info (dict (mandatory)) – the execution information, the dictionary is supposed to contain a runtime attribute.
Returns:: log – the logging information.
Return type:: dict

_rst_table(data)[source]¶

Create a rst formatted table.

Parameters:: data (list of lists of str (mandatory)) – the table line-cell centent.
Returns:: rsttable – the rst formatted table containing the input data.
Return type:: list of str

save_log(returncode)[source]¶

Method to save process execution information in json format.

If the class attribute log_file is not set, a log.json output file is generated in the process call current working directory.

Parameters:: returncode (ProcessResult) – the process result return code.

classmethod help(returnhelp=False)[source]¶

Method to print the full help.

Parameters:

cls (process class (mandatory)) – a process class
returnhelp (bool (optional, default False)) – if True return the help string message, otherwise display it on the console.

get_commandline()[source]¶

Method to generate a commandline representation of the process.

If not implemented, it will generate a commandline running python, instantiating the current process, and calling its _run_process() method.

Returns:: commandline – Arguments are in separate elements of the list.
Return type:: list of strings

params_to_command()[source]¶

Generates a commandline representation of the process.

If not implemented, it will generate a commandline running python, instantiating the current process, and calling its _run_process() method.

This method is new in Capsul v3 and is a replacement for get_commandline().

It can be overwritten by custom Process subclasses. Actually each process should overwrite either params_to_command() or _run_process().

The returned commandline is a list, which first element is a “method”, and others are the actual commandline with arguments. There are several methods, the process is free to use either of the supported ones, depending on how the execution is implemented.

Methods:

capsul_job: Capsul process run in python

The command will run the _run_process() execution method of the process, after loading input parameters from a JSON dictionary file. The only second element in the commandline list is the process identifier (module/class as in get_process_instance()). The location of the JSON file will be passed to the job execution through an environment variable SOMAWF_INPUT_PARAMS:

return ['capsul_job', 'morphologist.capsul.morphologist']

format_string: free commandline with replacements for parameters

Command arguments can be, or contain, format strings in the shape ‘%(param)s’, where param is a parameter of the process. This way we can map values correctly, and call a foreign command:

return ['format_string', 'ls', '%(input_dir)s']

json_job: free commandline with JSON file for input parameters

A bit like capsul_job but without the automatic wrapper:

return ['json_job', 'python', '-m', 'my_module']

Returns:: commandline – Arguments are in separate elements of the list.
Return type:: list of strings

make_commandline_argument(*args)[source]¶

This helper function may be used to build non-trivial commandline arguments in get_commandline implementations. Basically it concatenates arguments, but it also takes care of keeping track of temporary file objects (if any), and converts non-string arguments to strings (using repr()).

Ex:

>>> process.make_commandline_argument('param=', self.param)

will return the same as:

>>> 'param=' + self.param

if self.param is a string (file name) or a temporary path.

static run_from_commandline(process_definition)[source]¶

Run a process from a commandline call. The process name (with module) are given in argument, input parameters should be passed through a JSON file which location is in the SOMAWF_INPUT_PARAMS environment variable.

If the process has outputs, the SOMAWF_OUTUT_PARAMS environment variable should contain the location of an output file which will be written with a dict containing output parameters values.

get_log()[source]¶

Load the logging file.

Returns:: log – the content of the log file.
Return type:: dict

get_input_spec()[source]¶

Method to access the process input specifications.

Returns:: outputs – a string representation of all the input trait specifications.
Return type:: str

get_output_spec()[source]¶

Method to access the process output specifications.

Returns:: outputs – a string representation of all the output trait specifications.
Return type:: str

get_inputs()[source]¶

Method to access the process inputs.

Returns:: outputs – a dictionary with all the input trait names and values.
Return type:: dict

get_outputs()[source]¶

Method to access the process outputs.

Returns:: outputs – a dictionary with all the output trait names and values.
Return type:: dict

get_help(returnhelp=False, use_labels=False)[source]¶

Generate description of a process parameters.

Parameters:

returnhelp (bool (optional, default False)) – if True return the help string message formatted in rst, otherwise display the raw help string message on the console.
use_labels (bool) – if True, input and output sections will get a RestructuredText label to avoid ambiguities.

get_input_help(rst_formating=False)[source]¶

Generate description for process input parameters.

Parameters:: rst_formating (bool (optional, default False)) – if True generate a rst table with the input descriptions.
Returns:: helpstr – the class input traits help
Return type:: str

get_output_help(rst_formating=False)[source]¶

Generate description for process output parameters.

Parameters:: rst_formating (bool (optional, default False)) – if True generate a rst table with the input descriptions.
Returns:: helpstr – the trait output help descriptions
Return type:: str

set_parameter(name, value, protected=None)[source]¶

Method to set a process instance trait value.

For File and Directory traits the None value is replaced by the special Undefined trait value.

Parameters:

name (str (mandatory)) – the trait name we want to modify
value (object (mandatory)) – the trait value we want to set
protected (None or bool (tristate)) – if True or False, force the “protected” status of the plug. If None, keep it as is.

get_parameter(name)[source]¶

Method to access the value of a process instance.

Parameters:: name (str (mandatory)) – the trait name we want to modify
Returns:: value – the trait value we want to access
Return type:: object

get_study_config()[source]¶: Get (or create) the StudyConfig this process belongs to

set_study_config(study_config)[source]¶: Set a StudyConfig for the process. Note that it can only be done once: once a non-null StudyConfig has been assigned to the process, it should not change.

get_missing_mandatory_parameters()[source]¶: Returns a list of parameters which are not optional, and which value is Undefined or None, or an empty string for a File or Directory parameter.

requirements()[source]¶

Requirements needed to run the process. It is a dictionary which keys are config/settings modules and values are requests for them.

The default implementation returns an empty dict (no requirements), and should be overloaded by processes which actually have requirements.

Ex:

{'spm': 'version >= "12" and standalone == "True"')

check_requirements(environment='global', message_list=None)[source]¶

Checks the process requirements against configuration settings values in the attached CapsulEngine. This makes use of the requirements() method and checks that there is one matching config value for each required module.

Parameters:

environment (str) – config environment id. Normally corresponds to the computing resource name, and defaults to “global”.
message_list (list) – if not None, this list will be updated with messages for unsatisfied requirements, in order to present the user with an understandable error.

Returns:

config – if None is returned, requirements are not met: the process cannot run. If a dict is returned, it corresponds to the matching config values. When no requirements are needed, an empty dict is returned. A pipeline, if its requirements are met will return a list of configuration values, because different nodes may require different config values.

Return type:

dict, list, or None

populse_mia.user_interface.pipeline_manager.process_mia.capsul_engine(database_location=None, require=None)[source]¶

User factory for creating capsul engines.

If no database_location is given, it will default to an internal (in- memory) database with no persistent settings or history values.

Configuration is read from a dictionary stored in two database entries. The first entry has the key ‘global_config’ (i.e. database.json_value(‘global_config’)), it contains the configuration values that are shared by all processing engines. The second entry is computing_config`. It contains a dictionary with one item per computing resource where the key is the resource name and the value is configuration values that are specific to this computing resource.

Before initialization of the CapsulEngine, modules are loaded. The list of loaded modules is searched in the ‘modules’ value in the database (i.e. in database.json_value(‘modules’)) ; if no list is defined in the database, capsul.module.default_modules is used.

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessCompletionEngine(process, name=None)[source]¶

Bases: HasTraits

Parameters completion from attributes for a process or pipeline node instance, in the context of a specific data organization.

ProcessCompletionEngine can be used directly for a pipeline, which merely delegates completion to its nodes, and has to be subclassed for a data organization framework on a node.

To get a completion engine, use:

completion_engine = ProcessCompletionEngine.get_completion_engine(
    node, name)

Note that this will assign permanently the ProcessCompletionEngine object to its associated node or process. To get and set the attributes set:

attributes = completion_engine.get_attribute_values()
print(attributes.user_traits().keys())
attributes.specific_process_attribute = 'a value'

Once attributes are set, to process with parameters completion:

completion_engine.complete_parameters()

It is possible to have complete_parameters() triggered automatically when attributes or switch nodes change. To set this up, use:

completion_engine.install_auto_completion()

ProcessCompletionEngine can (and should) be specialized, at least to provide the attributes set for a given process. A factory is used to create the correct type of ProcessCompletionEngine for a given process / name: ProcessCompletionEngineFactory

capsul.attributes.fom_completion_engine.FomProcessCompletionEngine is a specialization of ProcessCompletionEngine to manage File Organization Models (FOM).

get_completion_engine()[source]¶

get_attribute_values()[source]¶

complete_parameters()[source]¶

set_parameters()[source]¶

attributes_to_path()[source]¶

get_path_completion_engine()[source]¶

install_auto_completion()[source]¶

remove_auto_completion()[source]¶

__init__(process, name=None)[source]¶

_clear_node(wr)[source]¶: Called when the object behind the self.process proxy is about to be deleted

get_attribute_values()[source]¶

Get attributes Controller associated to a process or node

Returns:

attributes (ProcessAttributes instance)
The default implementation does nothing for a
single Process instance, and merges attributes from its children if
the process is a pipeline.

_get_linked_attributes()[source]¶

complete_parameters(process_inputs={}, complete_iterations=True)[source]¶

Completes file parameters from given inputs parameters, which may include both “regular” process parameters (file names) and attributes.

Parameters:

process_inputs (dict (optional)) – parameters to be set on the process. It may include “regular” process parameters, and attributes used for completion. Attributes should be in a sub-dictionary under the key “capsul_attributes”.
complete_iterations (bool (optional)) – if False, iteration nodes inside the pipeline will not run their own completion. Thus parameters for the iterations will not be correctly completed. However this has 2 advantages: 1. it prevents modification of the input pipeline, 2. it will not do iterations completion which will anyway be done (again) when building a workflow in ~capsul.pipeline.pipeline_workflow.workflow_from_pipeline.

attributes_to_path(parameter, attributes)[source]¶

Build a path from attributes for a given parameter in a process.

Parameters:

parameter (str)
attributes (ProcessAttributes instance (Controller))

set_parameters(process_inputs)[source]¶: Set the given parameters dict to the given process. process_inputs may include regular parameters of the underlying process, and attributes (capsul_attributes: dict).

attributes_changed(obj, name, old, new)[source]¶

Traits changed callback which triggers parameters update.

This method basically calls complete_parameters() (after some checks).

Users do not normally have to use it directly, it is used internally when install_auto_completion() has been called.

See install_auto_completion()

nodes_selection_changed(obj, name, old, new)[source]¶

Traits changed callback which triggers parameters update.

This method basically calls complete_parameters() (after some checks).

Users do not normally have to use it directly, it is used internally when install_auto_completion() has been called.

See install_auto_completion()

install_auto_completion()[source]¶: Monitor attributes changes and switches changes (which may influence attributes) and recompute parameters completion when needed.

remove_auto_completion()[source]¶

Remove attributes monitoring and auto-recomputing of parameters.

Reverts install_auto_completion()

get_path_completion_engine()[source]¶: Get a PathCompletionEngine object for the given process. The default implementation queries PathCompletionEngineFactory, but some specific ProcessCompletionEngine implementations may override it for path completion at the process level (FOMs for instance).

static get_completion_engine(process, name=None)[source]¶: Get a ProcessCompletionEngine instance for a given process/node within the framework of its StudyConfig factory function.

static _remove_completion_engine(process)[source]¶

static _del_process_callback(process)[source]¶

_get_schemas()[source]¶: Get schemas dictionary from process and its StudyConfig

_install_subprogress_moniotoring(subprocess_compl)[source]¶

_remove_subprogress_moniotoring(subprocess_compl)[source]¶

static _substep_completion_progress(self, substep_completion_engine, obj, name, old, new)[source]¶

remove_attributes()[source]¶: Clear attributes controller cache, to allow rebuilding it after a change. This is generally a callback attached to switches changes.

remove_switch_observers()[source]¶: Remove notification callbacks previously set to listen switches state changes.

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessCompletionEngineFactory[source]¶

Bases: object

Get a ProcessCompletionEngine instance

factory_id = 'basic'¶

get_completion_engine(process, name=None)[source]¶

Factory for ProcessCompletionEngine: get an ProcessCompletionEngine instance for a process in the context of a given StudyConfig.

The study_config should specify which completion system(s) is (are) used (FOM, …) If nothing is configured, a ProcessCompletionEngine base instance will be returned. It will not be able to perform completion at all, but will conform to the API.

The base class implementation returns a base ProcessCompletionEngine instance, which is quite incomplete.

class populse_mia.user_interface.pipeline_manager.process_mia.BuiltinProcessCompletionEngineFactory[source]¶

Bases: ProcessCompletionEngineFactory

factory_id = 'builtin'¶

get_completion_engine(process, name=None)[source]¶

Factory for ProcessCompletionEngine: get an ProcessCompletionEngine instance for a node or process in the context of a given StudyConfig.

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessNode(pipeline, name, process, **kwargs)[source]¶

Bases: Node

Process node.

process¶

the process instance stored in the pipeline node

Type:: process instance

set_callback_on_plug()[source]¶

get_plug_value()[source]¶

set_plug_value()[source]¶

get_trait()[source]¶

__init__(pipeline, name, process, **kwargs)[source]¶

Generate a ProcessNode

Parameters:

pipeline (Pipeline (mandatory)) – the pipeline object where the node is added.
name (str (mandatory)) – the node name.
process (instance) – a process/interface instance.
kwargs (dict) – process default values.

set_callback_on_plug(plug_name, callback)[source]¶

Add an event when a plug change

Parameters:

plug_name (str (mandatory)) – a plug name
callback (@f (mandatory)) – a callback function

remove_callback_from_plug(plug_name, callback)[source]¶

Remove an event when a plug change

Parameters:

plug_name (str (mandatory)) – a plug name
callback (@f (mandatory)) – a callback function

get_plug_value(plug_name)[source]¶

Return the plug value

Parameters:: plug_name (str (mandatory)) – a plug name
Returns:: output – the plug value
Return type:: object

set_plug_value(plug_name, value, protected=None)[source]¶

Set the plug value

Parameters:

plug_name (str (mandatory)) – a plug name
value (object (mandatory)) – the plug value we want to set
protected (None or bool (tristate)) – if True or False, force the “protected” status of the plug. If None, keep it as is.

is_parameter_protected(plug_name)[source]¶: Tells whether the given parameter is protected or not

protect_parameter(plug_name, state=True)[source]¶

Protect the named parameter.

Protecting is not a real lock, it just marks the parameter a list of “protected” parameters. This is typically used to mark values that have been set manually by the user (using the ControllerWidget for instance) and that should not be later modified by automatic parameters tweaking (such as completion systems).

Protected parameters are listed in an additional trait, “protected_parameters”.

If the “state” parameter is False, then we will unprotect it (calling unprotect_parameter())

get_trait(trait_name)[source]¶

Return the desired trait

Parameters:: trait_name (str (mandatory)) – a trait name
Returns:: output – the trait named trait_name
Return type:: trait

is_job()[source]¶: if True, the node will be represented as a Job in Soma-Workflow. Otherwise the node is static and does not run.

requirements()[source]¶: Requirements reimplementation for a process node. This node delegates to its underlying process. see capsul.process.process.requirements()

check_requirements(environment='global', message_list=None)[source]¶: Reimplementation of capsul.pipeline.pipeline_nodes.Node.requirements() for a ProcessNode. This one delegates to its underlying process (or pipeline).

get_study_config()[source]¶: Get (or create) the StudyConfig this process belongs to

set_study_config(study_config)[source]¶: Get (or create) the StudyConfig this process belongs to

_process_deleted(process)[source]¶

property study_config¶

property completion_engine¶

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessIteration(process, iterative_parameters, study_config=None, context_name=None)[source]¶

Bases: Process

Note

Type ‘ProcessIteration.help()’ for a full description of this process parameters.
Type ‘<ProcessIteration>.get_input_spec()’ for a full description of this process input trait types.
Type ‘<ProcessIteration>.get_output_spec()’ for a full description of this process output trait types.

_doc_path = 'api/pipeline.html#processiteration'¶

__init__(process, iterative_parameters, study_config=None, context_name=None)[source]¶: Initialize the Process class.

_resize_outputs()[source]¶

change_iterative_plug(parameter, iterative=None)[source]¶

Change a parameter to be iterative (or non-iterative)

Parameters:

parameter (str) – parameter name
iterative (bool or None) – if None, the iterative state will be toggled. If True or False, the parameter state will be set accordingly.

_run_process()[source]¶

Runs the processings when the instance is called.

Either this _run_process() or get_commandline() must be defined in derived classes.

get_commandline() at the contrary, can implement commandlines which are completely independent from Capsul, and from python.

Note

If both methods are not defined in the derived class a NotImplementedError error is raised.

On the other side, if both methods are overloaded, the process behavior in local sequential computing mode and in Soma-Workflow modes may be different.

set_study_config(study_config)[source]¶: Set a StudyConfig for the process. Note that it can only be done once: once a non-null StudyConfig has been assigned to the process, it should not change.

complete_iteration(iteration)[source]¶

class populse_mia.user_interface.pipeline_manager.process_mia.NipypeProcess(*args, **kwargs)[source]¶

Bases: FileCopyProcess

Base class used to wrap nipype interfaces.

Note

Type ‘NipypeProcess.help()’ for a full description of this process parameters.
Type ‘<NipypeProcess>.get_input_spec()’ for a full description of this process input trait types.
Type ‘<NipypeProcess>.get_output_spec()’ for a full description of this process output trait types.

__init__(nipype_instance=None, use_temp_output_dir=None, *args, **kwargs)[source]¶

Initialize the NipypeProcess class.

NipypeProcess instance gets automatically an additional user trait ‘output_directory’.

This class also fix some lacks of the nipype version ‘0.10.0’.

NipypeProcess is normally not instantiated directly, but through the CapsulEngine factory, using a nipype interface name:

ce = capsul_engine()
npproc = ce.get_process_instance('nipype.interfaces.spm.Smooth')

However, it is now still possible to instantiate it directly, using a nipype interface class or instance:

npproc = NipypeProcess(nipype.interfaces.spm.Smooth)

NipypeProcess may be subclassed for specialized interfaces. In such a case, the subclass may provide:

(optionally) a class attribute _nipype_class_type to specify the

nipype interface class. If present the nipype interface class or instance will not be specified in the constructor call. * (optionally) a __postinit__() method which will be called in addition to the constructor, but later once the instance is correctly setup. This __postinit__ method allows to customize the new class instance. * (optionally) a class attribute _nipype_trait_mapping: a dict specifying a translation table between nipype traits names and the names they will get in the Process instance. By default, inputs get the same name as in their nipype interface, and outputs are prefixed with an underscore (‘_’) to avoid names collisions when a trait exists both in inputs and outputs in nipype. A special trait name _spm_script_file is also used in SPM interfaces to write the matlab script. It can also be translated to a different name in this dict.

Subclasses should preferably not define an __init__ method, because it may be called twice if no precaution is taken to avoid it (a __np_init_done__ instance attribute is set once init is done the first time).

Ex:

class Smooth(NipypeProcess):
    _nipype_class_type = spm.Smooth
    _nipype_trait_mapping = {
        'smoothed_files': 'smoothed_files',
        '_spm_script_file': 'spm_script_file'}

smooth = Smooth()

Parameters:

nipype_instance (nipype interface (mandatory, except from internals)) – the nipype interface we want to wrap in capsul.
use_temp_output_dir (bool or None) – use a temp working directory during processing

_nipype_interface¶

private attribute to store the nipye interface

Type:: Interface

_nipype_module¶

private attribute to store the nipye module name

Type:: str

_nipype_class¶

private attribute to store the nipye class name

Type:: str

_nipype_interface_name¶

private attribute to store the nipye interface name

Type:: str

requirements()[source]¶

Requirements needed to run the process. It is a dictionary which keys are config/settings modules and values are requests for them.

The default implementation returns an empty dict (no requirements), and should be overloaded by processes which actually have requirements.

Ex:

{'spm': 'version >= "12" and standalone == "True"')

set_output_directory(out_dir)[source]¶

Set the process output directory.

Parameters:: out_dir (str (mandatory)) – the output directory

set_usedefault(parameter, value)[source]¶

Set the value of the usedefault attribute on a given parameter.

Parameters:

parameter (str (mandatory)) – name of the parameter to modify.
value (bool (mandatory)) – value set to the usedefault attribute

_before_run_process()[source]¶: Method to copy files before executing the process.

_run_process()[source]¶

Method that do the processing when the instance is called.

Returns:: runtime – object containing the running results
Return type:: InterfaceResult

_after_run_process(run_process_result)[source]¶: Method to clean-up temporary workspace after process execution.

classmethod help(nipype_interface, returnhelp=False)[source]¶

Method to print the full wrapped nipype interface help.

Parameters:

cls (process class (mandatory)) – a nipype process class
nipype_instance (nipype interface (mandatory)) – a nipype interface object that will be documented.
returnhelp (bool (optional, default False)) – if True return the help string message, otherwise display it on the console.

class populse_mia.user_interface.pipeline_manager.process_mia.File(value=<traits.trait_type._NoDefaultSpecifiedType object>, exists=False, resolve=False, allow_compressed=True, extensions=None, **metadata)[source]¶

Bases: BasePath

Defines a trait whose value must be a file path.

>>> from nipype.interfaces.base import File, TraitedSpec, TraitError
>>> class A(TraitedSpec):
...     foo = File()
>>> a = A()
>>> a.foo
<undefined>

>>> a.foo = '/some/made/out/path/to/file'
>>> a.foo
'/some/made/out/path/to/file'

>>> class A(TraitedSpec):
...     foo = File(exists=False, resolve=True)
>>> a = A(foo='idontexist.txt')
>>> a.foo  
'.../idontexist.txt'

>>> class A(TraitedSpec):
...     foo = File(exists=True, resolve=True)
>>> a = A()
>>> a.foo = 'idontexist.txt'  
Traceback (most recent call last):
TraitError:

>>> open('idoexist.txt', 'w').close()
>>> a.foo = 'idoexist.txt'
>>> a.foo  
'.../idoexist.txt'

>>> class A(TraitedSpec):
...     foo = File('idoexist.txt')
>>> a = A()
>>> a.foo
<undefined>

>>> class A(TraitedSpec):
...     foo = File('idoexist.txt', usedefault=True)
>>> a = A()
>>> a.foo
'idoexist.txt'

>>> class A(TraitedSpec):
...     foo = File(exists=True, resolve=True, extensions=['.txt', 'txt.gz'])
>>> a = A()
>>> a.foo = 'idoexist.badtxt'  
Traceback (most recent call last):
TraitError:

>>> a.foo = 'idoexist.txt'
>>> a.foo  
'.../idoexist.txt'

>>> class A(TraitedSpec):
...     foo = File(extensions=['.nii', '.nii.gz'])
>>> a = A()
>>> a.foo = 'badext.txt'  
Traceback (most recent call last):
TraitError:

>>> class A(TraitedSpec):
...     foo = File(extensions=['.nii', '.nii.gz'])
>>> a = A()
>>> a.foo = 'goodext.nii'
>>> a.foo
'goodext.nii'

>>> a = A()
>>> a.foo = 'idontexist.000.nii'
>>> a.foo  
'idontexist.000.nii'

>>> a = A()
>>> a.foo = 'idontexist.000.nii.gz'
>>> a.foo  
'idontexist.000.nii.gz'

_is_file = True¶

__init__(value=<traits.trait_type._NoDefaultSpecifiedType object>, exists=False, resolve=False, allow_compressed=True, extensions=None, **metadata)[source]¶: Create a File trait.

_exts = None¶

validate(objekt, name, value, return_pathlike=False)[source]¶: Validate a value change.

class populse_mia.user_interface.pipeline_manager.process_mia.InputMultiObject(trait=None, value=None, minlen=0, maxlen=9223372036854775807, items=True, **metadata)[source]¶

Bases: MultiObject

Implements a user friendly traits that accepts one or more paths to files or directories. This is the input version which always returns a list. Default value of this trait is _Undefined. It does not accept empty lists.

XXX This should only be used as a final resort. We should stick to established Traits to the extent possible.

XXX This needs to be vetted by somebody who understands traits

>>> from nipype.interfaces.base import InputMultiObject, TraitedSpec
>>> class A(TraitedSpec):
...     foo = InputMultiObject(File(exists=False))
>>> a = A()
>>> a.foo
<undefined>

>>> a.foo = '/software/temp/foo.txt'
>>> a.foo
['/software/temp/foo.txt']

>>> a.foo = ['/software/temp/foo.txt']
>>> a.foo
['/software/temp/foo.txt']

>>> a.foo = ['/software/temp/foo.txt', '/software/temp/goo.txt']
>>> a.foo
['/software/temp/foo.txt', '/software/temp/goo.txt']

_items_event = <traits.ctrait.CTrait object>¶

populse_mia.user_interface.pipeline_manager.process_mia.relax_exists_constraint(trait)[source]¶

Relax the exist constraint of a trait

Parameters:: trait (trait) – a trait that will be relaxed from the exist constraint

populse_mia.user_interface.pipeline_manager.process_mia.get_ref(obj)[source]¶: Get a regular reference to an object, whether it is already a regular reference, a weak reference, or a weak proxy which holds an access to the original reference (built using weak_proxy()). In case of a weak proxy not built using weak_proxy(), we try to get the self from a bound method of the object, namely obj.__init__.__self__, if it exists.

class populse_mia.user_interface.pipeline_manager.process_mia.Config(properties_path=None)[source]¶

Bases: object

Object that handles the configuration of the software

Contains:

Methods:

_configure_matlab_only: Configures MATLAB without SPM

_configure_matlab_spm: Configures SPM and MATLAB

_configure_mcr_only: Configures MCR without SPM

_configure_standalone_spm: Configures standalone SPM and MCR

_disable_matlab_spm: Disables all MATLAB and SPM configurations

get_admin_hash: Get the value of the hash of the admin password

get_afni_path: Returns the path of AFNI

get_ants_path: Returns the path of ANTS

getBackgroundColor: Get background color

get_capsul_config: Get CAPSUL config dictionary

get_capsul_engine: Get a global CapsulEngine object used for all operations in MIA application

getChainCursors: Returns if the “chain cursors” checkbox of the mini-viewer is activated

get_freesurfer_setup: Get freesurfer path

get_fsl_config: Returns the path of the FSL config file

get_mainwindow_maximized: Get the maximized (full-screen) flag

get_mainwindow_size: Get the main window size

get_matlab_command: Returns Matlab command

get_matlab_path: Returns the path of Matlab’s executable

get_matlab_standalone_path: Returns the path of Matlab Compiler Runtime

get_max_projects: Returns the maximum number of projects displayed in the “Saved projects” menu

get_max_thumbnails: Get max thumbnails number at the data browser bottom

get_mri_conv_path: Returns the MRIManager.jar path

get_mrtrix_path: Returns mrtrix path

getNbAllSlicesMax: Returns the maximum number of slices to display in the mini viewer

get_opened_projects: Returns the opened projects

get_projects_save_path: Returns the folder where the projects are saved

get_properties_path: Returns the software’s properties path

get_referential: Returns boolean to indicate DataViewer referential

get_resources_path: Get the resources path

getShowAllSlices: Returns if the “show all slices” checkbox of the mini viewer is activated

getSourceImageDir: Get the source directory for project images

get_spm_path: Returns the path of SPM12 (license version)

get_spm_standalone_path: Returns the path of SPM12 (standalone version)

getTextColor: Return the text color

getThumbnailTag: Returns the tag that is displayed in the mini viewer

get_use_afni: Returns the value of “use afni” checkbox in the preferences

get_use_ants: Returns the value of “use ants” checkbox in the preferences

get_use_clinical: Returns the value of “clinical mode” checkbox in the preferences

get_use_freesurfer: Returns the value of “use freesurfer” checkbox in the preferences

get_use_fsl: Returns the value of “use fsl” checkbox in the preferences

get_use_matlab: Returns the value of “use matlab” checkbox in the preferences

get_use_matlab_standalone: Returns the value of “use matlab standalone” checkbox in the preferences

get_use_mrtrix: Returns the value of “use mrtrix” checkbox in the preferences

get_user_level: Get the user level in the Capsul config

get_user_mode: Returns the value of “user mode” checkbox in the preferences

get_use_spm: Returns the value of “use spm” checkbox in the preferences

get_use_spm_standalone: Returns the value of “use spm standalone” checkbox in the preferences

getViewerConfig: Returns the DataViewer configuration (neuro or radio), by default neuro

getViewerFramerate: Returns the DataViewer framerate for automatic time running images

isAutoSave: Checks if auto-save mode is activated

isControlV1: Checks if the selected display of the controller is of V1 type

isRadioView: Checks if miniviewer in radiological orientation (if not, then it is in neurological orientation)

loadConfig: Reads the config in the config.yml file

saveConfig: Saves the config to the config.yml file

set_admin_hash: Set the password hash

set_afni_path: Set the path of the AFNI

set_ants_path: Set the path of the ANTS

setAutoSave: Sets the auto-save mode

setBackgroundColor: Sets the background color

set_capsul_config: Set CAPSUL configuration dict into MIA config

setChainCursors: Set the “chain cursors” checkbox of the mini viewer

set_clinical_mode: Set the value of “clinical mode” in the preferences

setControlV1: Set controller display mode (True if V1)

set_freesurfer_setup: Set freesurfer path

set_fsl_config: Set the path of the FSL config file

set_mainwindow_maximized: Set the maximized (fullscreen) flag

set_mainwindow_size: Set main window size

set_matlab_path: Set the path of Matlab’s executable

set_matlab_standalone_path: Set the path of Matlab Compiler Runtime

set_max_projects: Set the maximum number of projects displayed in the “Saved projects” menu

set_max_thumbnails: Set max thumbnails number at the data browser bottom

set_mri_conv_path: Set the MRIManager.jar path

set_mrtrix_path: Set the path of mrtrix

setNbAllSlicesMax: Set the maximum number of slices to display in the mini viewer

set_opened_projects: Set the opened projects

set_projects_save_path: Set the folder where the projects are saved

set_radioView: Set the orientation in miniviewer (True for radiological, False for neurological orientation)

set_referential: Set the DataViewer referential

set_resources_path: Set the resources path

setShowAllSlices: Set the “show all slices” checkbox of the mini viewer

setSourceImageDir: Set the source directory for project images

set_spm_path: Set the path of SPM12 (license version)

set_spm_standalone_path: Set the path of SPM12 (standalone version)

setTextColor: Set the text color

setThumbnailTag: Set the tag that is displayed in the mini viewer

set_use_afni: Set the value of “use afni” checkbox in the preferences

set_use_ants: Set the value of “use ants” checkbox in the preferences

set_use_freesurfer: Set the value of “use freesurfer” checkbox in the preferences

set_use_fsl: Set the value of “use fsl” checkbox in the preferences

set_use_matlab: Set the value of “use matlab” checkbox in the preferences

set_use_matlab_standalone: Set the value of “use matlab standalone” checkbox in the preferences

set_use_mrtrix: Set the value of “use mrtrix” checkbox in the preferences

set_user_mode: Set the value of “user mode” checkbox in the preferences

set_use_spm: Set the value of “use spm” checkbox in the preferences

set_use_spm_standalone: Set the value of “use spm standalone” checkbox in the preferences

setViewerConfig: Set the Viewer configuration neuro or radio

setViewerFramerate: Set the Viewer frame rate for automatic running time images

update_capsul_config: Update a global CapsulEngine object used for all operations in MIA application

capsul_engine = None¶

__init__(properties_path=None)[source]¶

Initialization of the Config class

Parameters:: properties_path – (str) If provided, the configuration file will be loaded / saved from the given directory. Otherwise, the regular heuristics will be used to determine the config path. This option allows to use an alternative config directory (for tests for instance).

_configure_matlab_only(matlab_path: str) → None[source]¶

Configures MATLAB without SPM, ensuring that only MATLAB is used.

Parameters:: matlab_path – (str) The directory path of the MATLAB installation.

_configure_matlab_spm(spm_dir, matlab_path)[source]¶

Configures SPM to use the specified SPM directory with a MATLAB installation.

Parameters:

spm_dir – (str) The directory path of the SPM installation.
matlab_path – (str) The directory path of the MATLAB installation.

_configure_mcr_only(mcr_dir: str) → None[source]¶

Configures MATLAB Compiler Runtime (MCR) without SPM, ensuring that only MCR is used.

Parameters:: mcr_dir – (str) The directory path of the MATLAB Compiler Runtime (MCR).

_configure_standalone_spm(spm_dir, mcr_dir)[source]¶

Configures standalone SPM to use the specified SPM and MATLAB Compiler Runtime (MCR) directories.

Parameters:

spm_dir – (str) The directory path of the standalone SPM installation.
mcr_dir – (str) The directory path of the MATLAB Compiler Runtime (MCR).

_disable_matlab_spm() → None[source]¶: Disables all MATLAB and SPM configurations, ensuring that neither MATLAB nor SPM is used.

get_admin_hash()[source]¶

Retrieves the hashed admin password from the configuration.

Returns:: The hashed admin password if found in config, False if not present in config.

get_afni_path()[source]¶

Get the AFNI path.

Returns:: (str) Path to AFNI, or “” if unknown.

get_ants_path()[source]¶

Get the ANTS path.

Returns:: (str) Path to ANTS, or “” if unknown.

getBackgroundColor()[source]¶

Get background color.

Returns:: (str) Background color, or “” if unknown.

get_capsul_config(sync_from_engine=True)[source]¶

Retrieve and construct the Capsul configuration dictionary.

This function builds a configuration dictionary for Capsul, incorporating settings for various neuroimaging tools and processing engines. It manages configurations for tools like SPM, FSL, FreeSurfer, MATLAB, AFNI, ANTs, and MRTrix.

The function first retrieves local settings for each tool from the Mia preferences, then constructs the appropriate configuration structure. If requested, it can synchronize the configuration with the current Capsul engine state.

Parameters:

sync_from_engine – (bool) If True, synchronizes the configuration with the current Capsul engine settings after building the base configuration.

Returns:

(dict) A nested dictionary containing the complete Capsul configuration, structured with the following main sections:

engine_modules: List of available processing modules

engine: Contains global and environment-specific settings, as well as configurations specific to certain tools (SPM, FSL, etc.)

Private functions:

_configure_spm: Configure SPM settings.
_configure_tool: Configure various neuroimaging settings (e.g. ‘fsl’, ‘afni’, etc.)

static get_capsul_engine()[source]¶

Get or create a global CapsulEngine singleton for Mia application operations.

The engine is created only once when first needed (lazy initialization). Subsequent calls return the same instance.

Returns:: (CapsulEngine) The global CapsulEngine instance.

getChainCursors()[source]¶

Get the value of the checkbox ‘chain cursor’ in miniviewer.

Returns:: (bool) Value of the checkbox.

get_freesurfer_setup()[source]¶

Get the freesurfer path.

Returns:: (str) Path to freesurfer, or “” if unknown.

get_fsl_config()[source]¶

Get the FSL config file path.

Returns:: (str) Path to the fsl/etc/fslconf/fsl.sh file.

get_mainwindow_maximized()[source]¶

Get the maximized (fullscreen) flag.

Returns:: (bool) Maximized (fullscreen) flag.

get_mainwindow_size()[source]¶

Get the main window size.

Returns:: (list) Main window size.

get_matlab_command()[source]¶

Retrieves the appropriate Matlab command based on the configuration.

Returns:: (str) The Matlab executable path or None if no path is specified.

get_matlab_path()[source]¶

Get the path to the matlab executable.

Returns:: (str) A path.

get_matlab_standalone_path()[source]¶

Get the path to matlab compiler runtime.

Returns:: (str) A path.

get_max_projects()[source]¶

Retrieves the maximum number of projects displayed in the “Saved projects” menu.

Returns:: (int) The maximum number of projects. Defaults to 5 if not specified.

get_max_thumbnails()[source]¶

Retrieves the maximum number of thumbnails displayed in the mini-viewer at the bottom of the data browser.

Returns:: (int) The maximum number of thumbnails. Defaults to 5 if not specified.

get_mri_conv_path()[source]¶

Get the MRIManager.jar path.

Returns:: (str) A path.

get_mrtrix_path()[source]¶

Get the mrtrix path.

Returns:: (str) A path.

getNbAllSlicesMax()[source]¶

Get number the maximum number of slices to display in the miniviewer.

Returns:: (int) Maximum number of slices to display in miniviewer.

get_opened_projects()[source]¶

Get opened projects.

Returns:: (list) Opened projects.

get_projects_save_path()[source]¶

Get the path where projects are saved.

Returns:: (str) A path.

get_properties_path()[source]¶

Retrieves the path to the folder containing the “processes” and “properties” directories of Mia.

The properties path is defined in the configuration_path.yml file, located in ~/.populse_mia.

In user mode, the path is retrieved from the properties_user_path parameter.
In developer mode, the path is retrieved from the properties_dev_path parameter.

If outdated parameters (mia_path, mia_user_path) are found, they are automatically updated in the configuration file.

Returns:: (str) The absolute path to the properties folder.

get_referential()[source]¶

Retrieves the chosen referential from the anatomist_2 data viewer.

Returns:: (str) “0” for World Coordinates, “1” for Image ref.

get_resources_path()[source]¶

Get the resources path.

Returns:: (str) A path.

getShowAllSlices()[source]¶

Get whether the show_all_slices parameters was enabled or not in the miniviewer.

Returns:: (bool) True if the show_all_slices parameters was enabled.

getSourceImageDir()[source]¶

Get the source directory for project images.

Returns:: (str) A path.

get_spm_path()[source]¶

Get the path of SPM.

Returns:: (str) A path.

get_spm_standalone_path()[source]¶

Get the path to the SPM12 standalone version.

Returns:: (str) A path.

getTextColor()[source]¶

Get the text color.

Returns:: (str) The text color.

getThumbnailTag()[source]¶

Get the tag of the thumbnail displayed in the miniviewer.

Returns:: (str) The tag of the thumbnail displayed in miniviewer.

get_use_afni()[source]¶

Get the value of “use afni” checkbox in the preferences.

Returns:: (bool) The value of “use afni” checkbox.

get_use_ants()[source]¶

Get the value of “use ants” checkbox in the preferences.

Returns:: (bool) The value of “use ants” checkbox.

get_use_clinical()[source]¶

Get the clinical mode in the preferences.

Returns:: (bool) The clinical mode.

get_use_freesurfer()[source]¶

Get the value of “use freesurfer” checkbox in the preferences.

Returns:: (bool) The value of “use freesurfer” checkbox.

get_use_fsl()[source]¶

Get the value of “use fsl” checkbox in the preferences.

Returns:: (bool) The value of “use fsl” checkbox.

get_use_matlab()[source]¶

Get the value of “use matlab” checkbox in the preferences.

Returns:: (bool) The value of “use matlab” checkbox.

get_use_matlab_standalone()[source]¶

Get the value of “use matlab standalone” checkbox in the preferences.

Returns:: (bool) The value of “use matlab standalone” checkbox.

get_use_mrtrix()[source]¶

Get the value of “use mrtrix” checkbox in the preferences.

Returns:: (bool) The value of “use mrtrix” checkbox.

get_user_level()[source]¶

Get the user level in the Capsul config.

Returns:: (int) The user level in the Capsul config.

get_user_mode()[source]¶

Get if user mode is disabled or enabled in the preferences.

Returns:: (bool) If True, the user mode is enabled.

get_use_spm()[source]¶

Get the value of “use spm” checkbox in the preferences.

Returns:: (bool) The value of “use spm” checkbox.

get_use_spm_standalone()[source]¶

Get the value of “use spm standalone” checkbox in the preferences.

Returns:: (bool) The value of “use spm standalone” checkbox.

getViewerConfig()[source]¶

Get the viewer config “neuro” or “radio”, “neuro” by default.

Returns:: (str) The viewer config (“neuro” or “radio”).

getViewerFramerate()[source]¶

Get the Viewer framerate.

Returns:: (str) The Viewer framerat (ex. “5”).

isAutoSave()[source]¶

Get if the auto-save mode is enabled or not.

Returns:: (bool) If True, auto-save mode is enabled.

isControlV1()[source]¶

Gets whether the controller display is of type V1.

Returns:: (bool) If True, V1 controller display.

isRadioView()[source]¶

Get if the display in miniviewer is in radiological orientation.

Returns:: (bool) If True, radiological orientation, otherwise neurological orientation.

loadConfig()[source]¶

Read the config from config.yml file.

Attempts to read an encrypted YAML configuration file from the properties directory, decrypt it using Fernet encryption, and parse it as YAML.

Returns:: (dict) Parsed configuration from the YAML file. Returns empty dict if parsing fails.

saveConfig()[source]¶

Save the current parameters in the config.yml file.

Encrypts and writes the current configuration (self.config) to config.yml using Fernet encryption. Creates the necessary directory structure if it doesn’t exist. After saving, updates the capsul configuration.

set_admin_hash(admin_hash)[source]¶

Set the password hash.

Parameters:: admin_hash – A string.

set_afni_path(path)[source]¶

Set the AFNI path.

Parameters:: path – (str) A path.

set_ants_path(path)[source]¶

Set the ANTS path

Parameters:: path – (str) A path.

setAutoSave(save)[source]¶

Set auto-save mode.

Parameters:: save – A boolean.

setBackgroundColor(color)[source]¶

Set background color and save configuration.

Parameters:: color – Color string (‘Black’, ‘Blue’, ‘Green’, ‘Grey’, ‘Orange’, ‘Red’, ‘Yellow’, ‘White’)

set_capsul_config(capsul_config_dict)[source]¶

Update Mia configuration with Capsul settings and synchronize tools configuration.

Called after editing Capsul config (via File > Mia preferences > Pipeline tab > Edit CAPSUL config) to synchronize Capsul settings with Mia preferences. Configures various neuroimaging tools (AFNI, ANTs, FSL, etc.) based on the Capsul engine configuration.

Parameters:: capsul_config_dict – Dictionary containing Capsul configuration.

Structure of capsul_config_dict:

{
    'engine': {
        'environment_name': {...configuration...}
    },
    'engine_modules': [...]
}

Private function:

_get_module_config: Extracts module configuration from the global Capsul configuration.

setChainCursors(chain_cursors)[source]¶

Set the value of the checkbox ‘chain cursor’ in the mini viewer.

Parameters:: chain_cursors – A boolean.

set_clinical_mode(clinical_mode)[source]¶

Enable or disable clinical mode.

Parameters:: clinical_mode – A boolean.

setControlV1(controlV1)[source]¶

Set controller display mode (True if V1).

Parameters:: controlV1 – A boolean.

set_freesurfer_setup(path)[source]¶

Set the freesurfer config file.

Parameters:: path – (str) Path to freesurfer/FreeSurferEnv.sh.

set_fsl_config(path)[source]¶

Set the FSL config file.

Parameters:: path – (str) Path to fsl/etc/fslconf/fsl.sh.

set_mainwindow_maximized(enabled)[source]¶

Set the maximized (full-screen) flag.

Parameters:: enabled – A boolean.

set_mainwindow_size(size)[source]¶

Set main window size.

Parameters:: size – A list of two integers.

set_matlab_path(path)[source]¶

Set the path of Matlab’s executable.

Parameters:: path – (str) A path.

set_matlab_standalone_path(path)[source]¶

Set the path of Matlab Compiler Runtime.

Parameters:: path – (str) A path.

set_max_projects(nb_max_projects)[source]¶

Set the maximum number of projects displayed in the “Saved projects” menu.

Parameters:: nb_max_projects – An integer.

set_max_thumbnails(nb_max_thumbnails)[source]¶

Set max thumbnails number at the data browser bottom.

Parameters:: nb_max_thumbnails – An integer.

set_mri_conv_path(path)[source]¶

Set the MRIManager.jar path.

Parameters:: path – (str) A path.

set_mrtrix_path(path)[source]¶

Set the mrtrix path.

Parameters:: path – (str) A path.

setNbAllSlicesMax(nb_slices_max)[source]¶

Set the number of slices to display in the mini-viewer.

Parameters:: nb_slices_max – (int) Maximum number of slices to display.

set_opened_projects(new_projects)[source]¶

Set the list of opened projects and saves the modification.

Parameters:: new_projects – (list[str]) A list of paths.

set_projects_save_path(path)[source]¶

Set the folder where the projects are saved.

Parameters:: path – (str) A path.

set_radioView(radio_view)[source]¶

Set the radiological / neurological orientation in mini viewer.

True for radiological
False for neurological

Parameters:: radio_view – A boolean.

set_referential(ref)[source]¶

Set the referential to “image Ref” or “World Coordinates” in anatomist_2 data viewer.

Parameters:: ref – (str) “0” for World Coordinates, “1” for Image Ref.

set_resources_path(path)[source]¶

Set the resources path.

Parameters:: path – (str) A path.

setShowAllSlices(show_all_slices)[source]¶

Set the show_all_slides setting in miniviewer.

Parameters:: show_all_slices – A boolean.

setSourceImageDir(source_image_dir)[source]¶

Set the source directory for project images.

Parameters:: source_image_dir – (str) A path.

set_spm_path(path)[source]¶

Set the path of SPM (license version).

Parameters:: path – (str) A path.

set_spm_standalone_path(path)[source]¶

Set the path of SPM (standalone version).

Parameters:: path – (str) A path.

setTextColor(color)[source]¶

Set text color and save configuration.

Parameters:: color – Color string (‘Black’, ‘Blue’, ‘Green’, ‘Grey’, ‘Orange’, ‘Red’, ‘Yellow’, ‘White’)

setThumbnailTag(thumbnail_tag)[source]¶

Set the tag that is displayed in the mini-viewer.

Parameters:: thumbnail_tag – A string.

set_use_afni(use_afni)[source]¶

Set the value of “use_afni” checkbox in the preferences.

Parameters:: use_afni – A boolean.

set_use_ants(use_ants)[source]¶

Set the value of “use_ants” checkbox in the preferences.

Parameters:: use_ants – A boolean.

set_use_freesurfer(use_freesurfer)[source]¶

Set the value of “use_freesurfer” checkbox in the preferences.

Parameters:: use_freesurfer – A boolean.

set_use_fsl(use_fsl)[source]¶

Set the value of “use_fsl” checkbox in the preferences.

Parameters:: use_fsl – A boolean.

set_use_matlab(use_matlab)[source]¶

Set the value of “use matlab” checkbox in the preferences.

Parameters:: use_matlab – A boolean.

set_use_matlab_standalone(use_matlab_standalone)[source]¶

Set the value of “use_matlab_standalone” checkbox in the preferences.

Parameters:: use_matlab – A boolean.

set_use_mrtrix(use_mrtrix)[source]¶

Set the value of “use_mrtrix” checkbox in the preferences.

Parameters:: use_mrtrix – A boolean.

set_user_mode(user_mode)[source]¶

Enable or disable user mode.

Parameters:: user_mode – A boolean.

set_use_spm(use_spm)[source]¶

Set the value of “use spm” checkbox in the preferences.

Parameters:: use_spm – A boolean.

set_use_spm_standalone(use_spm_standalone)[source]¶

Set the value of “use spm standalone” checkbox in the preferences.

Parameters:: use_spm_standalone – A boolean.

setViewerConfig(config_NeuRad)[source]¶

sets user’s configuration neuro or radio for data_viewer.

neuro: neurological
radio: radiological

Parameters:: config_NeuRad – A string.

setViewerFramerate(im_sec)[source]¶

sets user’s framerate for data_viewer.

Parameters:: im_sec – (int) Number of images per second.

update_capsul_config()[source]¶

Updates the global CapsulEngine object used for all operations in the Mia application.

The CapsulEngine is created once when needed and updated each time the configuration is saved. This method ensures that all necessary engine modules are loaded and configurations are properly imported from the saved settings.

Returns:: (capsul.engine.CapsulEngine) The updated CapsulEngine object, or None if the engine is not initialized.

class populse_mia.user_interface.pipeline_manager.process_mia.PopUpInheritanceDict(values, node_name, plug_name, iterate)[source]¶

Bases: QDialog

Dialog for selecting tag inheritance between input and output plugs.

This dialog allows users to select which input plug should pass its tags to a specific output plug, or to choose to ignore tag inheritance altogether.

Methods:

_setup_buttons: Set up action buttons for the dialog
_setup_radio_buttons: Set up radio buttons for each input option
ok_clicked: Event when ok button is clicked
okall_clicked: Event when Ok all button is clicked
on_clicked: Event when radiobutton is clicked
ignoreall_clicked: Event when ignore all plugs button is clicked
ignore_clicked: Event when ignore button is clicked
ignore_node_clicked: Event when ignore all nodes button is clicked

__init__(values, node_name, plug_name, iterate)[source]¶

Initialize the inheritance selection dialog.

Parameters:

(dict) (values) – Dict mapping input names (keys) to their paths (values)
(str) (plug_name) – Name of the current node
(str) – Name of the current output plug
(bool) (iterate) – Boolean indicating if the choice applies to iterations

_setup_buttons(node_name, plug_name, layout)[source]¶

Set up action buttons for the dialog.

Parameters:

node_name – Name of the current node
plug_name – Name of the current output plug
layout – Layout to add the buttons to

_setup_radio_buttons(values, layout)[source]¶

Set up radio buttons for each input option.

Parameters:

values – Dict mapping input names to their paths
layout – Layout to add the radio buttons to

ok_clicked()[source]¶

Handle OK button click.

Accepts the dialog with current selection applied to current plug.

okall_clicked()[source]¶

Handle ‘OK for all output plugs’ button click.

Accepts the dialog with current selection applied to all output plugs.

on_clicked()[source]¶

Handle radio button selection event.

Updates the currently selected input value and key.

ignoreall_clicked()[source]¶

Handle ‘Ignore for all output plugs’ button click.

Accepts the dialog with tag inheritance ignored for all output plugs.

ignore_clicked()[source]¶

Handle Ignore button click.

Accepts the dialog with tag inheritance ignored for current plug.

ignore_node_clicked()[source]¶

Handle ‘Ignore for all nodes in the pipeline’ button click.

Accepts the dialog with tag inheritance ignored for the entire pipeline.

populse_mia.user_interface.pipeline_manager.process_mia.update_auto_inheritance(node, job=None)[source]¶

Automatically infer database tags for output parameters from input parameters.

Single input case: When only one input parameter has a database
value, all outputs inherit from this input.
Multiple inputs with same value: When multiple inputs exist but
have identical database values, fallback to single input behavior.
Ambiguous case: When multiple inputs have different database
values, track all possible inheritance sources for user resolution.

The process attribute auto_inheritance_dict is filled with these values. It’s a dict with the shape:

{output_filename: <input_spec>}

output_filename is the relative filename in the database

<input_spec> can be:

a string: filename
a dict:
```
{input_param: input_filename}
```

auto_inheritance_dict is built automatically, and is used as a fallback to ProcessMIA inheritance_dict, built “manually” (specialized for each process) in the ProcessMIA.list_outputs() when the latter does not exist, or does not specify what an output inherits from.

If ambiguities still subsist, the Mia infrastructure will ask the user how to solve them, which is not very convenient, and error-prone, thus should be avoided.

Parameters:

node – The node (typically a process or process node) whose inputs and outputs are analyzed for tag inheritance.
job – An optional job object containing parameter values to override or populate the node’s inputs and outputs. Defaults to None.

Return (dict or None):

Auto-inheritance mapping if successful and no job provided, None if no inheritance can be determined or job is provided (in which case the job object is updated in-place).

class populse_mia.user_interface.pipeline_manager.process_mia.MIAProcessCompletionEngine(process, name, fallback_engine)[source]¶

Bases: ProcessCompletionEngine

A specialized completion engine for all processes within the Populse_mia context.

This engine handles both PopulseMIA processes and NipypeProcess instances with special consideration for their unique requirements:

PopulseMIA processes use their list_outputs method to generate outputs based on input parameters, primarily using filename patterns rather than attributes.
NipypeProcess instances have their MATLAB/SPM settings configured from the application configuration.

The engine also manages project-specific parameters including “project” and “output_directory” when available in the study configuration.

The completion system is augmented with Mia database integration, where attributes from input parameters (called “tags” in Mia) are added to the completion attributes.

This engine tracks completed processes in the correct order, enabling other operations to be performed in the same sequence later.

Contains:

Method:

_complete_mia_process: Complete parameters for Mia-specific
processes.
_complete_standard_process: Complete parameters for standard
(non-Mia) processes.
complete_attributes_with_database: Augments the Capsul
completion system attributes associated with a process.
complete_nipype_common: Set Nipype parameters for SPM.
complete_parameters: Completes file parameters from
given inputs parameters.
complete_parameters_mia: Completion for ProcessMIA
instances.
get_attribute_values: Get attribute values from the fallback
engine.
get_path_completion_engine: Get the path completion engine from
the fallback engine.
get_project: Get the project associated with the process
path_attributes: Get path attributes from the fallback engine.
remove_switch_observe: Reimplemented since it is expects
in switches completion engine.

__init__(process, name, fallback_engine)[source]¶

Initialize the Mia process completion engine.

Parameters:

process – The process instance to be completed.
(str) (name) – The name of the process.
fallback_engine – The fallback engine to use when MIA-specific completion is not applicable.

_complete_standard_process(process, process_inputs, complete_iterations)[source]¶

Complete parameters for standard (non-Mia) processes.

Parameters:

process – The process to complete.
(dict) (process_inputs) – Parameters to set on the process.
(bool) (complete_iterations) – Whether to complete iteration nodes.

_complete_mia_process(process, process_inputs, complete_iterations)[source]¶

Complete parameters for Mia-specific processes.

Parameters:

process – The Mia process to complete.
(dict) (process_inputs) – Parameters to set on the process.
(bool) (complete_iterations) – Whether to complete iteration nodes.

complete_attributes_with_database(process_inputs=None)[source]¶

Augment the completion attributes with values from the Mia database.

Queries the database for attributes associated with input parameters and adds them to the completion attributes if matches are found.

Parameters:: (dict) (process_inputs) – Parameters to be set on the process.
Returns:: The augmented attributes collection.

static complete_nipype_common(process, output_dir=True)[source]¶

Configure Nipype/SPM parameters for a process.

Sets MATLAB/SPM paths, commands, and project-specific parameters based on the configuration.

Parameters:

process – The process to configure.
(bool) (output_dir) – If False, the output_directory attribute value is not initialised.

complete_parameters(process_inputs=None, complete_iterations=True)[source]¶

Complete process parameters based on input values.

This method handles both standard Capsul processes and Mia-specific processes, applying the appropriate completion strategy for each.

Parameters:

(dict) (process_inputs) – Parameters to be set on the process. May include regular parameters and completion attributes (under ‘capsul_attributes’ key).
(bool) (complete_iterations) – If False, iteration nodes in pipelines will not complete their parameters. This prevents modification of the input pipeline and avoids redundant iterations completion that will be done again during workflow building.

complete_parameters_mia(process_inputs=None, iteration=False, verbose=False)[source]¶

Complete parameters for ProcessMIA instances.

Uses the ProcessMIA.list_outputs method to generate output parameters based on input values and sets the inheritance_dict for data indexation.

Parameters:

(dict) (process_inputs) – Parameters to set on the process.
(bool) (verbose) – Whether this completion is for an iteration node.
(bool) – If true, makes the method verbose

get_attribute_values()[source]¶

Get attribute values from the fallback engine.

Returns:: The attribute values collection.

get_path_completion_engine()[source]¶

Get the path completion engine from the fallback engine.

Returns:: The path completion engine.

static get_project(process)[source]¶

Get the project associated with a process.

Parameters:: process – The process to get the project for.
Returns:: The associated project or None if not found.

path_attributes(filename, parameter=None)[source]¶

Get path attributes from the fallback engine.

Parameters:

(str) (parameter) – The filename to get attributes for.
(str) – The parameter name associated with the filename.

Returns:

The path attributes.

remove_switch_observer(observer=None)[source]¶

Remove a switch observer from the fallback engine.

Parameters:: observer – The observer to remove.
Returns:: The result from the fallback engine.

class populse_mia.user_interface.pipeline_manager.process_mia.MIAProcessCompletionEngineFactory[source]¶

Bases: ProcessCompletionEngineFactory

Specialization of the ProcessCompletionEngineFactory for the Populse Mia context.

This factory is identified by factory_id = "mia_completion" and is activated in a StudyConfig instance by setting the following 2 parameters:

study_config.attributes_schema_paths += [
‘populse_mia.user_interface.pipeline_manager.process_mia’

] study_config.process_completion = ‘mia_completion’

Once activated, the completion system is applied to all processes, distinguishing between MIA and Nipype processes. For standard processes, additional database operations are performed before invoking the underlying completion system (such as FOM or others).

Contains:

Method:

get_completion_engine: get a ProcessCompletionEngine instance for a given process/node

factory_id = 'mia_completion'¶

get_completion_engine(process, name=None)[source]¶

Retrieves a ProcessCompletionEngine instance for the given process or node.

Parameters:

Node) (process (Process or) – The process or node for which to get the completion engine.
optional) (name (str,) – An optional name for the completion engine.

Return (ProcessCompletionEngine):

A completion engine instance associated with the process.

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessMIA(*args, **kwargs)[source]¶

Bases: Process

Extends the Capsul Process class to customize execution for Mia bricks.

This class provides specialized methods for Mia bricks, including process initialization, output handling, and trait management.

Note

Type ‘ProcessMIA.help()’ for a full description of this process parameters.
Type ‘<ProcessMIA>.get_input_spec()’ for a full description of this process input trait types.
Type ‘<ProcessMIA>.get_output_spec()’ for a full description of this process output trait types.

ignore_node = False¶

ignore = {}¶

key = {}¶

__init__(*args, **kwargs)[source]¶

Initializes the process instance with default attributes.

Parameters:

(tuple) (args) – Positional arguments passed to the parent class.
(dict) (kwargs) – Keyword arguments passed to the parent class

_add_field_to_collections(database_schema, collection, tag_def)[source]¶

Add a new field to the specified collection in the database.

Parameters:

database_schema – The database schema context used for modifying collections.
(str) (collection) – The name of the collection to which the field should be added.
(dict) (tag_def) –
Dictionary containing the field definition with the following keys: - ‘name’ (str): The name of the field. - ‘field_type’ (str): The type of the field. - ‘description’ (str): A description of the

field.
- ’visibility’ (str): The visibility status of
  the field.
- ’origin’ (str): The origin of the field.
- ’unit’ (str): The unit associated with the
  field.
- ’default_value’ (Any): The default value of
  the field.

_add_or_modify_tags(own_tags, current_values, initial_values, field_names)[source]¶

Add new tags or modify existing tag values in the current and initial collections.

Parameters:

(list[dict]) (own_tags) – List of tags to be added or modified, where each tag is a dictionary with ‘name’, ‘value’, ‘description’, etc., keys.
(dict) (initial_values) – Dictionary storing the current tag values.
(dict) – Dictionary storing the initial tag values.
(set[str]) (field_names) – Set of field names that exist in the database schema.

_all_values_identical(values_dict)[source]¶

Checks if all dictionaries in values_dict have identical content.

Parameters:: (dict) (values_dict) – A dictionary where each value is expected to be comparable to the others.
Return (bool):: True if all values in values_dict are identical or if the dictionary is empty, otherwise False.

_after_run_process(run_process_result)[source]¶

Retrieve output values when the process is a NipypeProcess.

Parameters:: run_process_result – The result of the process execution. (unused)

_find_plug_for_output(out_file)[source]¶

Find the plug name associated with the given output file.

Parameters:: (str) (out_file) – The output file to search for in user traits.
Return (str | None):: The name of the plug (trait) if found, otherwise None.

_get_relative_path(file_path, base_dir)[source]¶

Converts an absolute file path to a relative path based on the project folder.

Parameters:

(str) (base_dir) – The absolute path of the file.
(str) – The base directory to make the path relative to.

Return (str):

The relative file path.

_remove_tags(tags2del, current_values, initial_values, out_file)[source]¶

Remove specified tags from value dictionaries and the database.

Parameters:

(list[str]) (tags2del) – List of tag names to be removed.
(dict) (initial_values) – Dictionary storing the current tag values.
(dict) – Dictionary storing the initial tag values.
(str) (out_file) – The output file associated with the tags being removed.

_resolve_inheritance_ambiguity(all_current_values, all_initial_values, in_files, node_name, plug_name, out_file)[source]¶

Resolves ambiguity when multiple input files could provide tags.

This method applies a series of resolution strategies in order: 1. If all input files have identical tag values, the first input is

selected.

If a previously stored selection rule exists, it is used.
If neither condition applies, the user is prompted to manually resolve the ambiguity, and their decision is stored for future use.

Parameters:

(dict) (in_files) – A dictionary containing the current values for each possible input file.
(dict) – A dictionary containing the initial values for each possible input file.
(dict) – A mapping of input file indices to their corresponding file paths.
(str) (out_file) – The name of the processing node.
None) (plug_name (str |) – The name of the plug (trait) causing the ambiguity.
(str) – The output file for which inheritance needs to be resolved.

_run_process()[source]¶: Execute the specific run method for ProcessMIA subclasses.

_save_tag_values(rel_out_file, current_values, initial_values)[source]¶

Save tag values to the CURRENT and INITIAL database collections.

Parameters:

(str) (rel_out_file) – The relative path of the output file used as the document’s primary key.
(dict) (initial_values) – Dictionary containing the current tag values to be saved.
(dict) – Dictionary containing the initial tag values to be saved.

init_default_traits()[source]¶: Initialize required traits for Nipype or Capsul processes.

init_process(int_name)[source]¶

Instantiate the process attribute given a process identifier.

Parameters:: (str) (int_name) – A process identifier used to fetch the process instance.

list_outputs()[source]¶: Reset and override process outputs.

load_nii(file_path, scaled=True, matlab_like=False)[source]¶

Load a NIfTI image and return its header and data, optionally adjusting for MATLAB conventions.

MATLAB and Python (in particular NumPy) treat the order of dimensions and the origin of the coordinate system differently. MATLAB uses main column order (also known as Fortran order). NumPy (and Python in general) uses the order of the main rows (C order). For a 3D array data(x, y, z) in MATLAB, the equivalent in NumPy is data[y, x, z]. MATLAB and NumPy also handle the origin of the coordinate system differently: MATLAB’s coordinate system starts with the origin in the lower left-hand corner (as in traditional matrix mathematics). NumPy’s coordinate system starts with the origin in the top left-hand corner. When taking matlab_like=True as argument, the numpy matrix is rearranged to follow MATLAB conventions. Using scaled=False generates a raw unscaled data matrix (as in MATLAB with header = loadnifti(fnii) and header.reco.data).

Parameters:

(str) (file_path) – The path to a NIfTI file.
(bool) (matlab_like) – If True the data is scaled.
(bool) – If True the data is rearranged to match the order of the dimensions and the origin of the coordinate system in Matlab.

make_initResult()[source]¶: Generate the initialization result dictionary.

relax_nipype_exists_constraints()[source]¶: Relax the ‘exists’ constraint of the process.inputs traits.

requirements()[source]¶: Return the process requirements using MIA’s requirement attribute.

run_process_mia()[source]¶: Execute a customized run for ProcessMIA subclasses.

tags_inheritance(in_file, out_file, node_name=None, own_tags=None, tags2del=None)[source]¶

Inherit and manage data tags from input file(s) to an output file.

This method handles the inheritance of metadata tags from one or more input files to an output file. It also allows adding new tags, modifying existing ones, or deleting unwanted tags in the process.

Notes: This method performs inheritance in two ways: 1. Immediate inheritance during process execution 2. Deferred inheritance by storing inheritance information for later

use during workflow generation (addresses issue #290, #310)

In ambiguous cases (multiple input files), the method will either: - Use previously stored inheritance rules - Prompt the user for a decision if no rule exists - Auto-resolve if all inputs have identical tag values

Parameters:

dict) (own_tags (list of) –
Source of tag inheritance. Either: - A string representing a single input

file path (unambiguous case)
- A dictionary mapping plug names to corresponding input file paths (ambiguous case)
(str) (node_name) – Path of the output file that will inherit the tags.
(str) – Name of the processing node in the workflow.
dict) –
Tags to be added or modified. Each dictionary must contain: - “name”: Tag identifier - “field_type”: Data type of the tag - “description”: Human-readable

description
- ”visibility”: Boolean or visibility
  level
- ”origin”: Source of the tag
- ”unit”: Unit of measurement
  (if applicable)
- ”default_value”: Default value
- ”value”: Current value to set
str) (tags2del (list of) – Tags to be deleted from the output file.