.. _launch-analysis-label:

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

.. _start-analysis-label:

Start an Analysis
-----------------

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

Define any other input parameters via a settings dictionary:

.. code-block:: python

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

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

Start the analysis:

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

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

.. note::
   The :code:`script_name` is a unique identification code that may be
   referred to differently across the platform (:code:`analysis_code`,
   :code:`input_data_type`, or :code:`type`). See :ref:`data-upload-label`
   and :ref:`search-analysis-label`.

Once started, :code:`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**:

.. code-block:: python

    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:

.. figure:: figs/launch_analyses/1.webp
    :alt: Example analysis finalized in the QMENTA Platform

This workflow consists of three processing tools executed sequentially:

.. figure:: figs/launch_analyses/2.webp
    :alt: Example flow-diagram of a workflow

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

.. note::
    The Medical Image Data analysis (section :ref:`data-upload-label`) is
    exclusively for data upload.


.. _start-analysis-choose-file-label:

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:


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

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

.. code-block:: bash

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

.. code-block:: bash

    >? 2D_FLAIR_AX.zip

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

.. note::
    The analysis will be cancelled if :code:`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:

.. code-block:: python

    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:

.. figure:: figs/launch_analyses/4.webp
    :alt: Example failed workflow

Restart process:

.. code-block:: python

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

Result after restart:

.. figure:: figs/launch_analyses/5.webp
    :alt: Workflow in execution after restarting

.. 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 (:code:`qa_status` and :code:`qa_comments`):

.. code-block:: python

    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)

:code:`QCStatus` values:
- :code:`PASS`
- :code:`FAIL`
- :code:`UNDETERMINED`

QC Status visualization:

.. figure:: figs/launch_analyses/3.webp
    :alt: Analysis with QC Status set to PASS

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

Download Analysis Logs:

.. code-block:: python

    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:
- :ref:`download-results-label` – Retrieve and store analysis outputs.