Feat/local and global models in EnsembleModel

CHANGELOG.md

@@ -5,12 +5,17 @@ We do our best to avoid the introduction of breaking changes,
 but cannot always guarantee backwards compatibility. Changes that may **break code which uses a previous release of Darts** are marked with a "🔴".
 
 ## [Unreleased](https://github.com/unit8co/darts/tree/master)
+
 [Full Changelog](https://github.com/unit8co/darts/compare/0.24.0...master)
 
 ### For users of the library:
 
 **Improved**
-- Added support for `PathLike` to the `save()` and `load()` functions of `ForecastingModel`. [#1754](https://github.com/unit8co/darts/pull/1754) by [Simon Sudrich](https://github.com/sudrich).
+- General model improvements:
+  - Added support for `PathLike` to the `save()` and `load()` functions of all non-deep learning based models. [#1754](https://github.com/unit8co/darts/pull/1754) by [Simon Sudrich](https://github.com/sudrich).
+- Improvements to `EnsembleModel`:
+  - Model creation parameter `forecasting_models` now supports a mix of `LocalForecastingModel` and `GlobalForecastingModel` (single `TimeSeries` training/inference only, due to the local models). [#1745](https://github.com/unit8co/darts/pull/1745) by [Antoine Madrona](https://github.com/madtoinou).
+  - Future and past covariates can now be used even if `forecasting_models` have different covariates support. The covariates passed to `fit()`/`predict()` are used only by models that support it. [#1745](https://github.com/unit8co/darts/pull/1745) by [Antoine Madrona](https://github.com/madtoinou).
 
 ## [0.24.0](https://github.com/unit8co/darts/tree/0.24.0) (2023-04-12)
 ### For users of the library:

darts/models/forecasting/baselines.py

@@ -169,6 +169,9 @@ def __init__(
 
         Naive implementation of `EnsembleModel`
         Returns the average of all predictions of the constituent models
+
+        If `future_covariates` or `past_covariates` are provided at training or inference time,
+        they will be passed only to the models supporting them.
         """
         super().__init__(models)
 
@@ -184,15 +187,12 @@ def fit(
             future_covariates=future_covariates,
         )
         for model in self.models:
-            if self.is_global_ensemble:
-                kwargs = dict(series=series)
-                if model.supports_past_covariates:
-                    kwargs["past_covariates"] = past_covariates
-                if model.supports_future_covariates:
-                    kwargs["future_covariates"] = future_covariates
-                model.fit(**kwargs)
-            else:
-                model.fit(series=series)
+            kwargs = dict(series=series)
+            if model.supports_past_covariates:
+                kwargs["past_covariates"] = past_covariates
+            if model.supports_future_covariates:
+                kwargs["future_covariates"] = future_covariates
+            model.fit(**kwargs)
 
         return self
 

darts/models/forecasting/ensemble_model.py

@@ -8,6 +8,7 @@
 
 from darts.logging import get_logger, raise_if, raise_if_not
 from darts.models.forecasting.forecasting_model import (
+    ForecastingModel,
     GlobalForecastingModel,
     LocalForecastingModel,
 )
@@ -22,31 +23,41 @@ class EnsembleModel(GlobalForecastingModel):
     Ensemble models take in a list of forecasting models and ensemble their predictions
     to make a single one according to the rule defined by their `ensemble()` method.
 
+    If `future_covariates` or `past_covariates` are provided at training or inference time,
+    they will be passed only to the models supporting them.
+
     Parameters
     ----------
     models
         List of forecasting models whose predictions to ensemble
     """
 
-    def __init__(
-        self, models: Union[List[LocalForecastingModel], List[GlobalForecastingModel]]
-    ):
+    def __init__(self, models: List[ForecastingModel]):
         raise_if_not(
             isinstance(models, list) and models,
             "Cannot instantiate EnsembleModel with an empty list of models",
             logger,
         )
 
-        is_local_ensemble = all(
-            isinstance(model, LocalForecastingModel) for model in models
-        )
-        self.is_global_ensemble = all(
+        is_local_model = [isinstance(model, LocalForecastingModel) for model in models]
+        is_global_model = [
             isinstance(model, GlobalForecastingModel) for model in models
-        )
+        ]
+
+        self.is_local_ensemble = all(is_local_model)
+        self.is_global_ensemble = all(is_global_model)
 
         raise_if_not(
-            is_local_ensemble or self.is_global_ensemble,
-            "All models must be of the same type: either GlobalForecastingModel, or LocalForecastingModel.",
+            all(
+                [
+                    local_model or global_model
+                    for local_model, global_model in zip(
+                        is_local_model, is_global_model
+                    )
+                ]
+            ),
+            "All models must be of type `GlobalForecastingModel`, or `LocalForecastingModel`. "
+            "Also, make sure that all models in `models` are instantiated.",
             logger,
         )
 
@@ -60,6 +71,21 @@ def __init__(
         super().__init__()
         self.models = models
 
+        if self.supports_past_covariates and not self._full_past_covariates_support():
+            logger.info(
+                "Some models in the ensemble do not support past covariates, the past covariates will be "
+                "provided only to the models supporting them when calling fit/predict."
+            )
+
+        if (
+            self.supports_future_covariates
+            and not self._full_future_covariates_support()
+        ):
+            logger.info(
+                "Some models in the ensemble do not support future covariates, the future covariates will be "
+                "provided only to the models supporting them when calling fit/predict."
+            )
+
     def fit(
         self,
         series: Union[TimeSeries, Sequence[TimeSeries]],
@@ -71,34 +97,42 @@ def fit(
         Note that `EnsembleModel.fit()` does NOT call `fit()` on each of its constituent forecasting models.
         It is left to classes inheriting from EnsembleModel to do so appropriately when overriding `fit()`
         """
+
+        is_single_series = isinstance(series, TimeSeries)
+
+        # local models OR mix of local and global models
         raise_if(
-            not self.is_global_ensemble and not isinstance(series, TimeSeries),
-            "The models are of type LocalForecastingModel, which does not support training on multiple series.",
+            not self.is_global_ensemble and not is_single_series,
+            "The models contain at least one LocalForecastingModel, which does not support training on multiple "
+            "series.",
             logger,
         )
         raise_if(
-            not self.is_global_ensemble and past_covariates is not None,
+            self.is_local_ensemble and past_covariates is not None,
             "The models are of type LocalForecastingModel, which does not support past covariates.",
             logger,
         )
 
-        is_single_series = isinstance(series, TimeSeries)
-
-        # check that if timeseries is single series, than covariates are as well and vice versa
-        error = False
+        # check that if timeseries is single series, that covariates are as well and vice versa
+        error_past_cov = False
+        error_future_cov = False
 
         if past_covariates is not None:
-            error = is_single_series != isinstance(past_covariates, TimeSeries)
+            error_past_cov = is_single_series != isinstance(past_covariates, TimeSeries)
 
         if future_covariates is not None:
-            error = is_single_series != isinstance(future_covariates, TimeSeries)
+            error_future_cov = is_single_series != isinstance(
+                future_covariates, TimeSeries
+            )
 
         raise_if(
-            error,
-            "Both series and covariates have to be either univariate or multivariate.",
+            error_past_cov or error_future_cov,
+            "Both series and covariates have to be either single TimeSeries or sequences of TimeSeries.",
             logger,
         )
 
+        self._verify_past_future_covariates(past_covariates, future_covariates)
+
         super().fit(series, past_covariates, future_covariates)
 
         return self
@@ -125,12 +159,17 @@ def _make_multiple_predictions(
         num_samples: int = 1,
     ):
         is_single_series = isinstance(series, TimeSeries) or series is None
+        # maximize covariate usage
         predictions = [
             model._predict_wrapper(
                 n=n,
                 series=series,
-                past_covariates=past_covariates,
-                future_covariates=future_covariates,
+                past_covariates=past_covariates
+                if model.supports_past_covariates
+                else None,
+                future_covariates=future_covariates
+                if model.supports_future_covariates
+                else None,
                 num_samples=num_samples,
             )
             for model in self.models
@@ -160,6 +199,8 @@ def predict(
             verbose=verbose,
         )
 
+        self._verify_past_future_covariates(past_covariates, future_covariates)
+
         predictions = self._make_multiple_predictions(
             n=n,
             series=series,
@@ -229,3 +270,34 @@ def find_max_lag_or_none(lag_id, aggregator) -> Optional[int]:
 
     def _is_probabilistic(self) -> bool:
         return all([model._is_probabilistic() for model in self.models])
+
+    @property
+    def supports_past_covariates(self) -> bool:
+        return any([model.supports_past_covariates for model in self.models])
+
+    @property
+    def supports_future_covariates(self) -> bool:
+        return any([model.supports_future_covariates for model in self.models])
+
+    def _full_past_covariates_support(self) -> bool:
+        return all([model.supports_past_covariates for model in self.models])
+
+    def _full_future_covariates_support(self) -> bool:
+        return all([model.supports_future_covariates for model in self.models])
+
+    def _verify_past_future_covariates(self, past_covariates, future_covariates):
+        """
+        Verify that any non-None covariates comply with the model type.
+        """
+        raise_if(
+            past_covariates is not None and not self.supports_past_covariates,
+            "Some past_covariates have been provided to a EnsembleModel containing no models "
+            "supporting such covariates.",
+            logger,
+        )
+        raise_if(
+            future_covariates is not None and not self.supports_future_covariates,
+            "Some future_covariates have been provided to a Ensemble model containing no models "
+            "supporting such covariates.",
+            logger,
+        )

darts/models/forecasting/regression_ensemble_model.py

@@ -8,10 +8,7 @@
 
 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 (
-    GlobalForecastingModel,
-    LocalForecastingModel,
-)
+from darts.models.forecasting.forecasting_model import ForecastingModel
 from darts.models.forecasting.linear_regression_model import LinearRegressionModel
 from darts.models.forecasting.regression_model import RegressionModel
 from darts.timeseries import TimeSeries
@@ -23,9 +20,7 @@
 class RegressionEnsembleModel(EnsembleModel):
     def __init__(
         self,
-        forecasting_models: Union[
-            List[LocalForecastingModel], List[GlobalForecastingModel]
-        ],
+        forecasting_models: List[ForecastingModel],
         regression_train_n_points: int,
         regression_model=None,
     ):
@@ -38,6 +33,11 @@ def __init__(
         as in :class:`RegressionModel`, where the regression model is used to produce forecasts based on the
         lagged series.
 
+        If `future_covariates` or `past_covariates` are provided at training or inference time,
+        they will be passed only to the forecasting models supporting them.
+
+        The regression model does not leverage the covariates passed to ``fit()`` and ``predict()``.
+
         Parameters
         ----------
         forecasting_models
@@ -115,10 +115,15 @@ def fit(
             )
 
         for model in self.models:
+            # maximize covariate usage
             model._fit_wrapper(
                 series=forecast_training,
-                past_covariates=past_covariates,
-                future_covariates=future_covariates,
+                past_covariates=past_covariates
+                if model.supports_past_covariates
+                else None,
+                future_covariates=future_covariates
+                if model.supports_future_covariates
+                else None,
             )
 
         predictions = self._make_multiple_predictions(

darts/models/forecasting/theta.py

@@ -40,7 +40,7 @@ def __init__(
 
         `season_mode` must be a ``SeasonalityMode`` Enum member.
 
-        You can access the Enum with ``from darts import SeasonalityMode``.
+        You can access the Enum with ``from darts.utils.utils import SeasonalityMode``.
 
         Parameters
         ----------

darts/tests/models/forecasting/test_ensemble_models.py

@@ -12,6 +12,7 @@
     NaiveEnsembleModel,
     NaiveSeasonal,
     RegressionEnsembleModel,
+    StatsForecastAutoARIMA,
     Theta,
 )
 from darts.tests.base_test_class import DartsBaseTestClass
@@ -84,8 +85,10 @@ def test_extreme_lag_inference(self):
     def test_input_models_local_models(self):
         with self.assertRaises(ValueError):
             NaiveEnsembleModel([])
+        # models are not instantiated
         with self.assertRaises(ValueError):
             NaiveEnsembleModel([NaiveDrift, NaiveSeasonal, Theta, ExponentialSmoothing])
+        # one model is not instantiated
         with self.assertRaises(ValueError):
             NaiveEnsembleModel(
                 [NaiveDrift(), NaiveSeasonal, Theta(), ExponentialSmoothing()]
@@ -136,6 +139,9 @@ def test_stochastic_ensemble(self):
 
     @unittest.skipUnless(TORCH_AVAILABLE, "requires torch")
     def test_input_models_global_models(self):
+        # one model is not instantiated
+        with self.assertRaises(ValueError):
+            NaiveEnsembleModel([RNNModel(12), TCNModel(10, 2), NBEATSModel])
         NaiveEnsembleModel([RNNModel(12), TCNModel(10, 2), NBEATSModel(10, 2)])
 
     @unittest.skipUnless(TORCH_AVAILABLE, "requires torch")
@@ -183,8 +189,35 @@ def test_call_predict_global_models_multivariate_input_with_covariates(self):
 
     @unittest.skipUnless(TORCH_AVAILABLE, "requires torch")
     def test_input_models_mixed(self):
+        # NaiveDrift is local, RNNModel is global
+        naive_ensemble = NaiveEnsembleModel([NaiveDrift(), RNNModel(12, n_epochs=1)])
+        # ensemble is neither local, nor global
+        self.assertFalse(naive_ensemble.is_local_ensemble)
+        self.assertFalse(naive_ensemble.is_global_ensemble)
+
+        # ensemble contains one local model, no support for multiple ts fit
+        with self.assertRaises(ValueError):
+            naive_ensemble.fit([self.series1, self.series2])
+
+    @unittest.skipUnless(TORCH_AVAILABLE, "requires torch")
+    def test_mixed_models_with_covariates(self):
+        naive_ensemble_one_covs = NaiveEnsembleModel(
+            [NaiveDrift(), RNNModel(12, n_epochs=1)]
+        )
+        # none of the models support past covariates
+        with self.assertRaises(ValueError):
+            naive_ensemble_one_covs.fit(self.series1, past_covariates=self.series2)
+        # only RNN supports future covariates
+        naive_ensemble_one_covs.fit(self.series1, future_covariates=self.series2)
+
+        naive_ensemble_future_covs = NaiveEnsembleModel(
+            [StatsForecastAutoARIMA(), RNNModel(12, n_epochs=1)]
+        )
+        # none of the models support past covariates
         with self.assertRaises(ValueError):
-            NaiveEnsembleModel([NaiveDrift(), Theta(), RNNModel(12)])
+            naive_ensemble_future_covs.fit(self.series1, past_covariates=self.series2)
+        # both models supports future covariates
+        naive_ensemble_future_covs.fit(self.series1, future_covariates=self.series2)
 
     def test_fit_multivar_ts_with_local_models(self):
         naive = NaiveEnsembleModel(