imaging_api.services.retrieval
==============================

.. py:module:: imaging_api.services.retrieval


Attributes
----------

.. autoapisummary::

   imaging_api.services.retrieval.XNATAuthHeaders


Functions
---------

.. autoapisummary::

   imaging_api.services.retrieval.retrieve_images_for_project
   imaging_api.services.retrieval.get_import_status
   imaging_api.services.retrieval.retry_retrieve_images_for_project


Module Contents
---------------

.. py:data:: XNATAuthHeaders

.. py:function:: retrieve_images_for_project(project_id: str, query: str, headers: XNATAuthHeaders) -> bool
   :async:


   Queues an import request for the images associated with the given project.

   Steps:

   1. Encrypt project ID to send to the data access API
   2. Fetch the cohort's accession IDs from the data access API
   3. Query PACS to find study for each accession ID -> put into a list
   4. Make a ImportStudyRequest object with the list of studies
   5. Check response gives all to QUEUED

   :param project_id: The imaging project ID to retrieve the data about.
   :type project_id: str
   :param query: The cohort query (raw SQL).
   :type query: str
   :param headers: The headers containing XNAT authentication details.
   :type headers: XNATAuthHeaders

   :returns: True if all studies were successfully queued, False otherwise.
   :rtype: bool

   :raises HTTPException: If the request cannot be processed.


.. py:function:: get_import_status(project_id: str, query: str, headers: XNATAuthHeaders) -> imaging_api.routers.schemas.ImportStatus
   :async:


   Returns information about the status of study imports:

   * `Successful`: Studies (i.e. accession numbers) successfully imported into XNAT
   * `Processing`: Studies currently being processed
   * `Failed`: Studies that failed to import
   * `Queued`: Studies waiting in the queue
   * `QueueFailed`: Studies that couldn't be queued for import

   1. Fetch the cohort's accession IDs from the data access API
   2. Get project experiments
   3. Get project import status

   :param project_id: The imaging project ID to retrieve the data about.
   :type project_id: str
   :param query: The cohort query.
   :type query: str
   :param headers: The headers containing XNAT authentication details.
   :type headers: XNATAuthHeaders

   :returns: An object containing the status of study imports.
   :rtype: ImportStatus

   :raises HTTPException: If the request cannot be processed.


.. py:function:: retry_retrieve_images_for_project(project_id: str, query: str, headers: XNATAuthHeaders) -> bool
   :async:


   Queues an import request for the images which have failed to import.

   Steps:

   1. Get import status
   2. If none have status failed (Failed or QueueFailed), return
   3. Create list of accession numbers that have failed.
   4. Unencrypt the accession numbers
   5. Use Pacs Query request to find study for each accession ID -> put into a list
   6. Make a ImportStudyRequest object with the list of studies
   7. Check response gives all to QUEUED
   8. Return success or failure

   :param project_id: The imaging project ID to retrieve the data about.
   :type project_id: str
   :param query: The cohort query (raw SQL).
   :type query: str
   :param headers: The headers containing XNAT authentication details.
   :type headers: XNATAuthHeaders

   :returns: True if all studies were successfully queued, False otherwise.
   :rtype: bool

   :raises HTTPException: If the request cannot be processed.