Working with Datasets and Datafiles
====================================

A *dataset* is a logical group of one or more data files (datafiles) within a
series. Datasets have a *type* (e.g. Philips raw, DICOM, generic file) that
determines how Agora processes them.

Get a dataset by ID
-------------------

.. code-block:: python

   dataset = agora.get_dataset(158)

Get all datasets of a series
-----------------------------

.. code-block:: python

   series   = agora.get_series(76)
   datasets = series.get_datasets()

Filter by dataset type
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from gtagora.models.dataset import DatasetType

   raw_datasets = series.get_datasets(filters={'type': DatasetType.PHILIPS_RAW})

Dataset types
~~~~~~~~~~~~~

The :class:`~gtagora.models.dataset.DatasetType` enumeration includes (among
others):

* ``DatasetType.PHILIPS_RAW``
* ``DatasetType.DICOM``
* ``DatasetType.GENERIC``

Refer to the :class:`~gtagora.models.dataset.DatasetType` API reference for
the full list.

Working with datafiles
-----------------------

Each dataset contains one or more *datafiles*, which map to the actual files
stored on the Agora server.

List datafiles of a dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   for datafile in dataset.get_datafiles():
       print(datafile.original_filename)

Get parameters
--------------

Datasets and series can carry structured metadata as *parameters*:

.. code-block:: python

   params = dataset.get_parameters()
   for p in params:
       print(f'{p.name}: {p.value}')

Get a parameter set by ID
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   ps = agora.get_parameterset(42)