Analyses Execution

Within the QMENTA Platform, the uploaded image data can be processed 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 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 sufficient processing resources are available. Nevertheless, the QMENTA Platform also supports manual steps that require operator attention. For example, some analyses require visual confirmation of output data quality or segmentation results. The operator might also be permitted to manually modify the segmentation if 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

To start an analysis in the active Project, first select the session by retrieving its Container ID 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"]

Define any other input parameters via a settings dictionary:

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

where param1 and param2 are example input settings. Each analysis has its own set of parameters.

Start the analysis:

# 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",
)

script_name is the analysis code as defined in its specifications, version its version, and analysis_name and analysis_description are optional fields.

Note

The script_name is a unique identification code that may be referred to differently across the platform (analysis_code, input_data_type, or type). See Data Handling and Search Analyses.

Once started, analysis_id contains the Analysis ID (unique identifier).

Note

You can only start an analysis if the input settings unequivocally match the available data in the input containers.

Complete example for WMH Lesion Segmentation Workflow:

analysis_settings = {
    "input": container_id,
    "skull_stripping": "1",
    "resampling": "1",
    "denoising": "1",
}

script_name='wmh_lesion_segmentation_workflow'
version='1.0'

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

The analysis appears in QMENTA Platform as:

This workflow consists of three processing tools executed sequentially:

Analysis duration depends on the analysis type, priority, and available resources.

Note

The Medical Image Data analysis (section Data Handling) is exclusively for data upload.

Start an Analysis Choosing the Input Files

Starting an analysis when there is only one set of files that satisfy the input requirements of the analysis was described in previous section :ref:’start-analysis-label’. However, sometimes there are several files that satisfy the input requirements of the analysis, hence, the actual file/s to be input to the analysis has to be selected.

For instance, in the previous example starting the WMH Lesion Segmentation Workflow it might happen that the session contains several T2-FLAIR weighted-images. In order to choose what T2-FLAIR image is to be used the code should be as follows:

# 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})",
    ignore_file_selection = False,
)

where ignore_file_selection = False will give you the option to select the input files. In the terminal, you will get a message similar to:

· File name: 2D_FLAIR_AX.zip
· File name: 2D_FLAIR_COR.zip
· File name: 2D_FLAIR_SAG.zip

and will be requested to input the file selection in the same terminal.

>? 2D_FLAIR_AX.zip

Subsequently, the analysis will start as previously explained using the selected input.

Note

The analysis will be cancelled if ignore_file_selection = True and there are multiple files that satisfy its input requirements.

Delete an Analysis

Delete finalized analyses (successful or failed) via Analysis ID:

project.delete_analysis(analysis_id)

Note

Deleting a workflow also deletes all its child analyses.

Restart an Analysis

Failed workflows can be restarted, keeping finished tools and restarting missing ones:

Restart process:

project.delete_analysis(analysis_id_child) # Remove failed child
project.restart_analysis(analysis_id_wf) # Restart workflow

Result after restart:

Note

Only workflows can be restarted, not individual tools. Only your owned analyses can be restarted.

Quality Check (QC) Status

Analyses have QC Status metadata (qa_status and qa_comments):

from qmenta.client.Project import QCStatus

# Read QC status
qc_status, qc_comments = project.get_qc_status_analysis(analysis_id)

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

QCStatus values: - PASS - FAIL - UNDETERMINED

QC Status visualization:

Get Analysis Logs

Download Analysis Logs:

project.get_analysis_log(analysis_id)

Note

Only logs from your proprietary tools can be downloaded. Workflows don’t have Analysis Logs.

Next Steps

After analysis completion: - Results Handling – Retrieve and store analysis outputs.