Feature/four theta (#123)

* feat(4Theta): naive implementation of 4Theta model

* fix(theta): avoid NaN values in theta, and unnecessary season test

* feat(gridsearch): add possibility to compare with model.fitted_values

* feat(4theta): add a method to auto select best model

* refactor(4Theta): Specify univariate model

* style(4Theta): Fix linter

* style(4Theta): fix docstring

* style(4Theta): Fix docstring

* style(4Theta): Change link

* style(4Theta): Correct docstring

* style(4theta): correct ticks in docstring

* refactor(4Theta): change different modes verification and add Enum

* refactor(theta): replace all string modes by Enum

* test(backtesting): Add a test to verify if fitted_values exist

* Fix(Theta): Correct all Enums

* fix(Theta): compare with enum members value instead. Correct some minor bugs

* fix(4theta): move the creation of enums in init file

* test(4theta): Add 4Theta to autoregressive test. Move Enums to top init file

* test(4theta): Add 4Theta specific test

* style(backtesting): fix lint

* test(4theta): Add another exception to test

* ref(4Theta): mode.fitted_values is now a TimeSeries to be consistent

* style(Theta): rename mode to season_mode to be consistent w/ FourTheta

* docs(thetas): correct errors in the different docs

* refactor(4Theta): Correct

  * Add normalization choice
  * Add comment to be clearer
  * Correct the docs
  * clean the code and add a check on mean=0

* refactor(backtesting): add a 'use_fitted_values' parameter

* fix(4theta): correct select_best_model

* test(4Theta): add a test for zero mean and correct others

* style(backtesting): linter formatting

* refactor(4Theta): change Enums names, correct theta and backtesting docs

* refactor(4theta): move creation of fitted_values timeseries to backtesting

* refactor(statistics): include Enums in extract and remove functions

* refactor(4Theta): check earlier if univariate

* test(4Theta): correct backtesting and test best_model

* test(4Theta): add new modes in test models

* docs(4theta): Add a disclaimer for 4theta performance

* refactor(Theta): change theta to have the same behavior as FourTheta

* examples(darts-intro): modify notebook to give the same results

* style(4Theta): correct deprecation warning for logger.warn

* style(4theta): move comment to backtesting

Co-authored-by: Julien Herzen <[email protected]>

Author: Droxef

darts/__init__.py

@@ -5,4 +5,24 @@
 
 from .timeseries import TimeSeries
 
+# Enums
+from enum import Enum
+
+
+class SeasonalityMode(Enum):
+    MULTIPLICATIVE = 'multiplicative'
+    ADDITIVE = 'additive'
+    NONE = None
+
+
+class TrendMode(Enum):
+    LINEAR = 'linear'
+    EXPONENTIAL = 'exponential'
+
+
+class ModelMode(Enum):
+    MULTIPLICATIVE = 'multiplicative'
+    ADDITIVE = 'additive'
+
+
 __version__ = 'dev'

darts/backtesting/backtesting.py

@@ -341,12 +341,13 @@ def backtest_gridsearch(model_class: type,
                         use_full_output_length: bool = True,
                         val_series: Optional[TimeSeries] = None,
                         num_predictions: int = 10,
+                        use_fitted_values: bool = False,
                         metric: Callable[[TimeSeries, TimeSeries], float] = metrics.mape,
                         verbose=False):
     """ A function for finding the best hyperparameters.
 
-    This function has 2 modes of operation: Expanding window mode and split mode.
-    Both modes of operation evaluate every possible combination of hyperparameter values
+    This function has 3 modes of operation: Expanding window mode, split mode and comparison with fitted values.
+    The three modes of operation evaluate every possible combination of hyperparameter values
     provided in the `parameters` dictionary by instantiating the `model_class` subclass
     of ForecastingModel with each combination, and returning the best-performing model with regards
     to the `metric` function. The `metric` function is expected to return an error value,
@@ -364,17 +365,24 @@ def backtest_gridsearch(model_class: type,
     For every hyperparameter combination, the model is trained on `train_series` and
     evaluated on `val_series`.
 
+    Comparison with fitted values (activated when `use_fitted_values` is passed):
+    For every hyperparameter combination, the model is trained on `train_series` and evaluated on the resulting
+    fitted values.
+    Not all models have fitted values, and this method raises an error if `model.fitted_values` doesn't exist.
+    The fitted values are the result of the fit of the model on the training series. Comparing with the fitted values
+    can be a quick way to assess the model, but one cannot see if the model overfits or underfits.
+
 
     Parameters
     ----------
-    model
+    model_class
         The ForecastingModel subclass to be tuned for 'series'.
     parameters
         A dictionary containing as keys hyperparameter names, and as values lists of values for the
         respective hyperparameter.
     train_series
         The univariate TimeSeries instance used for training (and also validation in split mode).
-    test_series
+    val_series
         The univariate TimeSeries instance used for validation in split mode.
     fcast_horizon_n
         The integer value of the forecasting horizon used in expanding window mode.
@@ -389,6 +397,9 @@ def backtest_gridsearch(model_class: type,
         as argument to the predict method of `model`.
     num_predictions:
         The number of train/prediction cycles performed in one iteration of expanding window mode.
+    use_fitted_values
+        If `True`, uses the comparison with the fitted values.
+        Raises an error if `fitted_values` is not an attribute of `model_class`.
     metric:
         A function that takes two TimeSeries instances as inputs and returns a float error value.
     verbose:
@@ -399,18 +410,22 @@ def backtest_gridsearch(model_class: type,
     ForecastingModel
         An untrained 'model_class' instance with the best-performing hyperparameters from the given selection.
     """
+    raise_if_not((fcast_horizon_n is not None) + (val_series is not None) + use_fitted_values == 1,
+                 "Please pass exactly one of the arguments 'forecast_horizon_n', 'val_series' or 'use_fitted_values'.",
+                 logger)
 
-    if (val_series is not None):
+    if use_fitted_values:
+        model = model_class()
+        raise_if_not(hasattr(model, "fitted_values"), "The model must have a fitted_values attribute"
+                     " to compare with the train TimeSeries", logger)
+    elif val_series is not None:
         raise_if_not(train_series.width == val_series.width, "Training and validation series require the same"
                      " number of components.", logger)
 
-    raise_if_not((fcast_horizon_n is None) ^ (val_series is None),
-                 "Please pass exactly one of the arguments 'forecast_horizon_n' or 'val_series'.", logger)
-
     fit_kwargs, predict_kwargs = _create_parameter_dicts(model_class(), target_indices, component_index,
                                                          use_full_output_length)
 
-    if val_series is None:
+    if (val_series is None) and (not use_fitted_values):
         backtest_start_time = train_series.end_time() - (num_predictions + fcast_horizon_n) * train_series.freq()
     min_error = float('inf')
     best_param_combination = {}
@@ -423,7 +438,13 @@ def backtest_gridsearch(model_class: type,
     for param_combination in iterator:
         param_combination_dict = dict(list(zip(parameters.keys(), param_combination)))
         model = model_class(**param_combination_dict)
-        if val_series is None:  # expanding window mode
+        if use_fitted_values:
+            model.fit(train_series)
+            # Takes too much time to create a TimeSeries
+            # Overhead: 2-10 ms in average
+            fitted_values = TimeSeries.from_times_and_values(train_series.time_index(), model.fitted_values)
+            error = metric(fitted_values, train_series)
+        elif val_series is None:  # expanding window mode
             backtest_forecast = backtest_forecasting(train_series, model, backtest_start_time, fcast_horizon_n,
                                                      target_indices, component_index, use_full_output_length)
             error = metric(backtest_forecast, train_series)
@@ -499,7 +520,7 @@ def explore_models(train_series: TimeSeries,
                 'trend': [None, 'poly', 'exp']
             }),
             (Theta, {
-                'theta': np.delete(np.linspace(-10, 10, 51), 30)
+                'theta': np.delete(np.linspace(-10, 10, 51), 25)
             }),
             (Prophet, {}),
             (AutoARIMA, {})

darts/models/__init__.py

@@ -10,7 +10,7 @@
 from .exponential_smoothing import ExponentialSmoothing
 from .rnn_model import RNNModel
 from .tcn_model import TCNModel
-from .theta import Theta
+from .theta import Theta, FourTheta
 from .fft import FFT
 
 # Regression