dubfi.fluxes.mdm
================

.. py:module:: dubfi.fluxes.mdm

.. autoapi-nested-parse::

   Unified implementation for handling uncertainty inflation etc.

   Motivation
   ----------
   Uncertainties and inflation are computed distributed during inversion,
   but are not saved there. To provide the uncertainties used in the
   inversion, these need to be calculated again during post-processing.
   Using a common implementation should reduce the risk of undetected
   bugs and inconsistencies.

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



Functions
---------

.. autoapisummary::

   dubfi.fluxes.mdm.get_obs_uncertainty
   dubfi.fluxes.mdm.get_uncertainty
   dubfi.fluxes.mdm.get_initial_inflation
   dubfi.fluxes.mdm.get_inflation_ens
   dubfi.fluxes.mdm.get_inflation_uncert
   dubfi.fluxes.mdm.apply_inflation_ens


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

.. py:function:: get_obs_uncertainty(ssh, config, obs, obs_orig = None, obs_stdev = None, same_station_count = None, mec_stdev = None, signal_n = None)

   Compute observation uncertainty that shall be assumed in the inversion.

   Observation uncertainty describes the uncorrelated uncertainty
   applied to each observation data point, including representativity
   uncertainty. All variables should be provided as mole mixing
   ratios (mol/mol).

   :param ssh: station and sampling height code
   :type ssh: str
   :param config: inversion configuration
   :type config: dict
   :param obs: observations (time series)
   :type obs: np.ndarray | xr.DataArray
   :param obs_orig: original observations (without temporal smoothing)
   :type obs_orig: np.ndarray | xr.DataArray, optional
   :param obs_stdev: temporal variability of observations (as reported by the
                     observation site)
   :type obs_stdev: np.ndarray | xr.DataArray, optional
   :param same_station_count: for each observation, number of all observations with equal
                              time and station. Usually, this is the number of currently
                              active sampling heights of the station.
   :type same_station_count: np.ndarray | xr.DataArray, optional
   :param mec_stdev: standard deviation computed by model equivalent calculator
   :type mec_stdev: np.ndarray | xr.DataArray, optional
   :param signal_n: signal from natural fluxes. Natural fluxes are assumed to have
                    a higher uncertainty.
   :type signal_n: np.ndarray | xr.DataArray, optional

   :returns: **uncertainty** -- resulting uncertainty
   :rtype: np.ndarray | xr.DataArray


.. py:function:: get_uncertainty(obs_uncert, meteo_uncert, bc_uncert, inflation = None)

   Compute model data mismatch uncertainty.


.. py:function:: get_initial_inflation(config, ssh)

   Get explicitly configured inflation for one station and sampling height.


.. py:function:: get_inflation_ens(config, mdm, obs_uncert, meteo_ens, bc_ens)

   Compute uncertainty inflation from ensembles.

   :param config: inversion configuration
   :type config: dict
   :param mdm: model data mismatch
   :type mdm: xr.DataArray | np.ndarray
   :param obs_uncert: observation uncertainty (assumed to be uncorrelated),
                      one-dimensional
   :type obs_uncert: xr.DataArray | np.ndarray
   :param meteo_ens: meteorological ensemble, dimensions should be
                     (ensmem, time)
   :type meteo_ens: xr.DataArray | np.ndarray
   :param bc_ens: boundary condition ensemble, dimensions should be
                  (bc_ens_letkf OR bc_ens, time)
   :type bc_ens: xr.DataArray | np.ndarray | None

   :returns: **inflation** -- extra inflation that shall be applied to mdm and meteo_ens.
   :rtype: xr.DataArray | np.ndarray


.. py:function:: get_inflation_uncert(config, mdm, obs_uncert, meteo_uncert, bc_uncert)

   Compute uncertainty inflation from uncertainties.

   All input arrays are expected to be one-dimensional an aligned.

   :param config: inversion configuration
   :type config: dict
   :param mdm: model data mismatch
   :type mdm: xr.DataArray | np.ndarray
   :param obs_uncert: observation uncertainty (assumed to be uncorrelated)
   :type obs_uncert: xr.DataArray | np.ndarray
   :param meteo_uncert: uncertainty due to meteorology
   :type meteo_uncert: xr.DataArray | np.ndarray
   :param bc_uncert: uncertainty from boundary conditions
   :type bc_uncert: xr.DataArray | np.ndarray | None

   :returns: **inflation** -- extra inflation that shall be applied to mdm and meteo_ens.
   :rtype: xr.DataArray | np.ndarray


.. py:function:: apply_inflation_ens(inflation, tot_ens, flux_ens, obs_uncert)

   Apply uncertainty inflation to ensemble in-place.