Merge branch 'niklas_issue009_feat_calculate-quantile-regression' into 'develop'

Niklas issue009 feat calculate quantile regression

See merge request !3

toarstats/__init__.py

+"""The toarstats package.
+
+This package contains the following two subpackages:
+metrics - calculate metrics on time series
+trends - calculate trends on time series
+"""
+
+from toarstats import metrics, trends
+
+__all__ = ["metrics", "trends"]

toarstats/trends/__init__.py

 """The trends subpackage.
 
 This subpackage contains trend analysis tools for time series.
+
+This subpackage exports the following function:
+calculate_trend - public interface for the trends subpackage
 """
+
+from toarstats.trends.interface import calculate_trend
+
+
+__all__ = ["calculate_trend"]

toarstats/trends/interface.py

+"""This module contains the public interface for the trends subpackage.
+
+This module contains the following function:
+calculate_trend - calculate the trend using the requested method
+"""
+
+from toarstats.trends.ols import ols
+from toarstats.trends.quant_reg import quant_reg
+from toarstats.trends.utils import deseasonalize
+
+
+def calculate_trend(method, data, formula="value ~ datetime", quantiles=None):
+    """Calculate the trend using the requested method.
+
+    This function is the public interface for the ``trends`` subpackage.
+    It takes all the user inputs and returns the result of the requested
+    trend analysis.
+
+    :param method: either ``"OLS"`` or ``"quant"``
+    :param data: data containing a list of date time values and
+                 associated parameter values on which to calculate the
+                 trend
+    :param formula: the formula specifying the model
+    :param quantiles: a single quantile or a list of quantiles to
+                      calculate, these must be between 0 and 1; only
+                      needed when ``method="quant"``
+
+    :raises ValueError: raised if the ``method`` parameter is not
+                        recognized
+
+    :return: The result of the fit or a list of fit results if
+             ``method="quant"`` and multiple quantiles are given
+    """
+    deseasonalized_data = deseasonalize(data)
+    if method == "OLS":
+        fit = ols(deseasonalized_data, formula)
+    elif method == "quant":
+        try:
+            fit = [quant_reg(deseasonalized_data, formula, quantile)
+                   for quantile in quantiles]
+        except TypeError:
+            fit = quant_reg(deseasonalized_data, formula, quantiles)
+    else:
+        raise ValueError(f"{method} is not recognized, must be 'OLS' or"
+                         " 'quant'")
+    return fit

toarstats/trends/ols.py

+"""Ordinary least squares (OLS) linear regression calculation.
+
+This module contains the following function:
+ols - calculate the OLS linear regression
+"""
+
+import statsmodels.formula.api as smf
+
+
+def ols(data, formula):
+    """Calculate the OLS linear regression.
+
+    :param data: data containing a list of date time values and
+                 associated parameter values on which to calculate the
+                 trend
+    :param formula: the formula specifying the model
+
+    :return: The result of the fit
+    """
+    model = smf.ols(formula, data)
+    fit = model.fit()
+    return fit

toarstats/trends/quant_reg.py

+"""Quantile regression calculation.
+
+This module contains the following function:
+quant_reg - calculate the OLS linear regression
+"""
+
+import statsmodels.formula.api as smf
+
+
+def quant_reg(data, formula, quantile):
+    """Calculate the quantile regression.
+
+    :param data: data containing a list of date time values and
+                 associated parameter values on which to calculate the
+                 trend
+    :param formula: the formula specifying the model
+    :param quantile: a single quantile, must be between 0 and 1
+
+    :return: The result of the fit
+    """
+    model = smf.quantreg(formula, data)
+    fit = model.fit(q=quantile)
+    return fit

toarstats/trends/utils.py

+"""This module contains helper functions for the trends subpackage.
+
+This module contains the following function:
+deseasonalize - calculate the trend using the requested method
+"""
+
+import numpy as np
+import pandas as pd
+import statsmodels.formula.api as smf
+
+
+def deseasonalize(data):
+    """Deseasonalize the data.
+
+    :param data: data containing a list of date time values and
+                 associated parameter values
+
+    :return: The deseasonalized data
+    """
+    seasonal_cycle = smf.ols(
+        "value~np.cos(month*2*np.pi/12)+np.sin(month*2*np.pi/12)"
+        "+np.cos(month*4*np.pi/12)+np.sin(month*4*np.pi/12)",
+        pd.DataFrame({"value": data["value"], "month": data.index.month})
+    ).fit(method="qr").predict(pd.DataFrame({"month": range(1, 13)}))
+    idx = data.index
+    return pd.DataFrame({
+        "value": data["value"].values - seasonal_cycle[idx.month-1].values,
+        "datetime": (idx.year-2000)*12 + idx.month
+    })