Fix/add fit/predict_kwargs argument to historical_forecasts

CHANGELOG.md

@@ -20,9 +20,10 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 - Improvements to Regression Models:
   - `XGBModel` now leverages XGBoost's native Quantile Regression support that was released in version 2.0.0 for improved probabilistic forecasts. [#2051](https://github.com/unit8co/darts/pull/2051) by [Dennis Bader](https://github.com/dennisbader).
 - Other improvements:
-  - Added support for time index time zone conversion with parameter `tz` before generating/computing holidays and datetime attributes. Support was added to all Time Axis Encoders (standalone encoders and forecasting models' `add_encoders`, time series generation utils functions `holidays_timeseries()` and `datetime_attribute_timeseries()`, and `TimeSeries` methods `add_datetime_attribute()` and `add_holidays()`. [#2054](https://github.com/unit8co/darts/pull/2054) by [Dennis Bader](https://github.com/dennisbader).
+  - Added support for time index time zone conversion with parameter `tz` before generating/computing holidays and datetime attributes. Support was added to all Time Axis Encoders, standalone encoders and forecasting models' `add_encoders`, time series generation utils functions `holidays_timeseries()` and `datetime_attribute_timeseries()`, and `TimeSeries` methods `add_datetime_attribute()` and `add_holidays()`. [#2054](https://github.com/unit8co/darts/pull/2054) by [Dennis Bader](https://github.com/dennisbader).
   - Added optional keyword arguments dict `kwargs` to `ExponentialSmoothing` that will be passed to the constructor of the underlying `statsmodels.tsa.holtwinters.ExponentialSmoothing` model. [#2059](https://github.com/unit8co/darts/pull/2059) by [Antoine Madrona](https://github.com/madtoinou).
   - Added new dataset `ElectricityConsumptionZurichDataset`: The dataset contains the electricity consumption of households in Zurich, Switzerland from 2015-2022 on different grid levels. We also added weather measurements for Zurich which can be used as covariates for modelling. [#2039](https://github.com/unit8co/darts/pull/2039) by [Antoine Madrona](https://github.com/madtoinou) and [Dennis Bader](https://github.com/dennisbader).
+  - Added new arguments `fit_kwargs` and `predict_kwargs` to `historical_forecasts()`, `backtest()` and `gridsearch()` that will be passed to the model's `fit()` and / or `predict` methods. E.g., you can now set a batch size, static validation series, ... depending on the model support. [#2050](https://github.com/unit8co/darts/pull/2050) by [Antoine Madrona](https://github.com/madtoinou)
 
 **Fixed**
 - Fixed a bug when calling optimized `historical_forecasts()` for a `RegressionModel` trained with unequal component-specific lags. [#2040](https://github.com/unit8co/darts/pull/2040) by [Antoine Madrona](https://github.com/madtoinou).

darts/models/forecasting/baselines.py

@@ -332,8 +332,12 @@ def fit(
             for model in self.forecasting_models:
                 model._fit_wrapper(
                     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,
                 )
 
         return self

darts/models/forecasting/forecasting_model.py

@@ -42,6 +42,7 @@
     _get_historical_forecast_predict_index,
     _get_historical_forecast_train_index,
     _historical_forecasts_general_checks,
+    _historical_forecasts_sanitize_kwargs,
     _reconciliate_historical_time_indices,
 )
 from darts.utils.timeseries_generation import (
@@ -316,23 +317,47 @@ def _fit_wrapper(
         series: TimeSeries,
         past_covariates: Optional[TimeSeries],
         future_covariates: Optional[TimeSeries],
+        **kwargs,
     ):
-        self.fit(series)
+        supported_params = inspect.signature(self.fit).parameters
+        kwargs_ = {k: v for k, v in kwargs.items() if k in supported_params}
+
+        # handle past and future covariates based on model support
+        for covs, name in zip([past_covariates, future_covariates], ["past", "future"]):
+            covs_name = f"{name}_covariates"
+            if getattr(self, f"supports_{covs_name}"):
+                kwargs_[covs_name] = covs
+            elif covs is not None:
+                raise_log(
+                    ValueError(f"Model cannot be fit/trained with `{covs_name}`."),
+                    logger,
+                )
+        self.fit(series, **kwargs_)
 
     def _predict_wrapper(
         self,
         n: int,
-        series: TimeSeries,
-        past_covariates: Optional[TimeSeries],
-        future_covariates: Optional[TimeSeries],
-        num_samples: int,
-        verbose: bool = False,
-        predict_likelihood_parameters: bool = False,
-    ) -> TimeSeries:
-        kwargs = dict()
-        if self.supports_likelihood_parameter_prediction:
-            kwargs["predict_likelihood_parameters"] = predict_likelihood_parameters
-        return self.predict(n, num_samples=num_samples, verbose=verbose, **kwargs)
+        **kwargs,
+    ) -> Union[TimeSeries, Sequence[TimeSeries]]:
+        supported_params = set(inspect.signature(self.predict).parameters)
+
+        # if predict() accepts covariates, the model might not support them at inference
+        for covs_name in ["past_covariates", "future_covariates"]:
+            if covs_name in kwargs and not getattr(self, f"supports_{covs_name}"):
+                if kwargs[covs_name] is None:
+                    supported_params = supported_params - {covs_name}
+                else:
+                    raise_log(
+                        ValueError(
+                            f"Model prediction does not support `{covs_name}`, either because it "
+                            f"does not support `{covs_name}` in general, or because it was fit/trained "
+                            f"without using `{covs_name}`."
+                        ),
+                        logger,
+                    )
+
+        kwargs_ = {k: v for k, v in kwargs.items() if k in supported_params}
+        return self.predict(n, **kwargs_)
 
     @property
     def min_train_series_length(self) -> int:
@@ -586,6 +611,8 @@ def historical_forecasts(
         show_warnings: bool = True,
         predict_likelihood_parameters: bool = False,
         enable_optimization: bool = True,
+        fit_kwargs: Optional[Dict[str, Any]] = None,
+        predict_kwargs: Optional[Dict[str, Any]] = None,
     ) -> Union[
         TimeSeries, List[TimeSeries], Sequence[TimeSeries], Sequence[List[TimeSeries]]
     ]:
@@ -692,6 +719,10 @@ def historical_forecasts(
             Default: ``False``
         enable_optimization
             Whether to use the optimized version of historical_forecasts when supported and available.
+        fit_kwargs
+            Additional arguments passed to the model `fit()` method.
+        predict_kwargs
+            Additional arguments passed to the model `predict()` method.
 
         Returns
         -------
@@ -802,6 +833,15 @@ def retrain_func(
                 logger,
             )
 
+        # remove unsupported arguments, raise exception if interference with historical forecasts logic
+        fit_kwargs, predict_kwargs = _historical_forecasts_sanitize_kwargs(
+            model=model,
+            fit_kwargs=fit_kwargs,
+            predict_kwargs=predict_kwargs,
+            retrain=retrain is not False and retrain != 0,
+            show_warnings=show_warnings,
+        )
+
         series = series2seq(series)
         past_covariates = series2seq(past_covariates)
         future_covariates = series2seq(future_covariates)
@@ -829,6 +869,7 @@ def retrain_func(
                 verbose=verbose,
                 show_warnings=show_warnings,
                 predict_likelihood_parameters=predict_likelihood_parameters,
+                **predict_kwargs,
             )
 
         if len(series) == 1:
@@ -969,6 +1010,7 @@ def retrain_func(
                             series=train_series,
                             past_covariates=past_covariates_,
                             future_covariates=future_covariates_,
+                            **fit_kwargs,
                         )
                     else:
                         # untrained model was not trained on the first trainable timestamp
@@ -1019,6 +1061,7 @@ def retrain_func(
                     num_samples=num_samples,
                     verbose=verbose,
                     predict_likelihood_parameters=predict_likelihood_parameters,
+                    **predict_kwargs,
                 )
                 if forecast_components is None:
                     forecast_components = forecast.columns
@@ -1076,6 +1119,8 @@ def backtest(
         reduction: Union[Callable[[np.ndarray], float], None] = np.mean,
         verbose: bool = False,
         show_warnings: bool = True,
+        fit_kwargs: Optional[Dict[str, Any]] = None,
+        predict_kwargs: Optional[Dict[str, Any]] = None,
     ) -> Union[float, List[float], Sequence[float], List[Sequence[float]]]:
         """Compute error values that the model would have produced when
         used on (potentially multiple) `series`.
@@ -1185,6 +1230,10 @@ def backtest(
             Whether to print progress.
         show_warnings
             Whether to show warnings related to parameters `start`, and `train_length`.
+        fit_kwargs
+            Additional arguments passed to the model `fit()` method.
+        predict_kwargs
+            Additional arguments passed to the model `predict()` method.
 
         Returns
         -------
@@ -1208,6 +1257,8 @@ def backtest(
                 last_points_only=last_points_only,
                 verbose=verbose,
                 show_warnings=show_warnings,
+                fit_kwargs=fit_kwargs,
+                predict_kwargs=predict_kwargs,
             )
         else:
             forecasts = historical_forecasts
@@ -1261,6 +1312,8 @@ def gridsearch(
         verbose=False,
         n_jobs: int = 1,
         n_random_samples: Optional[Union[int, float]] = None,
+        fit_kwargs: Optional[Dict[str, Any]] = None,
+        predict_kwargs: Optional[Dict[str, Any]] = None,
     ) -> Tuple["ForecastingModel", Dict[str, Any], float]:
         """
         Find the best hyper-parameters among a given set using a grid search.
@@ -1374,6 +1427,10 @@ def gridsearch(
             must be between `0` and the total number of parameter combinations.
             If a float, `n_random_samples` is the ratio of parameter combinations selected from the full grid and must
             be between `0` and `1`. Defaults to `None`, for which random selection will be ignored.
+        fit_kwargs
+            Additional arguments passed to the model `fit()` method.
+        predict_kwargs
+            Additional arguments passed to the model `predict()` method.
 
         Returns
         -------
@@ -1406,10 +1463,10 @@ def gridsearch(
                 logger,
             )
 
-        # TODO: here too I'd say we can leave these checks to the models
-        # if covariates is not None:
-        #     raise_if_not(series.has_same_time_as(covariates), 'The provided series and covariates must have the '
-        #                                                       'same time axes.')
+        if fit_kwargs is None:
+            fit_kwargs = dict()
+        if predict_kwargs is None:
+            predict_kwargs = dict()
 
         # compute all hyperparameter combinations from selection
         params_cross_product = list(product(*parameters.values()))
@@ -1437,7 +1494,12 @@ def _evaluate_combination(param_combination) -> float:
 
             model = model_class(**param_combination_dict)
             if use_fitted_values:  # fitted value mode
-                model._fit_wrapper(series, past_covariates, future_covariates)
+                model._fit_wrapper(
+                    series=series,
+                    past_covariates=past_covariates,
+                    future_covariates=future_covariates,
+                    **fit_kwargs,
+                )
                 fitted_values = TimeSeries.from_times_and_values(
                     series.time_index, model.fitted_values
                 )
@@ -1457,16 +1519,24 @@ def _evaluate_combination(param_combination) -> float:
                     last_points_only=last_points_only,
                     verbose=verbose,
                     show_warnings=show_warnings,
+                    fit_kwargs=fit_kwargs,
+                    predict_kwargs=predict_kwargs,
                 )
             else:  # split mode
-                model._fit_wrapper(series, past_covariates, future_covariates)
+                model._fit_wrapper(
+                    series=series,
+                    past_covariates=past_covariates,
+                    future_covariates=future_covariates,
+                    **fit_kwargs,
+                )
                 pred = model._predict_wrapper(
-                    len(val_series),
-                    series,
-                    past_covariates,
-                    future_covariates,
+                    n=len(val_series),
+                    series=series,
+                    past_covariates=past_covariates,
+                    future_covariates=future_covariates,
                     num_samples=1,
                     verbose=verbose,
+                    **predict_kwargs,
                 )
                 error = metric(val_series, pred)
 
@@ -2211,43 +2281,6 @@ def predict(
                 )
             )
 
-    def _predict_wrapper(
-        self,
-        n: int,
-        series: Union[TimeSeries, Sequence[TimeSeries]],
-        past_covariates: Optional[Union[TimeSeries, Sequence[TimeSeries]]],
-        future_covariates: Optional[Union[TimeSeries, Sequence[TimeSeries]]],
-        num_samples: int,
-        verbose: bool = False,
-        predict_likelihood_parameters: bool = False,
-    ) -> Union[TimeSeries, Sequence[TimeSeries]]:
-        kwargs = dict()
-        if self.supports_likelihood_parameter_prediction:
-            kwargs["predict_likelihood_parameters"] = predict_likelihood_parameters
-        return self.predict(
-            n,
-            series,
-            past_covariates=past_covariates,
-            future_covariates=future_covariates,
-            num_samples=num_samples,
-            verbose=verbose,
-            **kwargs,
-        )
-
-    def _fit_wrapper(
-        self,
-        series: Union[TimeSeries, Sequence[TimeSeries]],
-        past_covariates: Optional[Union[TimeSeries, Sequence[TimeSeries]]],
-        future_covariates: Optional[Union[TimeSeries, Sequence[TimeSeries]]],
-    ):
-        self.fit(
-            series=series,
-            past_covariates=past_covariates if self.supports_past_covariates else None,
-            future_covariates=future_covariates
-            if self.supports_future_covariates
-            else None,
-        )
-
     @property
     def _supports_non_retrainable_historical_forecasts(self) -> bool:
         """GlobalForecastingModel supports historical forecasts without retraining the model"""
@@ -2340,6 +2373,7 @@ def fit(self, series: TimeSeries, future_covariates: Optional[TimeSeries] = None
                 logger=logger,
             )
             self._expect_future_covariates = True
+            self._uses_future_covariates = True
 
         self.encoders = self.initialize_encoders()
         if self.encoders.encoding_available:
@@ -2448,35 +2482,6 @@ def _predict(
         """
         pass
 
-    def _fit_wrapper(
-        self,
-        series: TimeSeries,
-        past_covariates: Optional[TimeSeries],
-        future_covariates: Optional[TimeSeries],
-    ):
-        self.fit(series, future_covariates=future_covariates)
-
-    def _predict_wrapper(
-        self,
-        n: int,
-        series: TimeSeries,
-        past_covariates: Optional[TimeSeries],
-        future_covariates: Optional[TimeSeries],
-        num_samples: int,
-        verbose: bool = False,
-        predict_likelihood_parameters: bool = False,
-    ) -> TimeSeries:
-        kwargs = dict()
-        if self.supports_likelihood_parameter_prediction:
-            kwargs["predict_likelihood_parameters"] = predict_likelihood_parameters
-        return self.predict(
-            n,
-            future_covariates=future_covariates,
-            num_samples=num_samples,
-            verbose=verbose,
-            **kwargs,
-        )
-
     @property
     def _model_encoder_settings(
         self,
@@ -2673,28 +2678,6 @@ def _predict(
         """
         pass
 
-    def _predict_wrapper(
-        self,
-        n: int,
-        series: TimeSeries,
-        past_covariates: Optional[TimeSeries],
-        future_covariates: Optional[TimeSeries],
-        num_samples: int,
-        verbose: bool = False,
-        predict_likelihood_parameters: bool = False,
-    ) -> TimeSeries:
-        kwargs = dict()
-        if self.supports_likelihood_parameter_prediction:
-            kwargs["predict_likelihood_parameters"] = predict_likelihood_parameters
-        return self.predict(
-            n=n,
-            series=series,
-            future_covariates=future_covariates,
-            num_samples=num_samples,
-            verbose=verbose,
-            **kwargs,
-        )
-
     @property
     def _supports_non_retrainable_historical_forecasts(self) -> bool:
         return True