populse_mia.utils

Utilities and tools used across Mia

Contains:

Modules:

• utils.py

class populse_mia.utils.PackagesInstall

Bases: object

Helps make a pipeline package available in the Mia pipeline library recursively.

Contains:

Method:

• __init__: constructor

• add_package: provide recursive representation of a package

_already_loaded = {'capsul.pipeline.pipeline_nodes.Node', 'capsul.pipeline.pipeline_nodes.PipelineNode', 'capsul.pipeline.pipeline_nodes.ProcessNode', 'capsul.process.process.FileCopyProcess', 'capsul.process.process.NipypeProcess', 'capsul.process.process.Process', 'populse_mia.user_interface.pipeline_manager.process_mia.ProcessMIA'}

__init__()

Initializes the package registry.

add_package(module_name, class_name=None)

Recursively adds a package and its subpackages/modules to the Mia pipeline library.

Parameters:

• (str) (class_name) – Name of the module to add to the pipeline library.

• (str) – Specific class to add (optional). Only this pipeline will be added to the pipeline library.

Returns:

dictionary of dictionaries containing package/subpackages/pipelines status. ex: {package: {subpackage: {pipeline: ‘process_enabled’}}}

populse_mia.utils.check_python_version()

Checks if the Python version is at least 3.10.

Raises:

RuntimeError – If the Python version is lower than 3.10.

populse_mia.utils.check_value_type(value, value_type, is_subvalue=False)

Checks the type of new value in a table cell (QTableWidget).

Parameters:

• (str) (value) – Value of the cell (always a str, can be a string representation of a list)

• (type) (value_type) – Expected type (can be list[str], list[int], etc.)

• (bool) (is_subvalue) – Whether the value is a subvalue of a list.

Returns:

True if the value is valid to replace the old one, False otherwise

populse_mia.utils.dict4runtime_update(runtime_dict, project, db_filename, *tags)

Update a dictionary with tag values from the project’s current collection.

This function populates the runtime_dict with values associated with the specified tags from the COLLECTION_CURRENT database collection. If a tag is not present or its value is None, it is assigned the string “Undefined”. Date values are converted to ISO-formatted strings.

Parameters:

• (dict) (runtime_dict) – Dictionary used to transfer data from list_outputs to run_process_mia.

• project – The project instance containing the database.

• (str) (db_filename) – The name of the database file to query.

• tags – Variable number of tag names to retrieve from the database.

populse_mia.utils.get_db_field_value(project, document, field)

Retrieve the value of a specific field for a document from the project’s database.

Parameters:

• (Project) (project) – The current project instance containing the database.

• (str) (field) – The absolute path to the document.

• (str) – The name of the field whose value should be retrieved.

Returns:

The value of the specified field for the document in the current collection.

populse_mia.utils.get_document_names(project, collection)

Retrieves the names of all documents in the specified collection from the project’s database.

Parameters:

• project – The project instance containing the database.

• (str) (collection) – The name of the collection to query.

Returns (list[str]):

A list of document names in the collection.

populse_mia.utils.get_field_names(project, collection)

Retrieves the list of field names (i.e., column names) for documents in the specified collection of the project’s database.

Parameters:

• project – The project instance containing the database.

• (str) (collection) – The name of the collection to inspect.

Returns (list[str]):

A list of field names in the collection.

populse_mia.utils.get_shown_tags(project)

Retrieves the list of tags that are marked as ‘shown’ in the project’s database.

Parameters:

project – The project instance containing the database.

Returns (list[str]):

A list of tag names marked as shown.

populse_mia.utils.get_value(project, collection, file_name, field)

Retrieves the value of a specific field from a document in the given collection.

Parameters:

• project – The project instance containing the database.

• (str) (field) – The name of the collection containing the document.

• (str) – The name of the document (typically the file name).

• (str) – The name of the field whose value is to be retrieved.

Returns:

The value of the specified field, or None if not found.

populse_mia.utils.launch_mia(MainWindow, Project, SavedProjects, Config, args)

Launch and run the Mia software application.

This function is the main entry point. It:

• Installs a custom sys.excepthook to handle uncaught exceptions.

• Prevents multiple instances unless explicitly allowed.

• Verifies saved projects consistency.

• Performs project cleanup safely before destruction.

• Creates and displays the main Qt window.

• Ensures idempotent cleanup on exit or crash.

All state is local and shared via closures.

Parameters:

• (class) (Config) – The main window class to be instantiated.

• (class) – The project class to be instantiated.

• (class) – The class that manages all projects saved in Mia.

• (class) – The class that manages Mia’s configuration and properties.

• (argparse.Namespace) (args) – Parsed command-line arguments.

populse_mia.utils.message_already_exists()

Displays a message box to tell that a project name already exists.

populse_mia.utils.remove_document(project, collection, documents)

Removes one or multiple documents from the specified collection in the given project’s database.

Parameters:

• project – The project instance containing the database.

• (str) (collection) – The name of the collection from which documents will be removed.

