.. _download-results-label:

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 :ref:`login-label`.

List all Analyses
------------------------------

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

.. code-block:: python

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

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

    - :code:`_id`: Analysis ID. Analysis unique identifier.
    - :code:`name`: Name of the analysis.
    - :code:`script_name`: Code of the analysis.
    - :code:`version`: Version of the analysis.
    - :code:`state`: State of the analysis. One of:

        - :code:`running`: Analysis being executed.
        - :code:`completed`: Finished analysis.
        - :code:`waiting`: Analysis waiting to be executed.
        - :code:`pending`: Analysis waiting to be executed.
        - :code:`exception`: Analysis finished with errors.
    - :code:`owner`: Owner of the analysis.
    - :code:`in_container_id`: Input Container ID.
    - :code:`out_container_id`: Output Continer ID.
    - :code:`qa_status`: QC Status of the analysis.
    - :code:`qa_comments`: QC Comments of the analysis.
    - :code:`patient_secret_name`: Subject ID in which the analysis was executed.
    - :code:`ssid`: Session ID in which the analysis was executed.
    - :code:`settings`: Settings used to execute the analysis.

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

    - :code:`super_analysis_type`: Workflow analyses will have this key equal to 1.
    - :code:`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 :ref:`paa-label`.

.. _search-analysis-label:

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:

.. code-block:: python

    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:

    - :code:`p_n`: Applies the search to the Analysis Name.
    - :code:`type`: Applies the search to the Analysis code and version. Must have the following structure: :code:`f"{ANALYSIS_CODE}:{VERSION}"`.
    - :code:`analysis_code`: Applies the search to the Analysis code.
    - :code:`from_d`: Retrieves the analyses started after the provided date.
    - :code:`to_d`: Retrieves the analyses started before the provided date.
    - :code:`qa_status`: Retrieves the analyses whose QC Status is one of: :code:`QCStatus.PASS`, :code:`QCStatus.FAIL`, or :code:`QCStatus.UNDETERMINED`.
    - :code:`secret_name`: Applies the search to the Subject ID.
    - :code:`with_child_analysis`: Retrieves all analyses or only workflows.
    - :code:`id`: Applies the search to the Analysis ID. Unique identifier of the analysis.
    - :code:`state`: Applies the search to the Analysis State detailed above.
    - :code:`username`: Applies the search to the user that started the analysis.

An example realistic search criteria is shown next:

.. code-block:: python

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

.. code-block:: python

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

.. code-block:: python

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

where :code:`files_metadata` is a list of dictionaries, each belonging to a file
available in the container with the information described in section
:ref:`file-metadata-label`.

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

.. code-block:: python

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

.. figure:: figs/download_results/1.webp

    Example results the files available in the output container of the analysis shown in :ref:`start-analysis-label`.