dubfi.fluxes.readobs
====================

.. py:module:: dubfi.fluxes.readobs

.. autoapi-nested-parse::

   Read and filter observations as defined in configuration.

   .. codeauthor:: Valentin Bruch, DWD <valentin.bruch@dwd.de>
   .. versionadded:: 0.1.0 (initial release)
   .. versionchanged:: 0.1.1



Attributes
----------

.. autoapisummary::

   dubfi.fluxes.readobs.INVERSION_FLAGS


Classes
-------

.. autoapisummary::

   dubfi.fluxes.readobs.ReadObs


Functions
---------

.. autoapisummary::

   dubfi.fluxes.readobs.get_flag
   dubfi.fluxes.readobs.coordinates_from_config
   dubfi.fluxes.readobs.average_window
   dubfi.fluxes.readobs.data_from_config


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

.. py:data:: INVERSION_FLAGS
   :value: ['used', 'ignored: time range', 'ignored: season', 'ignored: time of day', 'ignored: wind...


   List of flags indicating filtering of observations for the inversion.

.. py:function:: get_flag(key)

   Get integer representation of inversion flag name, see :const:`INVERSION_FLAGS`.

   .. versionadded:: 0.1.1


.. py:function:: coordinates_from_config(config, **kwargs)

   Gather coordinates from input data, applying filtering as defined in config.

   :param config: configuration of path to configuration file (YAML)
   :type config: str | dict
   :param \*\*kwargs: passed on to :func:`data_from_config`
   :type \*\*kwargs: any

   :returns: **coordinates** -- dictionary with entries:

             - ssh: array of station and sampling height identifiers
             - time: list of time arrays, aligned with ssh
             - lon: array of station longitudes (degrees), aligned with ssh
             - lat: array of station latitudes (degrees), aligned with ssh
             - height: array of station heights (meters), aligned with ssh
             - flux_cat: array of flux category names
             - ens_size: number of meteorological ensemble members (integer)
   :rtype: dict


.. py:function:: average_window(da, window, min_diff = np.timedelta64(1, 'h'))

   Average data array over rolling time window.

   :param da: data array that shall be averaged. This must have a dimension
              and coordinate "time" of dtype np.datetime64. This time
              coordinate must be sorted and the minimum distance between the
              coordinate values must be at least min_diff.
   :type da: xr.DataArray
   :param window: time window for averaging.
                  result[i] is the mean of da[j] for all j such that
                  abs(da.time[i] - da.time[j]) < window.
   :type window: np.timedelta64
   :param min_diff: minimum distance between coordinate values in da.time.
                    If the value is too large, results will be wrong. If the
                    provided value is too small, performance will be worse.
   :type min_diff: np.timedelta64, default=1h

   :returns: **avg_da** -- da averaged over rolling time window. All dimensions and
             coordinates will be the same as in da. Internal order of data
             in memory may differ from da.
   :rtype: xr.DataArray


.. py:class:: ReadObs(config, suffix_rx)

   Object that parses configuration and reads data.

   .. versionadded:: 0.1.1

   Provide filtered data as defined in configuration.

   :param config: configuration of path to configuration file (YAML)
   :type config: str | dict
   :param suffix_rx: regular expression for the input file suffix, use this to
                     select the determinstic run without (_det.nc) or with
                     (_det_letkf.nc) far-field correction, or the ensemble data
                     (_ens.nc).
   :type suffix_rx: str, default=r"_det\.nc$"


   .. py:method:: get_data(coordinates_only = False, return_flags = False)

      Provide filtered data as defined in configuration.

      :param coordinates_only: if true, return only the coordinates and drop all other data
      :type coordinates_only: bool, default=False
      :param return_flags: additionally return a time series of flags defining why which
                           data point was used or not used in the inversion.
                           In this case, results will not be filtered.
      :type return_flags: bool, default=False

      :Yields: * *xr.Dataset* -- datasets for each matching station and sampling height.
                 Files are sorted alphabetically. Data are filtered unless
                 return_flags is true.
               * *xr.DataArray* -- only if return_flags: flag for each observation data point



   .. py:method:: filter_ds(ds, coordinates_only = False, return_flags = False)

      Filter data in dataset, see :meth:`~get_data`.



.. py:function:: data_from_config(config, coordinates_only = False, suffix_rx = '_det\\.nc$', return_flags = False)

   Provide filtered data as defined in configuration.

   :param config: configuration of path to configuration file (YAML)
   :type config: str | dict
   :param coordinates_only: if true, return only the coordinates and drop all other data
   :type coordinates_only: bool, default=False
   :param suffix_rx: regular expression for the input file suffix, use this to
                     select the determinstic run without (_det.nc) or with
                     (_det_letkf.nc) far-field correction, or the ensemble data
                     (_ens.nc).
   :type suffix_rx: str, default=r"_det\.nc$"
   :param return_flags: additionally return a time series of flags defining why which
                        data point was used or not used in the inversion
   :type return_flags: bool, default=False

   :Yields: * *xr.Dataset* -- filtered datasets for each matching station and sampling
              height. Files are sorted alphabetically.
            * *xr.DataArray* -- only if return_flags: flag for each observation data point

   .. versionchanged:: 0.1.1