Results Handling

Upon execution of an analysis in the QMENTA Platform, you can search through the whole list of analyses to identify specific ones, and download the desired results.

In this section, you will learn how to programmatically search analyses and download results from the QMENTA Platform.

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

List all Analyses

You can retrieve the list of analyses within the active Project via:

# Retrieve the list of analyses
analyses = project.list_analysis()

where analyses is a list of dictionaries, each dictionary belonging to a specific Analysis. The dictionary will contain important keys such as:

• _id: Analysis ID. Analysis unique identifier.

• name: Name of the analysis.

• script_name: Code of the analysis.

• version: Version of the analysis.

• state: State of the analysis. One of:

  • running: Analysis being executed.

  • completed: Finished analysis.

  • waiting: Analysis waiting to be executed.

  • pending: Analysis waiting to be executed.

  • exception: Analysis finished with errors.

• owner: Owner of the analysis.

• in_container_id: Input Container ID.

• out_container_id: Output Continer ID.

• qa_status: QC Status of the analysis.

• qa_comments: QC Comments of the analysis.

• patient_secret_name: Subject ID in which the analysis was executed.

• ssid: Session ID in which the analysis was executed.

• settings: Settings used to execute the analysis.

Further, depending on the analysis type one of the following keys will be present:

• super_analysis_type: Workflow analyses will have this key equal to 1.

• super_analysis: Tool analyses that are part of a workflow will have this key, containing a dictionary with information relating to the parent workflow.

If a tool analysis does not belong to a workflow it will not have either of the above keys. This is the case in the analysis execution shown in Protocol Adherence Automation Analysis.

Search Analyses

It is possible to apply a search criteria to initially filter the list of analyses retrieved. The search criteria is a dictionary that has the following structure:

search_criteria = {
    "p_n": str or None,
    "type": str or None,
    "analysis_code": str or None,
    "from_d": str or None,
    "to_d": str or None,
    "qa_status": str or None,
    "secret_name": str or None,
    "with_child_analysis": bool or None,
    "id": str or None,
    "state": str or None,
    "username": str or None,
}

where:

• p_n: Applies the search to the Analysis Name.

• type: Applies the search to the Analysis code and version. Must have the following structure: f"{ANALYSIS_CODE}:{VERSION}".

• analysis_code: Applies the search to the Analysis code.

• from_d: Retrieves the analyses started after the provided date.

• to_d: Retrieves the analyses started before the provided date.

• qa_status: Retrieves the analyses whose QC Status is one of: QCStatus.PASS, QCStatus.FAIL, or QCStatus.UNDETERMINED.

• secret_name: Applies the search to the Subject ID.

• with_child_analysis: Retrieves all analyses or only workflows.

• id: Applies the search to the Analysis ID. Unique identifier of the analysis.

• state: Applies the search to the Analysis State detailed above.

• username: Applies the search to the user that started the analysis.

An example realistic search criteria is shown next:

# Define search criteria
search_condition = {
    "type": "wmh_lesion_segmentation_workflow:1.0",
    "from": "17.01.2025"
    "state": "completed"
}

# Retrieve the list of analyses
analyses = project.list_analysis(search_condition=search_condition)

The above search will retrieve a list of all the completed analyses available in the active Project with the code belonging to the WMH Lesion Segmentation Workflow and started after the provided date.

Download Results

After retrieval of the desired analyses you can obtain their generated files by reading them from the corresponding container, as follows:

# Retrieve Analysis
search_condition = {
    "id": 1215504,
}
analysis = project.list_analysis(search_condition=search_condition)[0]

# Get Output Container ID
container_id = analysis["out_container_id"]

# List of files available in the container
files = project.list_container_files(container_id)
print(f"List of files available in container '{container_id}': {', '.join(files)}.")

You can also obtain all the metadata of those files via:

# List of files and their metadata
files_metadata = project.list_container_files_metadata(container_id)

where files_metadata is a list of dictionaries, each belonging to a file available in the container with the information described in section File-level Metadata.

Lastly, you can download any of those files as follows:

# Download first file of the list
project.download_file(
        container_id,
        files_metadata[0]["name"],
    )

The example above downloads the first file available in the container storing the output of the selected analysis.

See next an example of the files available in the output container of an analysis.

Example results the files available in the output container of the analysis shown in Start an Analysis.