• list[str]) (documents (str or) – A single document name or a list of document names to remove.

populse_mia.utils.safe_connect(signal, slot)

Connect a Qt signal to a slot, ensuring a single connection.

First disconnects signal from slot (if connected) to avoid duplicate connections, then connects them. This guarantees that the slot is connected exactly once.

Parameters:

• signal – The Qt signal to (re)connect.

• slot – The slot (callable) to connect to the signal.

populse_mia.utils.safe_disconnect(signal, slot)

Disconnect a Qt signal from a slot if connected.

Attempts to disconnect signal from slot and silently ignores the error raised when the connection does not exist. This makes the operation idempotent and safe to call multiple times.

Parameters:

• signal – The Qt signal to disconnect from.

• slot – The slot (callable) previously connected to the signal.

populse_mia.utils.set_db_field_value(project, document, tag_to_add)

Create or update a field and its value for a document in the project’s database.

If the specified field does not exist in the current and initial collections, it is added to both. The field is then assigned a value for the given document.

Parameters:

• (Project) (project) – The project instance containing the database and schema.

• (str) (document) – The absolute path of the document.

• (dict) (tag_to_add) – A dictionary describing the field with keys: ‘name’, ‘value’, ‘default_value’, ‘description’, ‘field_type’, ‘origin’, ‘unit’, and ‘visibility’.

populse_mia.utils.set_filters_directory_as_default(dialog)

Sets the filters directory as default (Json files)

Parameters:

(QFileDialog) (dialog) – current file dialog

populse_mia.utils.set_item_data(item, value, value_type)

Sets the data for a given item in the data browser based on the expected type.

This function prepares the input value according to the specified value_type, converting it into a format suitable for PyQt’s QVariant. It supports both primitive types (e.g., int, str, float) and more complex types like datetime, date, time, and lists of these types.

Parameters:

• (QStandardItem) (item) – The item to update (expected to support setData method).

• (Any) (value) – The new value to set for the item.

• (Type) (value_type) – The expected type of the value, which can be a standard Python type (e.g., str, int, float, bool) or a typing-based list type (e.g., list[int], list[datetime]).

populse_mia.utils.set_projects_directory_as_default(dialog, Config)

Sets the projects directory as default.

Parameters:

• (QFileDialog) (dialog) – current file dialog.

• Config – The class that manages Mia’s configuration and properties.

populse_mia.utils.table_to_database(value, value_type)

Prepares the value to the database based on its type.

Parameters:

• (Any) (value) – Value to convert.

• (Type) (value_type) – Value type.

Return (Any):

The value converted for the database.

populse_mia.utils.type_name(t)

Returns the name of a type or a string representation for generic aliases.

Parameters:

(Any) (t) – The type to get the name or representation for. This can be a regular type (e.g., str, list) or a generic alias (e.g., list[str]).

Returns:

The name of the type (e.g., ‘str’) or the string representation of the generic alias (e.g., ‘list[str]’).

populse_mia.utils.update_auto_inheritance(node, job=None)

Automatically infer database tags for output parameters from input parameters.

1. Single input case: When only one input parameter has a database

   value, all outputs inherit from this input.

2. Multiple inputs with same value: When multiple inputs exist but

   have identical database values, fallback to single input behavior.

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

populse_mia.utils.verCmp(first_ver, sec_ver, comp)

Version comparator.

Compares two versions according to the specified comparator:

• ‘eq’: Returns True if the first version is equal to the second.

• ‘sup’: Returns True if the first version is greater than or equal

  to the second.

• ‘inf’: Returns True if the first version is less than or equal to

  the second.

Parameters:

• (str) (comp) – The first version to compare (e.g., ‘0.13.0’).

• (str) – The second version to compare (e.g., ‘0.13.0’).

• (str) – The comparator to use (‘sup’, ‘inf’, ‘eq’).

Returns:

True if the comparison condition is satisfied, False otherwise.

Contains:

Private function:

• normalise: transform a version of a package to a corresponding list of integer

populse_mia.utils.verify_processes(nipypeVer, miaProcVer, capsulVer, Config)

Install or update to the last version available on the station, for nipype, capsul and mia_processes processes libraries.

Parameters:

• nipypeVer – nipype version currently installed (str).

• miaProcVer – mia_processes version currently installed (str).

• capsulVer – capsul version currently installed (str).

• Config – The class that manages Mia’s configuration and properties.

By default, Mia provides three process libraries in the pipeline library (available in Pipeline Manager tab). The nipype, given as it is because it is developed by another team (https://github.com/nipy/nipype), and mia_processes, capsul which are developed under the umbrella of populse (https://github.com/populse/mia_processes). When installing Mia in user mode, these three libraries are automatically installed on the station. The idea is to use the versioning available with pypi (https://pypi.org/). Thus, it is sufficient for the user to change the version of the library installed on the station (pip install…) to also change the version available in Mia. Indeed, when starting Mia, the verify_processes function will update the nipype, capsul and mia_processes libraries in the pipeline library accordingly. Currently, it is mandatory to have nipype, capsul and mia_processes installed in the station. All this information, as well as the installed versions and package paths are saved in the properties_path/properties/process_config.yml file. When an upgrade or downgrade is performed for a package, the last configuration used by the user is kept (if a pipeline was visible, it remains so and vice versa). However, if a new pipeline is available in the new version it is automatically marked as visible in the library.

Contains:

Private function:

• _deepCompDic: keep the previous config existing before packages update

populse_mia.utils.verify_setup(Config, dev_mode, pypath=None, dot_mia_config='/home/econdami/.populse_mia/configuration_path.yml')

Check and try to correct the configuration if necessary.

Parameters:

• Config – The class that manages Mia’s configuration and properties.

• (bool) (dev_mode) – the current developer mode. (True: dev, False: user)

• (list) (pypath) – List of paths for the capsul config.

• (str) (dot_mia_config) – Path to the configuration_path.yml file.

Contains:

Private function:

• _browse_properties_path: the user define the properties_path

  parameter

• _cancel_clicked: exit form Mia

• _make_default_config: make default configuration

• _save_yml_file: save data in a YAML file

• _verify_miaConfig: check the config and try to fix if necessary

Modules

populse_mia.utils.utils

Module that contains multiple functions used across Mia.