.. _data-search-label:

Data Searches
=============

Once you have populated a Project in the QMENTA Platform with several
sessions, you can perform different types of searches to extract the information
you are looking for.

In this section, you will learn how to search for subject data and metadata
within a project. Various methods to retrieve such information are explained.

To begin, log in and activate a Project by following the steps in :ref:`login-label`.

Search for a Specific Subject
---------------------------------

You can retrieve the information for a specific subject by:

.. code-block:: python

    # Define the Subject ID.
    subject_name = "0001"

    # Retrieve Subject Information
    subjects = [subject for subject in project.subjects_metadata if subject["patient_secret_name"] == subject_name]

where :code:`subject_name` corresponds to the Subject ID and :code:`subjects`
is a list of the sessions available for that Subject ID containing certain
information (Patient ID, Container ID, Session Tags,
Session Metadata...). This is equivalent to the information available via the :code:`Data` tab in
the QMENTA Platform.

.. note::
   This type of search only provides the sessions available in the Project at the time it was activated.

.. _data-asearch-label:

Advanced Search
-------------------

You can retrieve all the sessions of the active Project that satisfy a certain
search criteria.
The search criteria is a dictionary with the following structure:

.. code-block:: python

    search_criteria = {
            "pars_patient_secret_name": "string;VALUE",
            "pars_ssid": "integer;OPERATOR|VALUE",
            "pars_modalities": "string;VALUE",
            "pars_tags": "tags;VALUES",
            "pars_age_at_scan": "integer;OPERATOR|VALUE",
            "pars_[dicom]_FILEKEY": "TYPE;VALUE",
            "pars_PROJECTMETADATAKEY": "TYPE;VALUE",
    }

where the dictionary keys correspond as follows:

    -   :code:`pars_patient_secret_name`: Applies the search to the Subject ID.
    -   :code:`pars_ssid`: Applies the search to the Session ID (SSID).
    -   :code:`pars_modalities`: Applies the search to the file modalities available within the session.
    -   :code:`pars_tags`: Applies the search to the file tags available within the session.
    -   :code:`pars_age_at_scan`: Applies the search to the age of the subject at the time of acquisition.
    -   :code:`pars_[dicom]_FILEKEY`: Applies the search to the DICOM metadata extracted.
    -   :code:`pars_PROJECTMETADATAKEY`: Applies the search to the Project metadata parameters.

Further:

:code:`VALUE` is the comparing value to be applied in the search.

:code:`OPERATOR` is the operator to apply when comparing integers. It can be one of:

    - :code:`eq`: Equal.
    - :code:`ne`: Not Equal.
    - :code:`gt`: Greater Than.
    - :code:`gte`: Greater Equal Than.
    - :code:`lt`: Lower Than.
    - :code:`tle`: Lower Equal Than.

:code:`FILEKEY` is the name of the DICOM metadata to apply the search to.

:code:`PROJECTMETADATAKEY` is the name of the Project metadata field to apply the search to.

:code:`TYPE` is the data type of the metadata. It can be one of:

    - :code:`integer`
    - :code:`decimal`
    - :code:`string`
    - :code:`list`

An example is shown below:

.. code-block:: python

    # Define search criteria
    search_criteria = {
         "pars_modalities": "string;T1,T2",
         "pars_tags": "tags;flair,post_contrast",
         "pars_[dicom]_Manufacturer": "string;ge",
         "pars_[dicom]_FlipAngle": "integer;gt|5",
         "pars_[dicom]_ImageType": "list;PRIMARY;SECONDARY",
    }

    # Retrieve sessions matching the criteria
    sessions = project.get_subjects_metadata(search_criteria=search_criteria)

where :code:`sessions` is the list of sessions that satisfy the search. Each session has the same
information as described in the previous section. In this case, the search
returns any session (i.e., Subject ID/Session ID) that has a file classified with
a :code:`T1` and/or :code:`T2` modality, a file with a :code:`flair` and/or
:code:`post_contrat` tag, a file whose Manufacturer contains :code:`ge`, a
file whose FlipAngle is greater than :code:`5º`, and a file with ImageType
with any of the values: :code:`PRIMARY` and/or :code:`SECONDARY`.

The equivalent search in the QMENTA Platform is shown next.

.. figure:: figs/data_search/1.webp

    Example search and result shown in a Project in the QMENTA Platform.

Search of Input Containers
-----------------------------

This type of search queries the database with the primary goal to retrieve the
Container IDs of all sessions uploaded to the active Project that satisfy a
defined search criteria.

The search criteria is a dictionary that can have the following keys:

    -   :code:`s_n`: Applies the search to the Subject ID.
    -   :code:`ssid`: Applies the search to the Session ID (SSID).
    -   :code:`from_d`: Starting search date in which the data was acquired.
    -   :code:`to_d`: Ending search date in which the data was acquired.

An example search would be as follows:

.. code-block:: python

    search_criteria = {"s_n": "01", "ssid":"1"}
    sessions = project.list_input_containers(search_criteria)

In this case, the search criteria retrieves a list of sessions (:code:`sessions`)
where the strings :code:`01` and :code:`1` are included as Subject ID
and Session ID, respectively. Each session is represented by a dictionary containing the following information:

    - Subject ID in key: :code:`patient_secret_name`
    - Session ID (SSID) in key: :code:`ssid`
    - Container ID in key: :code:`container_id`
    - Container Name in key: :code:`container_name`

Next Steps
-----------

Explore the following sections in detail:

- :ref:`modify-metadata-label` – Modify metadata.
- :ref:`launch-analysis-label` – Execute analyses.
- :ref:`download-results-label` – Retrieve and store analysis outputs.