Feat/auto-regression and future values of past covariates documentation

darts/models/forecasting/catboost_model.py

@@ -53,7 +53,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that

darts/models/forecasting/ensemble_model.py

@@ -288,6 +288,7 @@ def predict(
         num_samples: int = 1,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> Union[TimeSeries, Sequence[TimeSeries]]:
         # ensure forecasting models all rely on the same series during inference
         if series is None:
@@ -305,6 +306,7 @@ def predict(
             num_samples=num_samples,
             verbose=verbose,
             predict_likelihood_parameters=predict_likelihood_parameters,
+            show_warnings=show_warnings,
         )
 
         # for single-level ensemble, probabilistic forecast is obtained directly from forecasting models

darts/models/forecasting/forecasting_model.py

@@ -328,6 +328,7 @@ def _predict_wrapper(
         num_samples: int,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> TimeSeries:
         kwargs = dict()
         if self.supports_likelihood_parameter_prediction:
@@ -838,6 +839,9 @@ def retrain_func(
         else:
             outer_iterator = _build_tqdm_iterator(series, verbose)
 
+        # deactivate the warning after displaying it once
+        show_predict_warnings = show_warnings
+
         forecasts_list = []
         for idx, series_ in enumerate(outer_iterator):
             past_covariates_ = past_covariates[idx] if past_covariates else None
@@ -1019,7 +1023,10 @@ def retrain_func(
                     num_samples=num_samples,
                     verbose=verbose,
                     predict_likelihood_parameters=predict_likelihood_parameters,
+                    show_warnings=show_predict_warnings,
                 )
+                show_predict_warnings = False
+
                 if forecast_components is None:
                     forecast_components = forecast.columns
 
@@ -2131,6 +2138,7 @@ def predict(
         num_samples: int = 1,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> Union[TimeSeries, Sequence[TimeSeries]]:
         """Forecasts values for `n` time steps after the end of the series.
 
@@ -2169,6 +2177,8 @@ def predict(
             If set to `True`, the model predict the parameters of its Likelihood parameters instead of the target. Only
             supported for probabilistic models with a likelihood, `num_samples = 1` and `n<=output_chunk_length`.
             Default: ``False``
+        show_warnings
+            Whether to show warnings related auto-regression and past covariates usage.
 
         Returns
         -------
@@ -2210,6 +2220,19 @@ def predict(
                     "must be embedded in the target `series` passed to `predict()`."
                 )
             )
+        if (
+            show_warnings
+            and self.uses_past_covariates
+            and self.output_chunk_length is not None
+            and n > self.output_chunk_length
+        ):
+            logger.warning(
+                "Since `predict` was called with `n > output_chunk_length`, auto-regression is be used to forecast "
+                "the values after `output_chunk_length`. As this model uses past covariates, it will access future "
+                "values (compared to the first predicted timestep) of this covariates to produce each subsequent "
+                "`output_chunk_length` forecasts."
+                "To hide this warning, set `show_warnings=False`."
+            )
 
     def _predict_wrapper(
         self,
@@ -2220,6 +2243,7 @@ def _predict_wrapper(
         num_samples: int,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> Union[TimeSeries, Sequence[TimeSeries]]:
         kwargs = dict()
         if self.supports_likelihood_parameter_prediction:
@@ -2231,6 +2255,7 @@ def _predict_wrapper(
             future_covariates=future_covariates,
             num_samples=num_samples,
             verbose=verbose,
+            show_warnings=show_warnings,
             **kwargs,
         )
 
@@ -2465,6 +2490,7 @@ def _predict_wrapper(
         num_samples: int,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> TimeSeries:
         kwargs = dict()
         if self.supports_likelihood_parameter_prediction:
@@ -2682,6 +2708,7 @@ def _predict_wrapper(
         num_samples: int,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> TimeSeries:
         kwargs = dict()
         if self.supports_likelihood_parameter_prediction:

darts/models/forecasting/lgbm.py

@@ -80,7 +80,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that

darts/models/forecasting/linear_regression_model.py

@@ -73,7 +73,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that

darts/models/forecasting/random_forest.py

@@ -77,7 +77,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that

darts/models/forecasting/regression_model.py

@@ -738,6 +738,7 @@ def predict(
         num_samples: int = 1,
         verbose: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
         **kwargs,
     ) -> Union[TimeSeries, Sequence[TimeSeries]]:
         """Forecasts values for `n` time steps after the end of the series.
@@ -813,6 +814,7 @@ def predict(
             num_samples,
             verbose,
             predict_likelihood_parameters,
+            show_warnings,
         )
 
         # check that the input sizes of the target series and covariates match
@@ -1499,7 +1501,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that

darts/models/forecasting/torch_forecasting_model.py

@@ -1226,6 +1226,7 @@ def predict(
         num_loader_workers: int = 0,
         mc_dropout: bool = False,
         predict_likelihood_parameters: bool = False,
+        show_warnings: bool = True,
     ) -> Union[TimeSeries, Sequence[TimeSeries]]:
         """Predict the ``n`` time step following the end of the training series, or of the specified ``series``.
 
@@ -1345,6 +1346,7 @@ def predict(
             future_covariates,
             num_samples=num_samples,
             predict_likelihood_parameters=predict_likelihood_parameters,
+            show_warnings=show_warnings,
         )
 
         dataset = self._build_inference_dataset(

darts/models/forecasting/xgboost.py

@@ -99,7 +99,8 @@ def __init__(
         output_chunk_length
             Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast
             horizon `n` used in `predict()`. However, setting `output_chunk_length` equal to the forecast horizon may
-            be useful if the covariates don't extend far enough into the future.
+            be useful to prevent auto-regression if the covariates don't extend far enough into the future or the
+            future values of the past covariates should not be accessed.
         add_encoders
             A large number of past and future covariates can be automatically generated with `add_encoders`.
             This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that