Analyses Execution¶

Within the QMENTA Platform, the uploaded image data can be processed in order to obtain a particular set of output data, or results. The image processing tools used, whether implemented in singular units or organized into a sequence of units (i.e., workflows), are collectively termed analyses. A comprehensive list of analyses available in the QMENTA Platform is available in the QMENTA Imaging Biomarker Marketplace.

Note

You may execute already available, in-house analyses, or integrate and execute your own. See Image Analysis Management for further details.

Analyses can be fully automatic, meaning that, once started, the QMENTA Platform will schedule their different steps as soon as the sufficient processing resources are available. Nevertheless, the QMENTA Platform also supports manual steps that require the attention of an operator. For example, in some analyses it is required to visually confirm the quality of the output data or the quality of an automatically performed segmentation. Further, in this latter case the operator might be permitted to manually modify the segmentation if deemed necessary.

Note

Manual steps of analyses can only be executed manually on the QMENTA Platform.

In this section, you will learn how to programmatically execute analyses on the QMENTA Platform.

To begin, log in and access a Project following the steps in Logging In and Activating a QMENTA Project.

Start an Analysis¶

In order to start an analysis in the active Project in the QMENTA Platform, the first step is to select the session in which the analysis will be executed. First, retrieve the Container ID of the session as explained in section Data Searches.

# Define the Subject ID and Session ID
subject_name = "0001"
ssid = "1"

# Retrieve Subject Information
subject = [subject for subject in project.subjects_metadata if  subject["patient_secret_name"] == subject_name and subject["ssid"] == ssid]
container_id = subjects[0]["container_id"]

Next, we need to define any other input parameters that might be needed via the following settings dictionary:

# Define input settings for the analysis
analysis_settings = {
    "input": container_id,
    "param2": value,
    "param2": value,
}

where param1 and param2 are example input settings of the analysis. Each analysis has its own set of parameters as defined in their specifications.

Lastly, we can proceed to start the analysis via:

# Start analysis
analysis_id = project.start_analysis(
    script_name='Code of the analysis.',
    version='Version of the analysis',
    settings=analysis_settings,
    analysis_name="Analysis name",
    analysis_description="Analysis description",
)

where script_name is the corresponding code of the analysis as defined in its specifications, version its version, and analysis_name and analysis_description are optional fields to specifically define a new name and description of the analysis, respectively.

Note

The script_name is a unique identification code of the type of an analysis. Nevertheless, throughout both the QMENTA Platform and the QMENTA Client API this identification code will have a different naming convention depending on the method to use. It can be one of: script_name, analysis_code, input_data_type, or type. See for instance: Data Handling and Search Analyses.

Once the analysis is started analysis_id will contain the Analysis ID (i.e., unique identifier of the analysis).

Note

You can only start an analysis via the QMENTA Client API if the input settings of the analysis unequivocally match the available data in the input containers.

See next a complete example of how to start the WMH Lesion Segmentation Workflow.

# Define input settings for the analysis
analysis_settings = {
    "input": container_id,
    "skull_stripping": "1",
    "resampling": "1",
    "denoising": "1",
}

# Define code and version of the analysis to start.
script_name='wmh_lesion_segmentation_workflow',
version='1.0',

# Start analysis
analysis_id = project.start_analysis(
    script_name=script_name,
    version=version,
    settings=analysis_settings,
    analysis_name = f"{script_name} (v.{version})",
)

Upon execution, the above analysis is shown in the QMENTA Platform as follows:

_images/13.webp — Example analysis finalized in the QMENTA Platform.¶

In the above example, the overall analysis is a workflow composed of three processing tools executed sequentially. The workflow name is shown in dark blue while the tools are shown in light gray. As such, in the QMENTA Platform workflows are a sequence of tools executed sequentially or in parallel. The flow of the above example is shown next.

_images/21.webp — Example flow-diagram of a workflow. In this case, it consists on the sequential execution of three tools.¶

The duration of an analysis will depend on the analysis executed, the priority of both the analysis and the user and the resources available.

Note

The Medical Image Data analysis explained in section Data Handling is exclusively used for the upload of data to the QMENTA Platform.

Delete an Analysis¶

Any analysis considered finalized - either because its execution finished successfully or because it failed-, can be deleted from the QMENTA Platform via the Analysis ID.

project.delete_analysis(analysis_id)

Note

If the analysis to be deleted is a workflow all its child analyses will be deleted too.

Restart an Analysis¶

When a workflow fails and its child analyses have been removed, the workflow can be restarted. The finished tools within the workflow will be kept and the missing ones (which probably previously failed) will start at due time. This process maintains the flow of the workflow.

Note

Only workflows can be restarted. Tools can not be restarted given that they are considered as single processing units. You can start the execution of another tool analysis instead.

For example, see next a failed workflow:

_images/4.webp — Example failed workflow.¶

And see next how to restart it:

project.delete_analysis(analysis_id_child) # Remove failed child analysis

project.restart_analysis(analysis_id_wf) # Restart workflow

where analysis_id_child and analysis_id_wf correspond to the Analysis ID of the tool and the workflow, respectively.

The final status of the workflow in the QMENTA Platform would look like this:

_images/5.webp — Workflow in execution after restarting it.¶

Upon restarting the workflow, the execution of the tools will continue.

Note

Only the analyses you own can be restarted by your user.

Quality Check (QC) Status¶

In the same way that data sessions have a Quality Check (QC) Status (as defined in section Quality Check (QC) Status), analyses also have a QC Status that can be used to define if the analysis execution passed or failed from a quality perspective.

The QC Status related metadata (qa_status and qa_comments) of an analysis have specific methods to read and modify it.

from qmenta.client.Project import QCStatus

# Reading the QC status related metadata
qc_status, qc_comments = project.get_qc_status_analysis(analysis_id)

# Modifying the QC status related metadata.
qc_comments = "The quality of the analysis is incorrect."
qc_status = QCStatus.FAIL
project.set_qc_status_analysis(analysis_id, qc_status, qc_comments)

where qc_comments is a string and qc_status is a value class QCStatus which can be either of:

PASS

FAIL

UNDETERMINED

See next how the QC Status is visualized in the QMENTA Platform.

_images/3.webp — Example analysis finalized in the QMENTA Platform in which the QC Status was set to `PASS`.¶

Get Analysis Logs¶

You can download the Analysis Logs via:

# Download Analysis Log
project.get_analysis_log(analysis_id)

Note

You can only download the logs generated by your proprietary tools.

Note

Workflows do not have an Analysis Log.

Next Steps¶

Once the analysis is completed you can proceed to:

Results Handling – Retrieve and store analysis outputs.