Working with Exams and Series
==============================

In Agora the typical data hierarchy is:

**Patient → Exam (Study) → Series → Dataset → Datafile**

Exams
-----

Get an exam by ID
~~~~~~~~~~~~~~~~~

.. code-block:: python

   exam = agora.get_exam(12)

Get all exams
~~~~~~~~~~~~~

.. code-block:: python

   exams = agora.get_exam_list()

Get an exam by UID (DICOM Study Instance UID)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   exam = agora.get_exam_by_uid(project=2, uid='1.2.840.10008.5.1.4.1.1.4')

Link an exam to a folder
~~~~~~~~~~~~~~~~~~~~~~~~

Creates a *link* — the exam remains in its original location and is also
visible in the target folder:

.. code-block:: python

   folder     = agora.get_folder(10)
   exam_item  = exam.link_to_folder(folder.id)

Remove the link (does **not** delete the exam):

.. code-block:: python

   exam_item.delete()

Lock and unlock an exam
~~~~~~~~~~~~~~~~~~~~~~~~

Locking prevents any further modifications to the exam:

.. code-block:: python

   exam.lock()
   exam.unlock()

Get relations
~~~~~~~~~~~~~

.. code-block:: python

   relations = exam.relations()

Get all patients
~~~~~~~~~~~~~~~~~

.. code-block:: python

   patients = agora.get_patients()
   for p in patients:
       print(p.name)

Get a patient by ID
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   patient = agora.get_patient(15)

Series
------

Get all series of an exam
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   series_list = exam.get_series()
   for s in series_list:
       print(f'Series: {s.name}')

Get a series by ID
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   series = agora.get_series(76)

Get a series by UID
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   series = agora.get_series_by_uid(project=2, uid='1.2.840.10008.5.1.4.1.1.4.1')

Get all datasets of a series
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   datasets = series.get_datasets()

Get relations of a series
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   relations = series.relations()

Get all datasets of an exam (shortcut)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   datasets = exam.get_datasets()

Search
------

Search for series by a free-text string:

.. code-block:: python

   results = agora.search_series('knee')
   for s in results:
       print(s.name)