populse_mia.utils.utils

Module that contains multiple functions used across Mia.

Functions

check_python_version()	Checks if the Python version is at least 3.10.
check_value_type(value, value_type[, ...])	Checks the type of new value in a table cell (QTableWidget).
dict4runtime_update(runtime_dict, project, ...)	Update a dictionary with tag values from the project's current collection.
get_db_field_value(project, document, field)	Retrieve the value of a specific field for a document from the project's database.
get_document_names(project, collection)	Retrieves the names of all documents in the specified collection from the project's database.
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.
get_shown_tags(project)	Retrieves the list of tags that are marked as 'shown' in the project's database.
get_value(project, collection, file_name, field)	Retrieves the value of a specific field from a document in the given collection.
launch_mia(MainWindow, Project, ...)	Launch and run the Mia software application.
message_already_exists()	Displays a message box to tell that a project name already exists.
remove_document(project, collection, documents)	Removes one or multiple documents from the specified collection in the given project's database.
safe_connect(signal, slot)	Connect a Qt signal to a slot, ensuring a single connection.
safe_disconnect(signal, slot)	Disconnect a Qt signal from a slot if connected.
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.
set_filters_directory_as_default(dialog)	Sets the filters directory as default (Json files).
set_item_data(item, value, value_type)	Set the data of a browser item according to the expected value type.
set_projects_directory_as_default(dialog, Config)	Sets the projects directory as default.
table_to_database(value, value_type)	Prepares the value to the database based on its type.
type_name(t)	Returns the name of a type or a string representation for generic aliases.
update_auto_inheritance(node[, job])	Automatically infer database tags for output parameters from input parameters.
verCmp(first_ver, sec_ver, comp)	Version comparator.
verify_processes(nipypeVer, miaProcVer, ...)	Install or update to the last version available on the station, for nipype, capsul and mia_processes processes libraries.
verify_setup(Config, dev_mode[, pypath, ...])	Check and try to correct the configuration if necessary.

Classes

PackagesInstall()

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

class populse_mia.utils.utils.PackagesInstall

Bases: object

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

Contains:

Methods:

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

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

• class_name (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’}}}

Return type:

dict

populse_mia.utils.utils._is_valid_date(date_str, date_format)

Checks if a string matches the given date format.

Parameters:

• date_str (str) – The date string to validate.

• date_format (str) – The expected date format.

Returns:

True if the string matches the format, False otherwise.

Return type:

bool

populse_mia.utils.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.utils.check_value_type(value, value_type, is_subvalue=False)

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

Parameters:

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

• value_type (type | types.GenericAlias) – Expected Python type of value (for example, int, str, float, bool, list[int], list[str], etc.)

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

Returns:

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

Return type:

bool

populse_mia.utils.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:

• runtime_dict (dict) – Dictionary used to transfer data from list_outputs method to the run_process_mia method within the bricks of the mia_processes library.

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

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

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

populse_mia.utils.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.

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

• field (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.utils.get_document_names(project, collection)

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

Parameters:

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

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

Returns:

A list of document names in the collection.

Return type:

list[str]

populse_mia.utils.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 (Project) – The project instance containing the database.

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

Returns:

A list of field names in the collection.

Return type:

list[str]

populse_mia.utils.utils.get_shown_tags(project)

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

Parameters:

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

Returns:

A list of tag names marked as shown.

Return type:

list[str]

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

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

Parameters:

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

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

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

• field (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.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:

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

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

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

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

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

Contains:

Inner functions:

• _clean_up: Perform application cleanup tasks.

• _cleanup_and_quit: Clean up application state and terminate the Qt event loop.

• _my_excepthook: Handle uncaught exceptions.

• _restore_terminal: Restore the terminal to a sane state.

• _signal_handler: Handle termination signals to ensure graceful shutdown.

• _verify_saved_projects: Verify the existence of saved projects on disk.

populse_mia.utils.utils.message_already_exists()

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

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

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

Parameters:

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

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

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

populse_mia.utils.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.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.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.

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

• tag_to_add (dict) –

  A dictionary describing the field with these keys:

  • ’name’,

  • ’value’,

  • ’default_value’

  • ’description’

  • ’field_type’

  • ’origin’

  • ’unit’

  • ’visibility’

populse_mia.utils.utils.set_filters_directory_as_default(dialog)

Sets the filters directory as default (Json files).

Parameters:

dialog (QFileDialog) – Current file dialog.

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

Set the data of a browser item according to the expected value type.

This function converts value according to value_type before storing it in item using setData(). It supports primitive Python types (e.g., int, str, float and bool) as well as datetime, date, time and lists of these types.

Parameters:

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

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

• value_type (type | types.GenericAlias) – 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]).

Contains:

Inner functions:

• prepare_value: Prepares the input value according to its expected type.

populse_mia.utils.utils.set_projects_directory_as_default(dialog, Config)

Sets the projects directory as default.

Parameters:

• dialog (QFileDialog) – Current file dialog.

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

populse_mia.utils.utils.table_to_database(value, value_type)

Prepares the value to the database based on its type.

Parameters:

• value (Any) – Value to convert.

• value_type (type | types.GenericAlias) – Value type.

Returns:

The value converted for the database.

Return type:

Any

populse_mia.utils.utils.type_name(t) → str

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

Parameters:

t (type | types.GenericAlias) – 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]').

Return type:

str

populse_mia.utils.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 a dictionary filled with these values {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.

Returns:

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

Return type:

dict | None

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

Version comparator.

Compares two package 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:

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

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

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

Returns:

True if the comparison condition is satisfied, False otherwise.

Return type:

bool

Contains:

Inner functions:

• normalise: Transform a version of a package to a corresponding list of integer.

populse_mia.utils.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 (str) – nipype version currently installed.

• miaProcVer (str) – mia_processes version currently installed.

• capsulVer (str) – capsul version currently installed.

• Config (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:

Inner functions:

• _deepCompDic: Keep the previous config existing before packages update.

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

Check and try to correct the configuration if necessary.

Parameters:

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

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

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

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

Contains:

Inner functions:

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