Develop

toarstats/trends/interface.py

@@ -4,43 +4,70 @@ This module contains the following function:
 calculate_trend - calculate the trend using the requested method
 """
 
+from toarstats.metrics.input_checks import check_data
 from toarstats.trends.ols import ols
 from toarstats.trends.quant_reg import quant_reg
-from toarstats.trends.utils import deseasonalize
+from toarstats.trends.utils import calculate_anomalies
 
 
-def calculate_trend(method, data, formula="value ~ datetime", quantiles=None):
+def calculate_trend(method, data, 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.
 
+    The calculation follows "Guidance note on best statistical practices
+    for TOAR analyses" (Chang et al. 2023,
+    https://arxiv.org/pdf/2304.14236.pdf) Annex E.
+
     :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
+    :raises TypeError: raised if
+
+                         - the ``data`` parameter is not a data frame or
+                           series
+                         - the index is not a datetime index
+                         - the values are not in a one-dimensional float
+                           or int array
+    :raises ValueError: raised if
+
+                          - the ``method`` parameter is not recognized
+                          - the index is empty, has duplicates or null
+                            values
+                          - the values array is empty or only contains
+                            null values
+                          - the index and values have different lengths
+                          - any ``quantiles`` are not strictly within 0
+                            and 1 with ``method="quantreg"``
 
-    :return: The result of the fit or a list of fit results if
-             ``method="quant"`` and multiple quantiles are given
+    :return: The result of the fit or a dict of fit results if
+             ``method="quant"``
     """
-    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:
+    if method not in {"OLS", "quant"}:
         raise ValueError(f"{method} is not recognized, must be 'OLS' or"
                          " 'quant'")
+    data_in = check_data(data, None, None).to_frame("value")
+    if method == "quant":
+        quantile_list = (
+            quantiles
+            if isinstance(quantiles, (list, set, tuple))
+            else [quantiles]
+        )
+        if not all(0 < quantile < 1 for quantile in quantile_list):
+            raise ValueError("The quantiles must be strictly between 0 and 1.")
+    anomalies_series = calculate_anomalies(data_in)
+    if method == "quant_reg":
+        fit = {
+            quantile: quant_reg(anomalies_series, quantile)
+            for quantile in quantile_list
+        }
+    else:
+        fit = ols(anomalies_series)
     return fit