.. _launch-analysis-label:

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 <https://catalog.qmenta.com/>`_.

.. note::
   You may execute already available, in-house analyses, or integrate and execute your own. See `Image Analysis Management <https://support.qmenta.com/knowledge/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 :ref:`login-label`.

.. _start-analysis-label:

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

.. code-block:: python

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

.. code-block:: python

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

where :code:`param1` and :code:`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:

.. code-block:: python

    # 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 :code:`script_name` is the corresponding code of the analysis as defined
in its specifications, :code:`version` its version, and :code:`analysis_name` and
:code:`analysis_description` are optional fields to specifically define a new
name and description of the analysis, respectively.

.. note::
   The :code:`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: :code:`script_name`, :code:`analysis_code`, :code:`input_data_type`, or :code:`type`. See for instance: :ref:`data-upload-label` and :ref:`search-analysis-label`.

Once the analysis is started :code:`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**.

.. code-block:: python

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

.. figure:: figs/launch_analyses/1.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.

.. figure:: figs/launch_analyses/2.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 :ref:`data-upload-label` 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.

.. code-block:: python

    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:

.. figure:: figs/launch_analyses/4.webp

    Example failed workflow.

And see next how to restart it:

.. code-block:: python

    project.delete_analysis(analysis_id_child) # Remove failed child analysis

    project.restart_analysis(analysis_id_wf) # Restart workflow

where :code:`analysis_id_child` and :code:`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:

.. figure:: figs/launch_analyses/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 :ref:`qc-subjects-label`),
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 (:code:`qa_status` and :code:`qa_comments`) of
an analysis have specific methods to read and modify it.

.. code-block:: python

    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 :code:`qc_comments` is a string and :code:`qc_status` is a value class
:class:`QCStatus` which can be either of:

    - :code:`PASS`
    - :code:`FAIL`
    - :code:`UNDETERMINED`

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

.. figure:: figs/launch_analyses/3.webp

    Example analysis finalized in the QMENTA Platform in which the QC Status was set to :code:`PASS`.

Get Analysis Logs
-----------------

You can download the Analysis Logs via:

.. code-block:: python

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

- :ref:`download-results-label` – Retrieve and store analysis outputs.