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.

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.MIAProcessCompletionEngine(process, name, fallback_engine)

Bases: ProcessCompletionEngine

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

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

• ProcessMIA 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:

Methods:

• _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)

Initialize the Mia process completion engine.

Parameters:

• process – The process instance to be completed.

• name – (str) 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)

Complete parameters for standard (non-Mia) processes.

Parameters:

• process – The process to complete.

• process_inputs – (dict) Parameters to set on the process.

• complete_iterations – (bool) Whether to complete iteration nodes.

_complete_mia_process(process, process_inputs, complete_iterations)

Complete parameters for Mia-specific processes.

Parameters:

• process – The Mia process to complete.

• process_inputs – (dict) Parameters to set on the process.

• complete_iterations – (bool) Whether to complete iteration nodes.

complete_attributes_with_database(process_inputs=None)

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:

process_inputs – (dict) Parameters to be set on the process.

Returns:

The augmented attributes collection.

static complete_nipype_common(process, output_dir=True)

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.

• output_dir – (bool) If False, the output_directory attribute value is not initialised.

complete_parameters(process_inputs=None, complete_iterations=True)

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:

• process_inputs – (dict) Parameters to be set on the process. May include regular parameters and completion attributes (under ‘capsul_attributes’ key).

• complete_iterations – (bool) 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)

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:

• process_inputs – (dict) Parameters to set on the process.

• iteration – (bool) Whether this completion is for an iteration node.

• verbose – (bool) If true, makes the method verbose

get_attribute_values()

Get attribute values from the fallback engine.

Returns:

The attribute values collection.

get_path_completion_engine()

Get the path completion engine from the fallback engine.

Returns:

The path completion engine.

static get_project(process)

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)

Get path attributes from the fallback engine.

Parameters:

• filename – (str) The filename to get attributes for.

• parameter – (str) The parameter name associated with the filename.

Returns:

The path attributes.

remove_switch_observer(observer=None)

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

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:

Methods:

• get_completion_engine: get a ProcessCompletionEngine instance

for a given process/node.

factory_id = 'mia_completion'

get_completion_engine(process, name=None)

Retrieves a ProcessCompletionEngine instance for the given process or node.

Parameters:

• process – (Process or Node) The process or node for which to get the completion engine.

• name – (str, optional) An optional name for the completion engine.

Returns:

(ProcessCompletionEngine) A completion engine instance associated with the process.

class populse_mia.user_interface.pipeline_manager.process_mia.ProcessMIA(*args, **kwargs)

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.

Contains:

Methods:

• _add_field_to_collections: Add a new field to the specified collection in the database.

• _add_or_modify_tags: Add new tags or modify existing tag values in the database.

• _all_values_identical: Checks if all dictionaries have identical content

• _after_run_process: Try to recover the output values, when the calculation has been delegated to a process in ProcessMIA.

• _find_plug_for_output: Find the plug name associated with the given output file.

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

• _remove_tags: Remove specified tags from value dictionaries and the database.

• _resolve_inheritance_ambiguity: Resolves ambiguity when multiple input files could provide tags.

• _run_process: Call the run_process_mia method in the ProcessMIA subclass.

• _save_tag_values: Save tag values to the database.

• init_default_traits: Automatically initialise necessary parameters for nipype or capsul.

• init_process: Instantiation of the process attribute given a process identifier.

• list_outputs: Override the outputs of the process.

• load_nii: Return the header and the data of a nibabel image object.

• make_initResult: Make the final dictionary for outputs, inheritance and requirement from the initialisation of a brick.

• relax_nipype_exists_constraints: Relax the exists constraint of the process.inputs traits.

• requirements: Capsul Process.requirements() implementation using Mia’s ProcessMIA.requirement attribute.

• run_process_mia: Implements specific runs for ProcessMia subclasses.

• tags_inheritance: Create tags for data.

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)

Initializes the process instance with default attributes.

Parameters:

• args – (tuple) Positional arguments passed to the parent class.

• kwargs – (dict) Keyword arguments passed to the parent class

_add_field_to_collections(database_schema, collection, tag_def)

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

Parameters:

• database_schema – The database schema context used for modifying collections.

• collection – (str) The name of the collection to which the field should be added.

• tag_def –

  (dict) 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)

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

Parameters:

• own_tags – (list[dict]) List of tags to be added or modified, where each tag is a dictionary with ‘name’, ‘value’, ‘description’, etc., keys.

• current_values – (dict) Dictionary storing the current tag values.

• initial_values – (dict) Dictionary storing the initial tag values.

• field_names – (set[str]) Set of field names that exist in the database schema.

_all_values_identical(values_dict)

Checks if all dictionaries in values_dict have identical content.

Parameters:

values_dict – (dict) A dictionary where each value is expected to be comparable to the others.

Returns:

(bool) True if all values in values_dict are identical or if the dictionary is empty, otherwise False.

_after_run_process(run_process_result)

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)

Find the plug name associated with the given output file.

Parameters:

out_file – (str) The output file to search for in user traits.

Returns:

(str | None) The name of the plug (trait) if found, otherwise None.

_get_relative_path(file_path, base_dir)

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

Parameters:

• file_path – (str) The absolute path of the file.

• base_dir – (str) The base directory to make the path relative to.

Returns:

(str) The relative file path.

_remove_tags(tags2del, current_values, initial_values, out_file)

Remove specified tags from value dictionaries and the database.

Parameters:

• tags2del – (list[str]) List of tag names to be removed.

• current_values – (dict) Dictionary storing the current tag values.

• initial_values – (dict) Dictionary storing the initial tag values.

• out_file – (str) 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)

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.

2. If a previously stored selection rule exists, it is used.

3. If neither condition applies, the user is prompted to manually resolve the ambiguity, and their decision is stored for future use.

Parameters:

• all_current_values – (dict) A dictionary containing the current values for each possible input file.

• all_initial_values – (dict) A dictionary containing the initial values for each possible input file.

• in_files – (dict) A mapping of input file indices to their corresponding file paths.

• node_name – (str) The name of the processing node.

• plug_name – (str | None) The name of the plug (trait) causing the ambiguity.

• out_file – (str) The output file for which inheritance needs to be resolved.

_run_process()

Execute the specific run method for ProcessMIA subclasses.

_save_tag_values(rel_out_file, current_values, initial_values)

Save tag values to the CURRENT and INITIAL database collections.

Parameters:

• rel_out_file – (str) The relative path of the output file used as the document’s primary key.

• current_values – (dict) Dictionary containing the current tag values to be saved.

• initial_values – (dict) Dictionary containing the initial tag values to be saved.

init_default_traits()

Initialize required traits for Nipype or Capsul processes.

init_process(int_name)

Instantiate the process attribute given a process identifier.

Parameters:

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

list_outputs()

Reset and override process outputs.

load_nii(file_path, scaled=True, matlab_like=False)

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:

• file_path – (str) The path to a NIfTI file.

• scaled – (bool) If True the data is scaled.

• matlab_like – (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()

Generate the initialization result dictionary.

relax_nipype_exists_constraints()

Relax the ‘exists’ constraint of the process.inputs traits.

requirements()

Return the process requirements using MIA’s requirement attribute.

run_process_mia()

Execute a customized run for ProcessMIA subclasses.

tags_inheritance(in_file, out_file, node_name=None, own_tags=None, tags2del=None)

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.

Note

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.

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:

• in_file –

  (str or dict) 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).

• out_file – (str) Path of the output file that will inherit the tags.

• node_name – (str) Name of the processing node in the workflow.

• own_tags –

  (list of 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.

• tags2del – (list of str) Tags to be deleted from the output file.