Feature/multivariate wrapper

darts/models/__init__.py

@@ -20,6 +20,9 @@
 from darts.models.forecasting.fft import FFT
 from darts.models.forecasting.kalman_forecaster import KalmanForecaster
 from darts.models.forecasting.linear_regression_model import LinearRegressionModel
+from darts.models.forecasting.multivariate_forecasting_model_wrapper import (
+    MultivariateForecastingModelWrapper,
+)
 from darts.models.forecasting.random_forest import RandomForest
 from darts.models.forecasting.regression_ensemble_model import RegressionEnsembleModel
 from darts.models.forecasting.regression_model import RegressionModel

darts/models/forecasting/multivariate_forecasting_model_wrapper.py

@@ -0,0 +1,151 @@
+"""
+Regression ensemble model
+-------------------------
+
+An ensemble model which uses a regression model to compute the ensemble forecast.
+"""
+from typing import List, Optional, Tuple
+
+from darts.logging import get_logger
+from darts.models.forecasting.forecasting_model import (
+    FutureCovariatesLocalForecastingModel,
+    LocalForecastingModel,
+    TransferableFutureCovariatesLocalForecastingModel,
+)
+from darts.timeseries import TimeSeries, concatenate
+from darts.utils.utils import seq2series
+
+logger = get_logger(__name__)
+
+
+class MultivariateForecastingModelWrapper(FutureCovariatesLocalForecastingModel):
+    def _fit(self, series: TimeSeries, future_covariates: Optional[TimeSeries] = None):
+        super()._fit(series, future_covariates)
+        self._trained_models = []
+
+        series = seq2series(series)
+        components = self._split_multivariate(series)
+        if self.supports_future_covariates:
+            self._trained_models = [
+                self.base_model.untrained_model().fit(c, future_covariates)
+                for c in components
+            ]
+        else:
+            self._trained_models = [
+                self.base_model.untrained_model().fit(c) for c in components
+            ]
+
+        return self
+
+    def predict(
+        self,
+        n: int,
+        series: Optional[TimeSeries] = None,
+        future_covariates: Optional[TimeSeries] = None,
+        num_samples: int = 1,
+        **kwargs,
+    ) -> TimeSeries:
+        # we override `predict()` to pass a non-None `series`, so that historic_future_covariates
+        # will be passed to `_predict()` (some future covariates local models require it ex. Kalman)
+        return self._predict(n, future_covariates, num_samples, **kwargs)
+
+    def _predict(
+        self,
+        n: int,
+        future_covariates: Optional[TimeSeries] = None,
+        num_samples: int = 1,
+        verbose: bool = False,
+        **kwargs,
+    ) -> TimeSeries:
+        predictions = [
+            model.predict(n=n, future_covariates=future_covariates)
+            if isinstance(model, FutureCovariatesLocalForecastingModel)
+            else model.predict(n=n)
+            for model in self._trained_models
+        ]
+
+        multivariate_series = concatenate(predictions, axis=1)
+        return multivariate_series
+
+    def __init__(self, model: LocalForecastingModel):
+        """
+        Wrapper around LocalForecastingModel allowing it to act like a GlobalForecastingModel
+
+        A copy of the provided model will be trained on each of the components of the provided series separately.
+        The model doesn't use series supplied during predict() and instead predicts on the series it trained on.
+
+        Parameters
+        ----------
+        model
+            Model used to predict individual components
+        """
+        super().__init__()
+
+        self.base_model: LocalForecastingModel = model
+        self._trained_models: List[LocalForecastingModel] = []
+
+    def _split_multivariate(self, time_series: TimeSeries):
+        """split multivariate TimeSeries into a list of univariate TimeSeries"""
+        return [
+            time_series.univariate_component(i) for i in range(time_series.n_components)
+        ]
+
+    @property
+    def extreme_lags(
+        self,
+    ) -> Tuple[
+        Optional[int],
+        Optional[int],
+        Optional[int],
+        Optional[int],
+        Optional[int],
+        Optional[int],
+    ]:
+        return self.base_model.extreme_lags
+
+    @property
+    def _model_encoder_settings(
+        self,
+    ) -> Tuple[
+        Optional[int],
+        Optional[int],
+        bool,
+        bool,
+        Optional[List[int]],
+        Optional[List[int]],
+    ]:
+        return None, None, False, self.supports_future_covariates, None, None
+
+    @property
+    def supports_multivariate(self) -> bool:
+        return True
+
+    @property
+    def supports_past_covariates(self) -> bool:
+        return False
+
+    @property
+    def supports_future_covariates(self) -> bool:
+        return self.base_model.supports_future_covariates
+
+    @property
+    def supports_static_covariates(self) -> bool:
+        return False
+
+    def _is_probabilistic(self) -> bool:
+        """
+        A GlobalForecastingModelWrappers is probabilistic if the base_model
+        is probabilistic
+        """
+        return self.base_model._is_probabilistic()
+
+    def _supports_non_retrainable_historical_forecasts(self) -> bool:
+        return isinstance(
+            self.base_model, TransferableFutureCovariatesLocalForecastingModel
+        )
+
+    @property
+    def _supress_generate_predict_encoding(self) -> bool:
+        return isinstance(
+            self.base_model, TransferableFutureCovariatesLocalForecastingModel
+        )

