swarmpal._api
=============

.. py:module:: swarmpal._api


Attributes
----------

.. autoapisummary::

   swarmpal._api.processes_by_name
   swarmpal._api._TOOLBOX_QUICKLOOKS


Functions
---------

.. autoapisummary::

   swarmpal._api.make_process
   swarmpal._api.apply_process
   swarmpal._api.apply_processes
   swarmpal._api._str_to_timedelta
   swarmpal._api._fetch_dataset
   swarmpal._api.fetch_data
   swarmpal._api._detect_toolbox
   swarmpal._api.quicklook


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

.. py:data:: processes_by_name

.. py:function:: make_process(process_name=None, config={})

   Instantiates a PalProcess object with a given name and a configuration.

   :param process_name: The name of the process to apply.
                        Must be one of ['FAC_single_sat'].
   :type process_name: Str
   :param config: Parameters passed to the Toolbox' process.
   :type config: dict


.. py:function:: apply_process(data, process_name=None, config={})

   Create a SwarmPAL process and apply it on the given data.

   :param data: the data on which the process will be applied to.
   :type data: DataTree
   :param process_name: the name of the process to apply. See ... for a list of Toolboxes and their Processes.
   :type process_name: Str
   :param config: parameters passed to the Toolbox.
   :type config: dict


.. py:function:: apply_processes(data, process_params)

   Apply a list of processes to a dataset.

   :param data: the data on which the process will be applied to.
   :type data: DataTree
   :param process_params: a list of processes to apply to the input data.


.. py:function:: _str_to_timedelta(time)

   Convert strings that match 'HH:MM:SS' to datetime.timedelta objects.


.. py:function:: _fetch_dataset(provider='', config={}, options=None)

   Helper that downloads a single dataset from a data provider with a specified configuration.
   :param provider: The name of the data provider. Must be one of ['vires', 'hapi'].
   :type provider: Str
   :param config: A configuration passed to `create_paldata`.
                  TODO: describe the 'schema'
   :type config: List
   :param options:
                   The option passed to `create_paldata`. When None, the following defaults are used:

                       .. list-table::
                           :widths: 30 70
                           :header-rows: 1

                           * - Provider
                             - Default Options
                           * - `vires`
                             - `dict(asynchronous=False, show_progress=False)`
                           * - `hapi`
                             - `dict(logging=False)`
   :type options: dict or None


.. py:function:: fetch_data(configurations)

   Downloads list of datasets and returns a unified DataTree.

   :param configurations: A list of configurations passed to `create_paldata`.
                          TODO: describe the 'schema'
   :type configurations: List


.. py:data:: _TOOLBOX_QUICKLOOKS

.. py:function:: _detect_toolbox(data: xarray.DataTree) -> str

   Inspect PAL_meta to determine which toolbox produced the output datasets.


.. py:function:: quicklook(data: xarray.DataTree, toolbox: str | None = None)

   Create a quicklook plot based on the toolbox processes recorded in PAL_meta.

   :param data: Data that has been processed by SwarmPAL
   :type data: DataTree
   :param toolbox: Override toolbox selection (one of: 'FAC', 'TFA', 'DSECS'). Case-insensitive.
                   If omitted, the toolbox is auto-detected from PAL_meta.
   :type toolbox: str, optional

   :rtype: matplotlib.figure.Figure