satellitetools.common.timeseries
================================

.. py:module:: satellitetools.common.timeseries

.. autoapi-nested-parse::

   Functions for timeseries data handling.

   @author: Olli Nevalainen (Finnish Meteorological Institute)



Attributes
----------

.. autoapisummary::

   satellitetools.common.timeseries.logger


Classes
-------

.. autoapisummary::

   satellitetools.common.timeseries.StrEnum
   satellitetools.common.timeseries.ConfidenceLevel


Functions
---------

.. autoapisummary::

   satellitetools.common.timeseries.xr_dataset_to_timeseries
   satellitetools.common.timeseries._adjust_sample_size
   satellitetools.common.timeseries.propagate_rmse
   satellitetools.common.timeseries.compute_uncertainty
   satellitetools.common.timeseries.compute_confidence_intervals


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

.. py:class:: StrEnum

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   str(object='') -> str
   str(bytes_or_buffer[, encoding[, errors]]) -> str

   Create a new string object from the given object. If encoding or
   errors is specified, then the object must expose a data buffer
   that will be decoded using the given encoding and error handler.
   Otherwise, returns the result of object.__str__() (if defined)
   or repr(object).
   encoding defaults to sys.getdefaultencoding().
   errors defaults to 'strict'.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:data:: logger

.. py:class:: ConfidenceLevel

   Bases: :py:obj:`enum.StrEnum`


   Confidence level for calculating the confidence interval bounds.

   Initialize self.  See help(type(self)) for accurate signature.


   .. py:attribute:: C90
      :value: '90'



   .. py:attribute:: C95
      :value: '95'



   .. py:attribute:: C99
      :value: '99'



.. py:function:: xr_dataset_to_timeseries(xr_dataset: xarray.Dataset, variables: List[Union[satellitetools.biophys.biophys.BiophysVariable, satellitetools.biophys.biophys.VegetationIndex]], add_uncertainty: bool = False, add_confidence_intervals: bool = False, confidence_level: ConfidenceLevel = ConfidenceLevel.C95) -> pandas.DataFrame

   Compute timeseries dataframe from xarray dataset.

   :param xr_dataset: xarray dataset with Sentinel-2 data.
   :type xr_dataset: xr.Dataset
   :param variables: List of variables to compute timeseries for.
   :type variables: List[BiophysVariable]
   :param add_uncertainty: Adds variable {variable}_uncertainty and confidence intervals to dataframe.
                           Currently, uncertainty is equal to standar error (se) or if variable is
                           biophysical variable from biophys_xarray, it sqrt(se^2 + RMSE_mean^2) where
                           RMSE_mean is propagated uncertainty for the individual observations/pixels
                           uncertainties. Uncertainty for the individual pixels is considered to be the
                           variable RMSE from the SNAP biophysical processor developers
                           (see biophys_xarray.py and linked ATBD) (i.e. same for all pixels).
   :type add_uncertainty: bool, default False
   :param confidence_level: Confidence level (%) for calculating the confidence interval bounds.
                            Options "90", "95" & "99"
   :type confidence_level: ConfidenceLevel, default ConfidenceLevel.C95

   :returns: **df** -- Pandas dataframe with mean, std, se and percentage of NaNs inside AOI.
   :rtype: pandas dataframe


.. py:function:: _adjust_sample_size(xr_dataset: xarray.Dataset, sample_n: float) -> float

   Get sample size for uncertainty calculation.

   :param xr_dataset: xarray dataset with Sentinel-2 data.
   :type xr_dataset: xr.Dataset
   :param sample_n: Original sample size.
   :type sample_n: float

   :returns: **sample_n** -- Adjusted sample size.
   :rtype: float


.. py:function:: propagate_rmse(n: int, rmse: float) -> float

   Propagate RMSE for the mean value.

   :param n: Sample size.
   :type n: int
   :param rmse: Root mean square error.
   :type rmse: float

   :returns: **propagated_rmse** -- Propagated RMSE for the mean value.
   :rtype: float


.. py:function:: compute_uncertainty(df: pandas.DataFrame, xr_dataset: xarray.Dataset, var: satellitetools.biophys.biophys.BiophysVariable, sample_n: float) -> pandas.DataFrame

   Compute uncertainty for the variable.

   :param df: Dataframe with the variable.
   :type df: pd.DataFrame
   :param xr_dataset: xarray dataset with Sentinel-2 data.
   :type xr_dataset: xr.Dataset
   :param var: Biophysical variable.
   :type var: BiophysVariable
   :param sample_n: Sample size for uncertainty calculation.
   :type sample_n: float

   :returns: **df** -- Dataframe with the variable and uncertainty.
   :rtype: pd.DataFrame


.. py:function:: compute_confidence_intervals(df: pandas.DataFrame, var: satellitetools.biophys.biophys.BiophysVariable, confidence_level=ConfidenceLevel.C95) -> pandas.DataFrame

   Compute confidence intervals for the variable.

   :param df: Dataframe with the variable.
   :type df: pd.DataFrame
   :param var: Biophysical variable.
   :type var: BiophysVariable
   :param confidence_level: Confidence level (%) for calculating the confidence interval bounds.
                            Options "90", "95" & "99"
   :type confidence_level: ConfidenceLevel, default ConfidenceLevel.C95

   :returns: **df** -- Dataframe with the variable and confidence intervals.
   :rtype: pd.DataFrame