darts/tests/models/forecasting/test_multivariate_forecasting_model_wrapper.py

@@ -0,0 +1,108 @@
+import copy
+
+from darts import TimeSeries
+from darts.logging import get_logger
+from darts.models import (
+    ARIMA,
+    BATS,
+    FFT,
+    TBATS,
+    AutoARIMA,
+    Croston,
+    ExponentialSmoothing,
+    FourTheta,
+    KalmanForecaster,
+    MultivariateForecastingModelWrapper,
+    NaiveMean,
+    NaiveMovingAverage,
+    NaiveSeasonal,
+    Prophet,
+    StatsForecastAutoCES,
+    StatsForecastAutoTheta,
+    Theta,
+)
+from darts.tests.base_test_class import DartsBaseTestClass
+from darts.utils import timeseries_generation as tg
+
+logger = get_logger(__name__)
+
+local_models = [
+    NaiveMean(),
+    NaiveMovingAverage(5),
+    NaiveSeasonal(),
+    ExponentialSmoothing(),
+    StatsForecastAutoTheta(season_length=12),
+    StatsForecastAutoCES(season_length=12, model="Z"),
+    Theta(1),
+    FourTheta(1),
+    FFT(trend="poly"),
+    TBATS(use_trend=True, use_arma_errors=True, use_box_cox=True),
+    BATS(use_trend=True, use_arma_errors=True, use_box_cox=True),
+]
+
+future_covariates_models = [
+    Prophet(),
+    Croston(),
+    AutoARIMA(),
+    ARIMA(12, 1, 1),
+    KalmanForecaster(),
+]
+
+
+class MultivariateForecastingModelWrapperTestCase(DartsBaseTestClass):
+    RANDOM_SEED = 42
+
+    ts_length = 50
+    n_pred = 5
+
+    univariate = tg.gaussian_timeseries(length=ts_length, mean=50)
+    multivariate = univariate.stack(univariate)
+
+    future_covariates = tg.gaussian_timeseries(length=ts_length + n_pred, mean=50)
+
+    def test_fit_predict_local_models(self):
+        for model in local_models:
+            self._test_predict_with_base_model(model, None)
+
+    def test_fit_predict_local_future_covariates_models(self):
+        for model in future_covariates_models:
+            self._test_predict_with_base_model(model, self.future_covariates)
+
+    def test_encoders_support(self):
+        add_encoders = {
+            "position": {"future": ["relative"]},
+        }
+
+        # test some models that support encoders
+        for model_object in future_covariates_models:
+            # test once with user supplied covariates, and once without
+            for fc in [self.future_covariates, None]:
+                model_params = {
+                    k: vals
+                    for k, vals in copy.deepcopy(model_object.model_params).items()
+                }
+                model_params["add_encoders"] = add_encoders
+                model = model_object.__class__(**model_params)
+
+                self._test_predict_with_base_model(model, fc)
+
+    def _test_predict_with_base_model(self, model, future_covariates):
+        series_univariate = self.univariate
+        series_multivariate = self.multivariate
+
+        combinations = [
+            series_univariate,
+            series_multivariate,
+        ]
+
+        for combination in combinations:
+            preds = self.trained_model_predictions(
+                model, self.n_pred, combination, future_covariates
+            )
+            self.assertTrue(isinstance(preds, TimeSeries))
+            self.assertTrue(preds.n_components == combination.n_components)
+
+    def trained_model_predictions(self, base_model, n, series, future_covariates):
+        model = MultivariateForecastingModelWrapper(base_model)
+        model.fit(series, future_covariates=future_covariates)
+        return model.predict(n=n, series=series, future_covariates=future_covariates)