Add dedicated LocalForecastingModel and renaming some model classes (#1327)

Author: dennisbader

darts/dataprocessing/encoders/__init__.py

@@ -1,4 +1,8 @@
-# Time Axis Encoders
+"""
+Time Axis Encoders
+------------------
+"""
+
 from .encoders import (
     FutureCallableIndexEncoder,
     FutureCyclicEncoder,

darts/models/forecasting/arima.py

@@ -17,14 +17,14 @@
 
 from darts.logging import get_logger
 from darts.models.forecasting.forecasting_model import (
-    TransferableDualCovariatesForecastingModel,
+    TransferableFutureCovariatesLocalForecastingModel,
 )
 from darts.timeseries import TimeSeries
 
 logger = get_logger(__name__)
 
 
-class ARIMA(TransferableDualCovariatesForecastingModel):
+class ARIMA(TransferableFutureCovariatesLocalForecastingModel):
     def __init__(
         self,
         p: int = 12,

darts/models/forecasting/auto_arima.py

@@ -8,13 +8,15 @@
 from pmdarima import AutoARIMA as PmdAutoARIMA
 
 from darts.logging import get_logger, raise_if
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 from darts.timeseries import TimeSeries
 
 logger = get_logger(__name__)
 
 
-class AutoARIMA(DualCovariatesForecastingModel):
+class AutoARIMA(FutureCovariatesLocalForecastingModel):
     def __init__(self, *autoarima_args, **autoarima_kwargs):
         """Auto-ARIMA
 

darts/models/forecasting/baselines.py

@@ -12,15 +12,15 @@
 from darts.logging import get_logger, raise_if_not
 from darts.models.forecasting.ensemble_model import EnsembleModel
 from darts.models.forecasting.forecasting_model import (
-    ForecastingModel,
     GlobalForecastingModel,
+    LocalForecastingModel,
 )
 from darts.timeseries import TimeSeries
 
 logger = get_logger(__name__)
 
 
-class NaiveMean(ForecastingModel):
+class NaiveMean(LocalForecastingModel):
     def __init__(self):
         """Naive Mean Model
 
@@ -44,7 +44,7 @@ def predict(self, n: int, num_samples: int = 1):
         return self._build_forecast_series(forecast)
 
 
-class NaiveSeasonal(ForecastingModel):
+class NaiveSeasonal(LocalForecastingModel):
     def __init__(self, K: int = 1):
         """Naive Seasonal Model
 
@@ -84,7 +84,7 @@ def predict(self, n: int, num_samples: int = 1):
         return self._build_forecast_series(forecast)
 
 
-class NaiveDrift(ForecastingModel):
+class NaiveDrift(LocalForecastingModel):
     def __init__(self):
         """Naive Drift Model
 
@@ -117,7 +117,7 @@ def predict(self, n: int, num_samples: int = 1):
 
 class NaiveEnsembleModel(EnsembleModel):
     def __init__(
-        self, models: Union[List[ForecastingModel], List[GlobalForecastingModel]]
+        self, models: Union[List[LocalForecastingModel], List[GlobalForecastingModel]]
     ):
         """Naive combination model
 

darts/models/forecasting/croston.py

@@ -9,11 +9,13 @@
 from statsforecast.models import CrostonClassic, CrostonOptimized, CrostonSBA
 
 from darts.logging import raise_if, raise_if_not
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 from darts.timeseries import TimeSeries
 
 
-class Croston(DualCovariatesForecastingModel):
+class Croston(FutureCovariatesLocalForecastingModel):
     def __init__(
         self, version: str = "classic", alpha_d: float = None, alpha_p: float = None
     ):

darts/models/forecasting/ensemble_model.py

@@ -8,8 +8,8 @@
 
 from darts.logging import get_logger, raise_if, raise_if_not
 from darts.models.forecasting.forecasting_model import (
-    ForecastingModel,
     GlobalForecastingModel,
+    LocalForecastingModel,
 )
 from darts.timeseries import TimeSeries
 
@@ -29,7 +29,7 @@ class EnsembleModel(GlobalForecastingModel):
     """
 
     def __init__(
-        self, models: Union[List[ForecastingModel], List[GlobalForecastingModel]]
+        self, models: Union[List[LocalForecastingModel], List[GlobalForecastingModel]]
     ):
         raise_if_not(
             isinstance(models, list) and models,
@@ -38,17 +38,15 @@ def __init__(
         )
 
         is_local_ensemble = all(
-            isinstance(model, ForecastingModel)
-            and not isinstance(model, GlobalForecastingModel)
-            for model in models
+            isinstance(model, LocalForecastingModel) for model in models
         )
         self.is_global_ensemble = all(
             isinstance(model, GlobalForecastingModel) for model in models
         )
 
         raise_if_not(
             is_local_ensemble or self.is_global_ensemble,
-            "All models must either be GlobalForecastingModel instances, or none of them should be.",
+            "All models must be of the same type: either GlobalForecastingModel, or LocalForecastingModel.",
             logger,
         )
 
@@ -76,12 +74,12 @@ def fit(
         """
         raise_if(
             not self.is_global_ensemble and not isinstance(series, TimeSeries),
-            "The models are not GlobalForecastingModel's and do not support training on multiple series.",
+            "The models are of type LocalForecastingModel, which does not support training on multiple series.",
             logger,
         )
         raise_if(
             not self.is_global_ensemble and past_covariates is not None,
-            "The models are not GlobalForecastingModel's and do not support past covariates.",
+            "The models are of type LocalForecastingModel, which does not support past covariates.",
             logger,
         )
 

darts/models/forecasting/exponential_smoothing.py

@@ -9,14 +9,14 @@
 import statsmodels.tsa.holtwinters as hw
 
 from darts.logging import get_logger
-from darts.models.forecasting.forecasting_model import ForecastingModel
+from darts.models.forecasting.forecasting_model import LocalForecastingModel
 from darts.timeseries import TimeSeries
 from darts.utils.utils import ModelMode, SeasonalityMode
 
 logger = get_logger(__name__)
 
 
-class ExponentialSmoothing(ForecastingModel):
+class ExponentialSmoothing(LocalForecastingModel):
     def __init__(
         self,
         trend: Optional[ModelMode] = ModelMode.ADDITIVE,

darts/models/forecasting/fft.py

@@ -10,7 +10,7 @@
 from statsmodels.tsa.stattools import acf
 
 from darts.logging import get_logger
-from darts.models.forecasting.forecasting_model import ForecastingModel
+from darts.models.forecasting.forecasting_model import LocalForecastingModel
 from darts.timeseries import TimeSeries
 from darts.utils.missing_values import fill_missing_values
 
@@ -210,7 +210,7 @@ def _crop_to_match_seasons(
     return series
 
 
-class FFT(ForecastingModel):
+class FFT(LocalForecastingModel):
     def __init__(
         self,
         nr_freqs_to_keep: Optional[int] = 10,

darts/models/forecasting/forecasting_model.py

@@ -133,7 +133,7 @@ def fit(self, series: TimeSeries) -> "ForecastingModel":
         self
             Fitted model.
         """
-        if not isinstance(self, DualCovariatesForecastingModel):
+        if not isinstance(self, FutureCovariatesLocalForecastingModel):
             series._assert_univariate()
         raise_if_not(
             len(series) >= self.min_train_series_length,
@@ -1068,6 +1068,20 @@ def load(path: Union[str, BinaryIO]) -> "ForecastingModel":
         return model
 
 
+class LocalForecastingModel(ForecastingModel, ABC):
+    """The base class for "local" forecasting models, handling only single univariate time series.
+
+    Local Forecasting Models (LFM) are models that can be trained on a single univariate target series only. In Darts,
+    most models in this category tend to be simpler statistical models (such as ETS or FFT). LFMs usually train on
+    the entire target series supplied when calling :func:`fit()` at once. They can also predict in one go with
+    :func:`predict()` for any number of predictions `n` after the end of the training series.
+
+    All implementations must implement the `_fit()` and `_predict()` methods.
+    """
+
+    pass
+
+
 class GlobalForecastingModel(ForecastingModel, ABC):
     """The base class for "global" forecasting models, handling several time series and optional covariates.
 
@@ -1080,7 +1094,7 @@ class GlobalForecastingModel(ForecastingModel, ABC):
     The name "global" stems from the fact that a training set of a forecasting model of this class is not constrained
     to a temporally contiguous, "local", time series.
 
-    All implementations have to implement the :func:`fit()` and :func:`predict()` methods defined below.
+    All implementations must implement the :func:`fit()` and :func:`predict()` methods.
     The :func:`fit()` method is meant to train the model on one or several training time series, along with optional
     covariates.
 
@@ -1371,12 +1385,18 @@ def _get_encoders_n(self, n) -> int:
         return n
 
 
-class DualCovariatesForecastingModel(ForecastingModel, ABC):
-    """The base class for the forecasting models that are not global, but support future covariates.
-    Among other things, it lets Darts forecasting models wrap around statsmodels models
-    having a `future_covariates` parameter, which corresponds to future-known covariates.
+class FutureCovariatesLocalForecastingModel(LocalForecastingModel, ABC):
+    """The base class for future covariates "local" forecasting models, handling single uni- or multivariate target
+    and optional future covariates time series.
 
-    All implementations have to implement the `_fit()` and `_predict()` methods defined below.
+    Future Covariates Local Forecasting Models (FC-LFM) are models that can be trained on a single uni- or multivariate
+    target and optional future covariates series. In Darts, most models in this category tend to be simpler statistical
+    models (such as ARIMA). FC-LFMs usually train on the entire target and future covariates series supplied when
+    calling :func:`fit()` at once. They can also predict in one go with :func:`predict()` for any number of predictions
+    `n` after the end of the training series. When using future covariates, the values for the future `n` prediction
+    steps must be given in the covariate series.
+
+    All implementations must implement the :func:`_fit()` and :func:`_predict()` methods.
     """
 
     _expect_covariate = False
@@ -1535,12 +1555,22 @@ def _predict_wrapper(
         )
 
 
-class TransferableDualCovariatesForecastingModel(DualCovariatesForecastingModel, ABC):
-    """The base class for the forecasting models that are not global, but support future covariates, and can
-    additionally be applied to new data unrelated to the original series used for fitting the model. Currently,
-    all the derived classes wrap statsmodels models.
+class TransferableFutureCovariatesLocalForecastingModel(
+    FutureCovariatesLocalForecastingModel, ABC
+):
+    """The base class for transferable future covariates "local" forecasting models, handling single uni- or
+    multivariate target and optional future covariates time series. Additionally, at prediction time, it can be
+    applied to new data unrelated to the original series used for fitting the model.
+
+    Transferable Future Covariates Local Forecasting Models (TFC-LFM) are models that can be trained on a single uni-
+    or multivariate target and optional future covariates series. Additionally, at prediction time, it can be applied
+    to new data unrelated to the original series used for fitting the model. Currently in Darts, all models in this
+    category wrap to statsmodel models such as VARIMA. TFC-LFMs usually train on the entire target and future covariates
+    series supplied when calling :func:`fit()` at once. They can also predict in one go with :func:`predict()`
+    for any number of predictions `n` after the end of the training series. When using future covariates, the values
+    for the future `n` prediction steps must be given in the covariate series.
 
-    All implementations have to implement the `_fit()`, `_predict()` methods.
+    All implementations must implement the :func:`_fit()` and :func:`_predict()` methods.
     """
 
     def predict(
@@ -1610,8 +1640,8 @@ def predict(
                     series
                 )
 
-        # DualCovariatesForecastingModel performs some checks on self.training_series. We temporary replace that with
-        # the new ts
+        # FutureCovariatesLocalForecastingModel performs some checks on self.training_series. We temporary replace
+        # that with the new ts
         if series is not None:
             self._orig_training_series = self.training_series
             self.training_series = series
@@ -1641,7 +1671,7 @@ def _predict(
         num_samples: int = 1,
     ) -> TimeSeries:
         """Forecasts values for a certain number of time steps after the end of the series.
-        TransferableDualCovariatesForecastingModel must implement the predict logic in this method.
+        TransferableFutureCovariatesLocalForecastingModel must implement the predict logic in this method.
         """
         pass
 

darts/models/forecasting/kalman_forecaster.py

@@ -17,13 +17,15 @@
 
 from darts.logging import get_logger
 from darts.models.filtering.kalman_filter import KalmanFilter
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 from darts.timeseries import TimeSeries
 
 logger = get_logger(__name__)
 
 
-class KalmanForecaster(DualCovariatesForecastingModel):
+class KalmanForecaster(FutureCovariatesLocalForecastingModel):
     def __init__(self, dim_x: int = 1, kf: Optional[Kalman] = None):
         """Kalman filter Forecaster
 

darts/models/forecasting/prophet_model.py

@@ -12,14 +12,16 @@
 import prophet
 
 from darts.logging import execute_and_suppress_output, get_logger, raise_if
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 from darts.timeseries import TimeSeries
 
 logger = get_logger(__name__)
 logger.level = logging.WARNING  # set to warning to suppress prophet logs
 
 
-class Prophet(DualCovariatesForecastingModel):
+class Prophet(FutureCovariatesLocalForecastingModel):
     def __init__(
         self,
         add_seasonalities: Optional[Union[dict, List[dict]]] = None,

darts/models/forecasting/regression_ensemble_model.py

@@ -9,8 +9,8 @@
 from darts.logging import get_logger, raise_if, raise_if_not
 from darts.models.forecasting.ensemble_model import EnsembleModel
 from darts.models.forecasting.forecasting_model import (
-    ForecastingModel,
     GlobalForecastingModel,
+    LocalForecastingModel,
 )
 from darts.models.forecasting.linear_regression_model import LinearRegressionModel
 from darts.models.forecasting.regression_model import RegressionModel
@@ -22,7 +22,9 @@
 class RegressionEnsembleModel(EnsembleModel):
     def __init__(
         self,
-        forecasting_models: Union[List[ForecastingModel], List[GlobalForecastingModel]],
+        forecasting_models: Union[
+            List[LocalForecastingModel], List[GlobalForecastingModel]
+        ],
         regression_train_n_points: int,
         regression_model=None,
     ):

darts/models/forecasting/sf_auto_arima.py

@@ -9,10 +9,12 @@
 from statsforecast.models import AutoARIMA as SFAutoARIMA
 
 from darts import TimeSeries
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 
 
-class StatsForecastAutoARIMA(DualCovariatesForecastingModel):
+class StatsForecastAutoARIMA(FutureCovariatesLocalForecastingModel):
     def __init__(self, *autoarima_args, **autoarima_kwargs):
         """Auto-ARIMA based on `Statsforecasts package
         <https://github.com/Nixtla/statsforecast>`_.

darts/models/forecasting/sf_ets.py

@@ -8,10 +8,12 @@
 from statsforecast.models import ETS
 
 from darts import TimeSeries
-from darts.models.forecasting.forecasting_model import DualCovariatesForecastingModel
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+)
 
 
-class StatsForecastETS(DualCovariatesForecastingModel):
+class StatsForecastETS(FutureCovariatesLocalForecastingModel):
     def __init__(self, *ets_args, **ets_kwargs):
         """ETS based on `Statsforecasts package
         <https://github.com/Nixtla/statsforecast>`_.