From 682d15fe2c129d4435057734f9a284e299e37f00 Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Tue, 15 Aug 2023 16:07:40 +0200
Subject: [PATCH 1/8] doc: adding very basic usage example for each model

---
 darts/models/forecasting/arima.py             | 17 ++++
 darts/models/forecasting/auto_arima.py        | 17 ++++
 darts/models/forecasting/baselines.py         | 82 +++++++++++++++++++
 darts/models/forecasting/block_rnn_model.py   | 21 +++++
 darts/models/forecasting/catboost_model.py    | 29 +++++++
 darts/models/forecasting/croston.py           | 17 ++++
 darts/models/forecasting/dlinear.py           | 28 +++++++
 .../forecasting/exponential_smoothing.py      | 18 ++++
 darts/models/forecasting/fft.py               | 20 +++++
 darts/models/forecasting/forecasting_model.py |  5 ++
 darts/models/forecasting/kalman_forecaster.py | 17 ++++
 darts/models/forecasting/lgbm.py              | 30 +++++++
 .../forecasting/linear_regression_model.py    | 44 ++++++++++
 darts/models/forecasting/nbeats.py            | 26 ++++++
 darts/models/forecasting/nhits.py             | 26 ++++++
 darts/models/forecasting/nlinear.py           | 28 +++++++
 darts/models/forecasting/prophet_model.py     | 37 ++++++++-
 darts/models/forecasting/random_forest.py     | 31 +++++++
 .../forecasting/regression_ensemble_model.py  | 34 ++++++++
 darts/models/forecasting/regression_model.py  | 18 ++++
 darts/models/forecasting/rnn_model.py         | 26 ++++++
 darts/models/forecasting/tbats_model.py       | 17 ++++
 darts/models/forecasting/tcn_model.py         | 25 ++++++
 darts/models/forecasting/tft_model.py         | 27 ++++++
 darts/models/forecasting/theta.py             | 33 ++++++++
 darts/models/forecasting/tide_model.py        | 26 ++++++
 darts/models/forecasting/transformer_model.py | 26 +++++-
 darts/models/forecasting/varima.py            | 19 +++++
 darts/models/forecasting/xgboost.py           | 30 +++++++
 29 files changed, 769 insertions(+), 5 deletions(-)

diff --git a/darts/models/forecasting/arima.py b/darts/models/forecasting/arima.py
index 87d3f21279..4b0534407e 100644
--- a/darts/models/forecasting/arima.py
+++ b/darts/models/forecasting/arima.py
@@ -79,6 +79,23 @@ def __init__(
                     'transformer': Scaler()
                 }
             ..
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import ARIMA
+        >>> series = AirPassengersDataset().load()
+        >>> # define ARIMA parameters
+        >>> model = ARIMA(p=12, d=1, q=2)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[448.51505247],
+               [414.33118769],
+               [438.9181897 ],
+               [478.23775116],
+               [499.3940067 ],
+               [554.151738  ]])
         """
         super().__init__(add_encoders=add_encoders)
         self.order = p, d, q
diff --git a/darts/models/forecasting/auto_arima.py b/darts/models/forecasting/auto_arima.py
index 2266917579..04ccd4bab3 100644
--- a/darts/models/forecasting/auto_arima.py
+++ b/darts/models/forecasting/auto_arima.py
@@ -62,6 +62,23 @@ def __init__(
                     'transformer': Scaler()
                 }
             ..
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import AutoARIMA
+        >>> series = AirPassengersDataset().load()
+        >>> # define some boundaries for the parameters
+        >>> model = AutoARIMA(start_p=8, max_p=12, start_q=1)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[447.46348905],
+               [414.15458208],
+               [442.00844015],
+               [483.42738436],
+               [506.05596196],
+               [561.68251165]])
         """
         super().__init__(add_encoders=add_encoders)
         self.model = PmdAutoARIMA(*autoarima_args, **autoarima_kwargs)
diff --git a/darts/models/forecasting/baselines.py b/darts/models/forecasting/baselines.py
index 9dd69902aa..ad976afaa8 100644
--- a/darts/models/forecasting/baselines.py
+++ b/darts/models/forecasting/baselines.py
@@ -26,6 +26,22 @@ def __init__(self):
 
         This model has no parameter, and always predicts the
         mean value of the training series.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import NaiveMean
+        >>> series = AirPassengersDataset().load()
+        >>> model = NaiveMean()
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[280.29861111],
+              [280.29861111],
+              [280.29861111],
+              [280.29861111],
+              [280.29861111],
+              [280.29861111]])
         """
         super().__init__()
         self.mean_val = None
@@ -63,6 +79,23 @@ def __init__(self, K: int = 1):
         ----------
         K
             the number of last time steps of the training set to repeat
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import NaiveSeasonal
+        >>> series = AirPassengersDataset().load()
+        # prior analysis suggested seasonality of 12
+        >>> model = NaiveSeasonal(K=12)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[417.],
+               [391.],
+               [419.],
+               [461.],
+               [472.],
+               [535.]])
         """
         super().__init__()
         self.last_k_vals = None
@@ -106,6 +139,22 @@ def __init__(self):
         and extends it in the future. For a training series of length :math:`T`, we have:
 
         .. math:: \\hat{y}_{T+h} = y_T + h\\left( \\frac{y_T - y_1}{T - 1} \\right)
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import NaiveDrift
+        >>> series = AirPassengersDataset().load()
+        >>> model = NaiveDrift()
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[434.23776224],
+               [436.47552448],
+               [438.71328671],
+               [440.95104895],
+               [443.18881119],
+               [445.42657343]])
         """
         super().__init__()
 
@@ -147,6 +196,22 @@ def __init__(self, input_chunk_length: int = 1):
         ----------
         input_chunk_length
             The size of the sliding window used to calculate the moving average
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import NaiveMovingAverage
+        >>> series = AirPassengersDataset().load()
+        # using the average of the last 6 months
+        >>> model = NaiveMovingAverage(input_chunk_length=6)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[503.16666667],
+               [483.36111111],
+               [462.9212963 ],
+               [455.40817901],
+               [454.47620885],
+               [465.22224366]])
         """
         super().__init__()
         self.input_chunk_length = input_chunk_length
@@ -217,6 +282,23 @@ def __init__(
             List of forecasting models whose predictions to ensemble
         show_warnings
             Whether to show warnings related to models covariates support.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import NaiveEnsembleModel, NaiveSeasonal, NaiveDrift
+        >>> series = AirPassengersDataset().load()
+        >>> # combine two naive models
+        >>> model = NaiveEnsembleModel([NaiveSeasonal(K=12), NaiveDrift()])
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[425.61888112],
+               [413.73776224],
+               [428.85664336],
+               [450.97552448],
+               [457.59440559],
+               [490.21328671]])
         """
         super().__init__(
             models=models,
diff --git a/darts/models/forecasting/block_rnn_model.py b/darts/models/forecasting/block_rnn_model.py
index 90d41deacb..48c55781be 100644
--- a/darts/models/forecasting/block_rnn_model.py
+++ b/darts/models/forecasting/block_rnn_model.py
@@ -74,6 +74,27 @@ def __init__(
         -------
         y of shape `(batch_size, output_chunk_length, target_size, nr_params)`
             Tensor containing the prediction at the last time step of the sequence.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import BlockRNNModel
+        >>> series = AirPassengersDataset().load()
+        >>> model = BlockRNNModel(
+        >>>             input_chunk_length=12,
+        >>>             output_chunk_length=6,
+        >>>             n_rnn_layers=2,
+        >>>             n_epochs=50,
+        >>>             )
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[5.66264695],
+               [6.0170242 ],
+               [6.95271513],
+               [5.65220405],
+               [6.96427217],
+               [6.21813972]])
         """
 
         super().__init__(**kwargs)
diff --git a/darts/models/forecasting/catboost_model.py b/darts/models/forecasting/catboost_model.py
index f3859f8522..524d88b520 100644
--- a/darts/models/forecasting/catboost_model.py
+++ b/darts/models/forecasting/catboost_model.py
@@ -94,6 +94,35 @@ def __init__(
             that all target `series` have the same static covariate dimensionality in ``fit()`` and ``predict()``.
         **kwargs
             Additional keyword arguments passed to `catboost.CatBoostRegressor`.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import CatBoostModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = CatBoostModel(
+        >>>             lags=12,
+        >>>             lags_past_covariates=12,
+        >>>             lags_future_covariates=[0,1,2,3,4,5],
+        >>>             output_chunk_length=6
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1006.4153701 ],
+               [1006.41907237],
+               [1006.30872957],
+               [1006.28614154],
+               [1006.22355514],
+               [1006.21607546]])
         """
         kwargs["random_state"] = random_state  # seed for tree learner
         self.kwargs = kwargs
diff --git a/darts/models/forecasting/croston.py b/darts/models/forecasting/croston.py
index 75029f5ae2..1ce390f0ee 100644
--- a/darts/models/forecasting/croston.py
+++ b/darts/models/forecasting/croston.py
@@ -74,6 +74,23 @@ def __init__(
         .. [2] Ruud H. Teunter, Aris A. Syntetos, and M. Zied Babai.
                Intermittent demand: Linking forecasting to inventory obsolescence.
                European Journal of Operational Research, 214(3):606 – 615, 2011.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import Croston
+        >>> series = AirPassengersDataset().load()
+        >>> # use the optimized version to automatically select best alpha parameter
+        >>> model = Croston(version="optimized")
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[461.7666],
+               [461.7666],
+               [461.7666],
+               [461.7666],
+               [461.7666],
+               [461.7666]])
         """
         super().__init__(add_encoders=add_encoders)
         raise_if_not(
diff --git a/darts/models/forecasting/dlinear.py b/darts/models/forecasting/dlinear.py
index 1d7bcfe6c8..40dbcb793c 100644
--- a/darts/models/forecasting/dlinear.py
+++ b/darts/models/forecasting/dlinear.py
@@ -402,6 +402,34 @@ def __init__(
         ----------
         .. [1] Zeng, A., Chen, M., Zhang, L., & Xu, Q. (2022).
                Are Transformers Effective for Time Series Forecasting?. arXiv preprint arXiv:2205.13504.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import DLinearModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = DLinearModel(
+                        input_chunk_length=6,
+                        output_chunk_length=6,
+                        n_epochs=20,
+                        )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[667.20957388],
+               [666.76986848],
+               [666.67733306],
+               [666.06625381],
+               [665.8529289 ],
+               [665.75320573]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/exponential_smoothing.py b/darts/models/forecasting/exponential_smoothing.py
index e833c8546b..a7a4fdafd0 100644
--- a/darts/models/forecasting/exponential_smoothing.py
+++ b/darts/models/forecasting/exponential_smoothing.py
@@ -66,6 +66,24 @@ def __init__(
             :func:`statsmodels.tsa.holtwinters.ExponentialSmoothing.fit()`.
             See `the documentation
             <https://www.statsmodels.org/stable/generated/statsmodels.tsa.holtwinters.ExponentialSmoothing.fit.html>`_.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import ExponentialSmoothing
+        >>> from darts.utils.utils import ModelMode, SeasonalityMode
+        >>> series = AirPassengersDataset().load()
+        >>> # using Holt's exponential smoothing
+        >>> model = ExponentialSmoothing(trend=ModelMode.ADDITIVE, seasonal=SeasonalityMode.NONE)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[433.86437351],
+               [435.92662262],
+               [437.98887173],
+               [440.05112085],
+               [442.11336996],
+               [444.17561907]])
         """
         super().__init__()
         self.trend = trend
diff --git a/darts/models/forecasting/fft.py b/darts/models/forecasting/fft.py
index 54f2b9d0af..8eeccc18cc 100644
--- a/darts/models/forecasting/fft.py
+++ b/darts/models/forecasting/fft.py
@@ -253,6 +253,26 @@ def __init__(
         global trend, and do not perform any frequency filtering:
 
         >>> FFT(required_matches={'month'}, trend='exp')
+
+        Simple usage example, using one of the dataset available in darts
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import FFT
+        >>> series = AirPassengersDataset().load()
+        >>> # increase the number of frequency and use a polynomial trend of degree 2
+        >>> model = FFT(
+                    nr_freqs_to_keep=20,
+                    trend= "poly",
+                    trend_poly_degree=2
+                    )
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[471.79323146],
+               [494.6381425 ],
+               [504.5659999 ],
+               [515.82463265],
+               [520.59404623],
+               [547.26720705]])
         """
         super().__init__()
         self.nr_freqs_to_keep = nr_freqs_to_keep
diff --git a/darts/models/forecasting/forecasting_model.py b/darts/models/forecasting/forecasting_model.py
index 7d75e9c258..c45ab26156 100644
--- a/darts/models/forecasting/forecasting_model.py
+++ b/darts/models/forecasting/forecasting_model.py
@@ -2257,6 +2257,7 @@ def fit(self, series: TimeSeries, future_covariates: Optional[TimeSeries] = None
         """
 
         if future_covariates is not None:
+            self.future_covariate_series = future_covariates
             if not series.has_same_time_as(future_covariates):
                 # fit() expects future_covariates to have same time as the target, so we intersect it here
                 future_covariates = future_covariates.slice_intersect(series)
@@ -2318,6 +2319,10 @@ def predict(
 
         super().predict(n, num_samples)
 
+        # retrieve the future covariate series saved in fit()
+        if future_covariates is None and self.future_covariate_series is not None:
+            future_covariates = self.future_covariate_series
+
         # avoid generating encodings again if subclass has already generated them
         if not self._supress_generate_predict_encoding:
             self._verify_passed_predict_covariates(future_covariates)
diff --git a/darts/models/forecasting/kalman_forecaster.py b/darts/models/forecasting/kalman_forecaster.py
index 2da16f4421..73d8b8ba8c 100644
--- a/darts/models/forecasting/kalman_forecaster.py
+++ b/darts/models/forecasting/kalman_forecaster.py
@@ -75,6 +75,23 @@ def __init__(
                     'transformer': Scaler()
                 }
             ..
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import KalmanForecaster
+        >>> series = AirPassengersDataset().load()
+        >>> # increasing the size of the state vector
+        >>> model = KalmanForecaster(dim_x=12)
+        >>> model.fit(series)
+        >>> pred = model.predict(26)
+        >>> pred.values()
+        array([[470.87664788],
+               [437.65504495],
+               [463.00699688],
+               [498.1041088 ],
+               [535.31300311],
+               [597.10971248]])
         """
         super().__init__(add_encoders=add_encoders)
         self.dim_x = dim_x
diff --git a/darts/models/forecasting/lgbm.py b/darts/models/forecasting/lgbm.py
index 8f85fe3237..ce62425f84 100644
--- a/darts/models/forecasting/lgbm.py
+++ b/darts/models/forecasting/lgbm.py
@@ -114,6 +114,36 @@ def __init__(
             treated as categorical are integer-encoded.
         **kwargs
             Additional keyword arguments passed to `lightgbm.LGBRegressor`.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import LightGBMModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = LightGBMModel(
+        >>>             lags=12,
+        >>>             lags_past_covariates=12,
+        >>>             lags_future_covariates=[0,1,2,3,4,5],
+        >>>             output_chunk_length=6,
+        >>>             verbose=-1
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1006.85376674],
+               [1006.83998586],
+               [1006.63884831],
+               [1006.57201255],
+               [1006.52290556],
+               [1006.39550065]])
         """
         kwargs["random_state"] = random_state  # seed for tree learner
         self.kwargs = kwargs
diff --git a/darts/models/forecasting/linear_regression_model.py b/darts/models/forecasting/linear_regression_model.py
index 778619bae4..a36c3e1abb 100644
--- a/darts/models/forecasting/linear_regression_model.py
+++ b/darts/models/forecasting/linear_regression_model.py
@@ -96,6 +96,50 @@ def __init__(
             Additional keyword arguments passed to `sklearn.linear_model.LinearRegression` (by default), to
             `sklearn.linear_model.PoissonRegressor` (if `likelihood="poisson"`), or to
             `sklearn.linear_model.QuantileRegressor` (if `likelihood="quantile"`).
+
+        Examples
+        --------
+        Deterministic forecasting, using past/future covariates (optional)
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import LinearRegressionModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = LinearRegressionModel(
+        >>>             lags=12,
+        >>>             lags_past_covariates=12,
+        >>>             lags_future_covariates=[0,1,2,3,4,5],
+        >>>             output_chunk_length=6,
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1005.72085839],
+               [1005.6548696 ],
+               [1005.65403772],
+               [1005.6846175 ],
+               [1005.75753605],
+               [1005.81830675]])
+
+        Probabilistic forecasting, without covariates
+        >>> # train the model with a quantile regression
+        >>> model = LinearRegressionModel(
+        >>>             lags=12,
+        >>>             output_chunk_length=6,
+        >>>             likelihood="quantile",
+        >>>             quantiles=[0.05, 0.5, 0.95]
+        >>>             )
+        >>> model.fit(target)
+        >>> pred = model.predict(6, num_samples=100)
+        >>> # forecast contains 100 samples for each forecasted timestamp
+        >>> pred.all_values().shape
+        (6, 1, 100)
         """
         self.kwargs = kwargs
         self._median_idx = None
diff --git a/darts/models/forecasting/nbeats.py b/darts/models/forecasting/nbeats.py
index 8e1c627c75..c9c5727631 100644
--- a/darts/models/forecasting/nbeats.py
+++ b/darts/models/forecasting/nbeats.py
@@ -722,6 +722,32 @@ def __init__(
         References
         ----------
         .. [1] https://openreview.net/forum?id=r1ecqn4YwB
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import NBEATSModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # changing the activation function of the encoder/decoder to LeakyReLU
+        >>> model = NBEATSModel(
+                        input_chunk_length=6,
+                        output_chunk_length=6,
+                        n_epochs=5,
+                        activation='LeakyReLU'
+                        )
+        >>> model.fit(target, past_covariates=past_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[ 929.78509085],
+               [1013.66339481],
+               [ 999.8843893 ],
+               [ 892.66032082],
+               [ 921.09781534],
+               [ 950.37965429]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/nhits.py b/darts/models/forecasting/nhits.py
index eaba3bc282..108e6ece19 100644
--- a/darts/models/forecasting/nhits.py
+++ b/darts/models/forecasting/nhits.py
@@ -659,6 +659,32 @@ def __init__(
         ----------
         .. [1] C. Challu et al. "N-HiTS: Neural Hierarchical Interpolation for Time Series Forecasting",
                https://arxiv.org/abs/2201.12886
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import NHiTSModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # increasing the number of blocks
+        >>> model = NHiTSModel(
+                        input_chunk_length=6,
+                        output_chunk_length=6,
+                        num_blocks=2,
+                        n_epochs=5,
+                        )
+        >>> model.fit(target, past_covariates=past_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[958.2354389 ],
+               [939.23201079],
+               [987.51425784],
+               [919.41209025],
+               [925.09583093],
+               [938.95625528]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/nlinear.py b/darts/models/forecasting/nlinear.py
index 18242b891c..060bde8cdb 100644
--- a/darts/models/forecasting/nlinear.py
+++ b/darts/models/forecasting/nlinear.py
@@ -351,6 +351,34 @@ def __init__(
         ----------
         .. [1] Zeng, A., Chen, M., Zhang, L., & Xu, Q. (2022).
                Are Transformers Effective for Time Series Forecasting?. arXiv preprint arXiv:2205.13504.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import NLinearModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = NLinearModel(
+                        input_chunk_length=6,
+                        output_chunk_length=6,
+                        n_epochs=20,
+                        )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[429.56117169],
+               [428.93264096],
+               [428.35210616],
+               [428.13154426],
+               [427.98781641],
+               [428.00325481]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/prophet_model.py b/darts/models/forecasting/prophet_model.py
index 51ec270ccd..37df119cfd 100644
--- a/darts/models/forecasting/prophet_model.py
+++ b/darts/models/forecasting/prophet_model.py
@@ -28,11 +28,17 @@ def __init__(
         country_holidays: Optional[str] = None,
         suppress_stdout_stderror: bool = True,
         add_encoders: Optional[dict] = None,
-        cap: Union[
-            float, Callable[[Union[pd.DatetimeIndex, pd.RangeIndex]], Sequence[float]]
+        cap: Optional[
+            Union[
+                float,
+                Callable[[Union[pd.DatetimeIndex, pd.RangeIndex]], Sequence[float]],
+            ]
         ] = None,
-        floor: Union[
-            float, Callable[[Union[pd.DatetimeIndex, pd.RangeIndex]], Sequence[float]]
+        floor: Optional[
+            Union[
+                float,
+                Callable[[Union[pd.DatetimeIndex, pd.RangeIndex]], Sequence[float]],
+            ]
         ] = None,
         **prophet_kwargs,
     ):
@@ -124,6 +130,29 @@ def __init__(
             Some optional keyword arguments for Prophet.
             For information about the parameters see:
             `The Prophet source code <https://github.com/facebook/prophet/blob/master/python/prophet/forecaster.py>`_.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import Prophet
+        >>> series = AirPassengersDataset().load()
+        >>> # supplying the seasonality information to improve accuracy
+        >>> model = Prophet(
+                        add_seasonalities={
+                            'name':"yearly_seasonality",
+                            'seasonal_periods':12,
+                            'fourier_order':20
+                            },
+                        )
+        >>> model.fit(target)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[469.84025187],
+               [465.97709479],
+               [493.98029195],
+               [493.66439198],
+               [498.16068783],
+               [540.44780324]])
         """
 
         super().__init__(add_encoders=add_encoders)
diff --git a/darts/models/forecasting/random_forest.py b/darts/models/forecasting/random_forest.py
index 600f307302..a5514b61f6 100644
--- a/darts/models/forecasting/random_forest.py
+++ b/darts/models/forecasting/random_forest.py
@@ -92,6 +92,37 @@ def __init__(
             that all target `series` have the same static covariate dimensionality in ``fit()`` and ``predict()``.
         **kwargs
             Additional keyword arguments passed to `sklearn.ensemble.RandomForest`.
+
+        Examples
+        --------
+        Deterministic forecasting, using past/future covariates (optional)
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import RandomForest
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # random forest with 200 trees trained with MAE
+        >>> model = RandomForest(
+        >>>             lags=12,
+        >>>             lags_past_covariates=12,
+        >>>             lags_future_covariates=[0,1,2,3,4,5],
+        >>>             output_chunk_length=6,
+        >>>             n_estimators=200,
+        >>>             criterion="absolute_error",
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1006.29805],
+               [1006.23675],
+               [1006.17325],
+               [1006.10295],
+               [1006.06505],
+               [1006.05465]])
         """
         self.n_estimators = n_estimators
         self.max_depth = max_depth
diff --git a/darts/models/forecasting/regression_ensemble_model.py b/darts/models/forecasting/regression_ensemble_model.py
index b26fd10b92..f4926d3052 100644
--- a/darts/models/forecasting/regression_ensemble_model.py
+++ b/darts/models/forecasting/regression_ensemble_model.py
@@ -71,6 +71,40 @@ def __init__(
         References
         ----------
         .. [1] D. H. Wolpert, “Stacked generalization”, Neural Networks, vol. 5, no. 2, pp. 241–259, Jan. 1992
+
+        Examples
+        --------
+        Deterministic forecasting
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, NaiveDrift, LinearRegressionModel
+        >>> series = AirPassengersDataset().load()
+        >>> model = RegressionEnsembleModel(
+                        forecasting_models = [NaiveSeasonal(K=12), NaiveDrift()],
+                        regression_train_n_points=20
+                        )
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[492.02657266],
+               [465.8913335 ],
+               [494.75724139],
+               [537.88270593],
+               [549.43343789],
+               [613.9482374 ]])
+
+        Probabilistic forecasting
+        >>> model = RegressionEnsembleModel(
+        >>>             forecasting_models = [NaiveSeasonal(K=12), NaiveDrift()],
+        >>>             regression_train_n_points=20,
+        >>>             regression_model=LinearRegressionModel(
+        >>>                     lags_future_covariates=[0],
+        >>>                     likelihood="quantile",
+        >>>                     quantiles=[0.05, 0.5, 0.95]
+        >>>                     )
+        >>> model.fit(series)
+        >>> pred = model.predict(6, num_samples=100)
+        >>> pred.all_values().shape
+        (6, 1, 100)
         """
         super().__init__(
             models=forecasting_models,
diff --git a/darts/models/forecasting/regression_model.py b/darts/models/forecasting/regression_model.py
index 1849dd8d1c..47def7d0bb 100644
--- a/darts/models/forecasting/regression_model.py
+++ b/darts/models/forecasting/regression_model.py
@@ -121,6 +121,24 @@ def __init__(
             Whether the model should use static covariate information in case the input `series` passed to ``fit()``
             contain static covariates. If ``True``, and static covariates are available at fitting time, will enforce
             that all target `series` have the same static covariate dimensionality in ``fit()`` and ``predict()``.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import RegressionModel
+        >>> from sklearn.linear_model import Ridge
+        >>> series = AirPassengersDataset().load()
+        >>> # wrap around the sklearn Ridge model
+        >>> model = RegressionModel(model=Ridge(), output_chunk_length=6, lags=12)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[465.35957261],
+               [431.07506438],
+               [459.23606073],
+               [503.10942733],
+               [528.02603021],
+               [588.43860056]])
         """
 
         super().__init__(add_encoders=add_encoders)
diff --git a/darts/models/forecasting/rnn_model.py b/darts/models/forecasting/rnn_model.py
index eb3ce4f434..0c0047cb88 100644
--- a/darts/models/forecasting/rnn_model.py
+++ b/darts/models/forecasting/rnn_model.py
@@ -383,6 +383,32 @@ def __init__(
         show_warnings
             whether to show warnings raised from PyTorch Lightning. Useful to detect potential issues of
             your forecasting use case. Default: ``False``.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import RNNModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # `training_length` > `input_chunk_length` to mimic inference constraints
+        >>> model = RNNModel(
+                        model="RNN",
+                        input_chunk_length=6,
+                        training_length=18,
+                        n_epochs=20,
+                        )
+        >>> model.fit(target, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[ 3.18922903],
+               [ 1.17791019],
+               [ 0.39992814],
+               [ 0.13277921],
+               [ 0.02523252],
+               [-0.01829086]])
         """
         # create copy of model parameters
         model_kwargs = {key: val for key, val in self.model_params.items()}
diff --git a/darts/models/forecasting/tbats_model.py b/darts/models/forecasting/tbats_model.py
index d1eaf6d1f5..5ac43e2640 100644
--- a/darts/models/forecasting/tbats_model.py
+++ b/darts/models/forecasting/tbats_model.py
@@ -173,6 +173,23 @@ def __init__(
             See https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods
         random_state
             Sets the underlying random seed at model initialization time.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import TBATS
+        >>> series = AirPassengersDataset().load()
+        >>> # based on preliminary analysis, the series contains a trend
+        >>> model = TBATS(use_trend=True)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[448.29856017],
+               [439.42215052],
+               [507.73465028],
+               [493.03751671],
+               [498.85885374],
+               [564.64871897]])
         """
         super().__init__()
 
diff --git a/darts/models/forecasting/tcn_model.py b/darts/models/forecasting/tcn_model.py
index 16cd3b1350..63d4c6f759 100644
--- a/darts/models/forecasting/tcn_model.py
+++ b/darts/models/forecasting/tcn_model.py
@@ -424,6 +424,31 @@ def __init__(
         References
         ----------
         .. [1] https://arxiv.org/abs/1803.01271
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import TCNModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # `output_chunk_length` must be strictly smaller than `input_chunk_length`
+        >>> model = TCNModel(
+                        input_chunk_length=12,
+                        output_chunk_length=6,
+                        n_epochs=20,
+                        )
+        >>> model.fit(target, past_covariates=past_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[-80.48476824],
+               [-80.47896667],
+               [-41.77135603],
+               [-41.76158729],
+               [-41.76854107],
+               [-41.78166819]])
         """
 
         raise_if_not(
diff --git a/darts/models/forecasting/tft_model.py b/darts/models/forecasting/tft_model.py
index cd40ece3dd..0111bb6137 100644
--- a/darts/models/forecasting/tft_model.py
+++ b/darts/models/forecasting/tft_model.py
@@ -871,6 +871,33 @@ def __init__(
         ----------
         .. [1] https://arxiv.org/pdf/1912.09363.pdf
         ..[2] Shazeer, Noam, "GLU Variants Improve Transformer", 2020. arVix https://arxiv.org/abs/2002.05202.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import TFTModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> model = TFTModel(
+        >>>             input_chunk_length=6,
+        >>>             output_chunk_length=6,
+        >>>             n_epochs=5,
+        >>>             )
+        >>> # future_covariates is mandatory for `TFTModel`
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[0.09969039],
+               [0.27813781],
+               [0.45841935],
+               [0.15467635],
+               [0.17572287],
+               [0.55062653]])
         """
         model_kwargs = {key: val for key, val in self.model_params.items()}
         if likelihood is None and loss_fn is None:
diff --git a/darts/models/forecasting/theta.py b/darts/models/forecasting/theta.py
index 92eac610f9..40f7425431 100644
--- a/darts/models/forecasting/theta.py
+++ b/darts/models/forecasting/theta.py
@@ -58,6 +58,23 @@ def __init__(
         References
         ----------
         .. [1] `Unmasking the Theta method <https://robjhyndman.com/papers/Theta.pdf`
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import Theta
+        >>> series = AirPassengersDataset().load()
+        >>> # using the canonical Theta method
+        >>> model = Theta(theta=2)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[442.7256909 ],
+               [433.74381763],
+               [494.54534585],
+               [480.36937856],
+               [481.06675142],
+               [545.80068173]])
         """
 
         super().__init__()
@@ -250,6 +267,22 @@ def __init__(
         -----
         Even though this model is an improvement of :class:`Theta`, it is a naive
         implementation of the algorithm, which can potentially be slower.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import FourTheta
+        >>> series = AirPassengersDataset().load()
+        >>> model = FourTheta(theta=2)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[443.3949283 ],
+               [434.39769555],
+               [495.28886231],
+               [481.08962991],
+               [481.78610361],
+               [546.61463773]])
         """
 
         super().__init__()
diff --git a/darts/models/forecasting/tide_model.py b/darts/models/forecasting/tide_model.py
index 4da7f33d7f..c1c6be9f72 100644
--- a/darts/models/forecasting/tide_model.py
+++ b/darts/models/forecasting/tide_model.py
@@ -530,6 +530,32 @@ def __init__(
                 http://arxiv.org/abs/2304.08424
         .. [2] T. Kim et al. "Reversible Instance Normalization for Accurate Time-Series Forecasting against
                 Distribution Shift", https://openreview.net/forum?id=cGDAkQo1C0p
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import TiDEModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> model = TiDEModel(
+        >>>             input_chunk_length=6,
+        >>>             output_chunk_length=6,
+        >>>             n_epochs=20
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1008.1667634 ],
+               [ 997.08337201],
+               [1017.72035839],
+               [1005.10790392],
+               [ 998.90537286],
+               [1005.91534452]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/transformer_model.py b/darts/models/forecasting/transformer_model.py
index c1bc94bcfd..bb0a057965 100644
--- a/darts/models/forecasting/transformer_model.py
+++ b/darts/models/forecasting/transformer_model.py
@@ -520,11 +520,35 @@ def __init__(
         Disclaimer:
         This current implementation is fully functional and can already produce some good predictions. However,
         it is still limited in how it uses the Transformer architecture because the `tgt` input of
-        `torch.nn.Transformer` is not utlized to its full extent. Currently, we simply pass the last value of the
+        `torch.nn.Transformer` is not utilized to its full extent. Currently, we simply pass the last value of the
         `src` input to `tgt`. To get closer to the way the Transformer is usually used in language models, we
         should allow the model to consume its own output as part of the `tgt` argument, such that when predicting
         sequences of values, the input to the `tgt` argument would grow as outputs of the transformer model would be
         added to it. Of course, the training of the model would have to be adapted accordingly.
+
+        Examples
+        --------
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import TransformerModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> model = TransformerModel(
+        >>>             input_chunk_length=6,
+        >>>             output_chunk_length=6,
+        >>>             n_epochs=20
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[5.40498034],
+               [5.36561899],
+               [5.80616883],
+               [6.48695488],
+               [7.63158655],
+               [5.65417736]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/varima.py b/darts/models/forecasting/varima.py
index e310e4b06e..bc69045177 100644
--- a/darts/models/forecasting/varima.py
+++ b/darts/models/forecasting/varima.py
@@ -71,6 +71,25 @@ def __init__(
                     'transformer': Scaler()
                 }
             ..
+
+        Examples
+        --------
+        >>> from darts.datasets import ETTh2Dataset
+        >>> from darts.models import VARIMA
+        >>> # forecasting the High UseFul Load ("HUFL") and Oil Temperature ("OT")
+        >>> series = ETTh2Dataset().load()[:500][["HUFL", "OT"]]
+        >>> # no clear trend in the dataset
+        >>> model = VARIMA(trend="n")
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> # the two targets are predicted together
+        >>> pred.values()
+        array([[48.11908832, 47.94259927],
+               [49.85410722, 47.9768968 ],
+               [51.16256336, 47.99770988],
+               [52.14787078, 48.00830983],
+               [52.88837291, 48.01117491],
+               [53.44342041, 48.00818257]])
         """
         super().__init__(add_encoders=add_encoders)
         self.p = p
diff --git a/darts/models/forecasting/xgboost.py b/darts/models/forecasting/xgboost.py
index ef693f4723..f26864e98d 100644
--- a/darts/models/forecasting/xgboost.py
+++ b/darts/models/forecasting/xgboost.py
@@ -112,6 +112,36 @@ def __init__(
             that all target `series` have the same static covariate dimensionality in ``fit()`` and ``predict()``.
         **kwargs
             Additional keyword arguments passed to `xgb.XGBRegressor`.
+
+        Examples
+        --------
+        Deterministic forecasting, using past/future covariates (optional)
+        >>> from darts.datasets import WeatherDataset
+        >>> from darts.models import XGBModel
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
+        >>> # values corresponding to the forecasted period
+        >>> model = XGBModel(
+        >>>             lags=12,
+        >>>             lags_past_covariates=12,
+        >>>             lags_future_covariates=[0,1,2,3,4,5],
+        >>>             output_chunk_length=6,
+        >>>             )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[1005.9185 ],
+               [1005.8315 ],
+               [1005.7878 ],
+               [1005.72626],
+               [1005.7475 ],
+               [1005.76074]])
         """
         kwargs["random_state"] = random_state  # seed for tree learner
         self.kwargs = kwargs

From a6f5c495098543ae82ad0a9ce694abac3d4cc297 Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Mon, 4 Sep 2023 10:46:51 +0200
Subject: [PATCH 2/8] doc: addressing review comments

---
 darts/models/forecasting/arima.py             | 19 ++++----
 darts/models/forecasting/auto_arima.py        | 17 ++++---
 darts/models/forecasting/baselines.py         | 18 ++++----
 darts/models/forecasting/block_rnn_model.py   | 45 ++++++++++---------
 darts/models/forecasting/catboost_model.py    | 14 +++---
 darts/models/forecasting/dlinear.py           | 12 ++---
 .../forecasting/exponential_smoothing.py      | 14 +++---
 darts/models/forecasting/fft.py               |  8 ++--
 darts/models/forecasting/kalman_forecaster.py | 19 ++++----
 darts/models/forecasting/lgbm.py              | 16 +++----
 .../forecasting/linear_regression_model.py    | 28 +++---------
 darts/models/forecasting/nbeats.py            | 12 ++---
 darts/models/forecasting/nhits.py             | 12 ++---
 darts/models/forecasting/nlinear.py           | 12 ++---
 darts/models/forecasting/prophet_model.py     | 32 +++++++------
 darts/models/forecasting/random_forest.py     | 19 ++++----
 .../forecasting/regression_ensemble_model.py  | 35 +++++----------
 darts/models/forecasting/regression_model.py  | 32 ++++++++-----
 darts/models/forecasting/rnn_model.py         | 12 ++---
 darts/models/forecasting/tcn_model.py         | 10 ++---
 darts/models/forecasting/tft_model.py         | 36 ++++++++-------
 darts/models/forecasting/tide_model.py        | 12 ++---
 darts/models/forecasting/transformer_model.py | 12 ++---
 darts/models/forecasting/varima.py            | 15 ++++---
 darts/models/forecasting/xgboost.py           | 14 +++---
 25 files changed, 241 insertions(+), 234 deletions(-)

diff --git a/darts/models/forecasting/arima.py b/darts/models/forecasting/arima.py
index 4b0534407e..d856f14f7b 100644
--- a/darts/models/forecasting/arima.py
+++ b/darts/models/forecasting/arima.py
@@ -84,18 +84,21 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import ARIMA
+        >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> series = AirPassengersDataset().load()
+        >>> # optionally, encode the holidays as a future covariates
+        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
         >>> # define ARIMA parameters
         >>> model = ARIMA(p=12, d=1, q=2)
-        >>> model.fit(series)
-        >>> pred = model.predict(6)
+        >>> model.fit(series, future_covariates=future_cov)
+        >>> pred = model.predict(6, future_covariates=future_cov)
         >>> pred.values()
-        array([[448.51505247],
-               [414.33118769],
-               [438.9181897 ],
-               [478.23775116],
-               [499.3940067 ],
-               [554.151738  ]])
+        array([[447.94644074],
+               [414.35377794],
+               [437.74584582],
+               [477.87154457],
+               [498.54135753],
+               [554.29890434]])
         """
         super().__init__(add_encoders=add_encoders)
         self.order = p, d, q
diff --git a/darts/models/forecasting/auto_arima.py b/darts/models/forecasting/auto_arima.py
index 04ccd4bab3..e17dc22249 100644
--- a/darts/models/forecasting/auto_arima.py
+++ b/darts/models/forecasting/auto_arima.py
@@ -67,18 +67,21 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import AutoARIMA
+        >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> series = AirPassengersDataset().load()
+        >>> # optionally, encode the holidays as a future covariates
+        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
         >>> # define some boundaries for the parameters
         >>> model = AutoARIMA(start_p=8, max_p=12, start_q=1)
-        >>> model.fit(series)
+        >>> model.fit(series, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[447.46348905],
-               [414.15458208],
-               [442.00844015],
-               [483.42738436],
-               [506.05596196],
-               [561.68251165]])
+        array([[447.66109213],
+               [414.24345894],
+               [440.96002246],
+               [483.5631593 ],
+               [505.61540834],
+               [562.53749429]])
         """
         super().__init__(add_encoders=add_encoders)
         self.model = PmdAutoARIMA(*autoarima_args, **autoarima_kwargs)
diff --git a/darts/models/forecasting/baselines.py b/darts/models/forecasting/baselines.py
index ad976afaa8..56dbc00e27 100644
--- a/darts/models/forecasting/baselines.py
+++ b/darts/models/forecasting/baselines.py
@@ -286,19 +286,19 @@ def __init__(
         Examples
         --------
         >>> from darts.datasets import AirPassengersDataset
-        >>> from darts.models import NaiveEnsembleModel, NaiveSeasonal, NaiveDrift
+        >>> from darts.models import NaiveEnsembleModel, NaiveSeasonal, LinearRegressionModel
         >>> series = AirPassengersDataset().load()
-        >>> # combine two naive models
-        >>> model = NaiveEnsembleModel([NaiveSeasonal(K=12), NaiveDrift()])
+        >>> # defining the ensemble
+        >>> model = NaiveEnsembleModel([NaiveSeasonal(K=12), LinearRegressionModel(lags=4)])
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[425.61888112],
-               [413.73776224],
-               [428.85664336],
-               [450.97552448],
-               [457.59440559],
-               [490.21328671]])
+        array([[439.23152974],
+               [431.41161602],
+               [439.72888401],
+               [453.70180806],
+               [454.96757177],
+               [485.16604194]])
         """
         super().__init__(
             models=models,
diff --git a/darts/models/forecasting/block_rnn_model.py b/darts/models/forecasting/block_rnn_model.py
index 48c55781be..a6fe788a21 100644
--- a/darts/models/forecasting/block_rnn_model.py
+++ b/darts/models/forecasting/block_rnn_model.py
@@ -74,27 +74,6 @@ def __init__(
         -------
         y of shape `(batch_size, output_chunk_length, target_size, nr_params)`
             Tensor containing the prediction at the last time step of the sequence.
-
-        Examples
-        --------
-        >>> from darts.datasets import AirPassengersDataset
-        >>> from darts.models import BlockRNNModel
-        >>> series = AirPassengersDataset().load()
-        >>> model = BlockRNNModel(
-        >>>             input_chunk_length=12,
-        >>>             output_chunk_length=6,
-        >>>             n_rnn_layers=2,
-        >>>             n_epochs=50,
-        >>>             )
-        >>> model.fit(series)
-        >>> pred = model.predict(6)
-        >>> pred.values()
-        array([[5.66264695],
-               [6.0170242 ],
-               [6.95271513],
-               [5.65220405],
-               [6.96427217],
-               [6.21813972]])
         """
 
         super().__init__(**kwargs)
@@ -317,6 +296,30 @@ def __init__(
         show_warnings
             whether to show warnings raised from PyTorch Lightning. Useful to detect potential issues of
             your forecasting use case. Default: ``False``.
+
+        Examples
+        --------
+        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import BlockRNNModel
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dt_attr
+        >>> series = AirPassengersDataset().load()
+        >>> # optionnaly, one-hot encode the months as a past covariates
+        >>> past_cov = dt_attr(series, "month")
+        >>> model = BlockRNNModel(
+        >>>   input_chunk_length=12,
+        >>>   output_chunk_length=6,
+        >>>   n_rnn_layers=2,
+        >>>   n_epochs=50,
+        >>>   )
+        >>> model.fit(series, past_covariates=past_cov)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[5.6068386 ],
+               [6.10806508],
+               [6.48818782],
+               [5.30463617],
+               [5.24570622],
+               [6.42277716]])
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/catboost_model.py b/darts/models/forecasting/catboost_model.py
index 524d88b520..99ba39a145 100644
--- a/darts/models/forecasting/catboost_model.py
+++ b/darts/models/forecasting/catboost_model.py
@@ -102,18 +102,18 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = CatBoostModel(
-        >>>             lags=12,
-        >>>             lags_past_covariates=12,
-        >>>             lags_future_covariates=[0,1,2,3,4,5],
-        >>>             output_chunk_length=6
-        >>>             )
+        >>>   lags=12,
+        >>>   lags_past_covariates=12,
+        >>>   lags_future_covariates=[0,1,2,3,4,5],
+        >>>   output_chunk_length=6
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/dlinear.py b/darts/models/forecasting/dlinear.py
index 40dbcb793c..fc0d868827 100644
--- a/darts/models/forecasting/dlinear.py
+++ b/darts/models/forecasting/dlinear.py
@@ -410,17 +410,17 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = DLinearModel(
-                        input_chunk_length=6,
-                        output_chunk_length=6,
-                        n_epochs=20,
-                        )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=20,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/exponential_smoothing.py b/darts/models/forecasting/exponential_smoothing.py
index a7a4fdafd0..dda34b6992 100644
--- a/darts/models/forecasting/exponential_smoothing.py
+++ b/darts/models/forecasting/exponential_smoothing.py
@@ -74,16 +74,16 @@ def __init__(
         >>> from darts.utils.utils import ModelMode, SeasonalityMode
         >>> series = AirPassengersDataset().load()
         >>> # using Holt's exponential smoothing
-        >>> model = ExponentialSmoothing(trend=ModelMode.ADDITIVE, seasonal=SeasonalityMode.NONE)
+        >>> model = ExponentialSmoothing(trend=ModelMode.ADDITIVE, seasonal=SeasonalityMode.MULTIPLICATIVE)
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[433.86437351],
-               [435.92662262],
-               [437.98887173],
-               [440.05112085],
-               [442.11336996],
-               [444.17561907]])
+        array([[445.24283838],
+               [418.22618932],
+               [465.31305075],
+               [494.95129261],
+               [505.4770514 ],
+               [573.31519186]])
         """
         super().__init__()
         self.trend = trend
diff --git a/darts/models/forecasting/fft.py b/darts/models/forecasting/fft.py
index 8eeccc18cc..65cb32e0ab 100644
--- a/darts/models/forecasting/fft.py
+++ b/darts/models/forecasting/fft.py
@@ -260,10 +260,10 @@ def __init__(
         >>> series = AirPassengersDataset().load()
         >>> # increase the number of frequency and use a polynomial trend of degree 2
         >>> model = FFT(
-                    nr_freqs_to_keep=20,
-                    trend= "poly",
-                    trend_poly_degree=2
-                    )
+        >>>   nr_freqs_to_keep=20,
+        >>>   trend= "poly",
+        >>>   trend_poly_degree=2
+        >>>   )
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/kalman_forecaster.py b/darts/models/forecasting/kalman_forecaster.py
index 73d8b8ba8c..52f20eadb3 100644
--- a/darts/models/forecasting/kalman_forecaster.py
+++ b/darts/models/forecasting/kalman_forecaster.py
@@ -80,18 +80,21 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import KalmanForecaster
+        >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> series = AirPassengersDataset().load()
+        >>> # optionally, encode the holidays as a future covariates
+        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
         >>> # increasing the size of the state vector
         >>> model = KalmanForecaster(dim_x=12)
-        >>> model.fit(series)
-        >>> pred = model.predict(26)
+        >>> model.fit(series, future_covariates=future_cov)
+        >>> pred = model.predict(6)
         >>> pred.values()
-        array([[470.87664788],
-               [437.65504495],
-               [463.00699688],
-               [498.1041088 ],
-               [535.31300311],
-               [597.10971248]])
+        array([[446.14067242],
+               [419.48270858],
+               [456.67694119],
+               [481.59399823],
+               [511.5273642 ],
+               [574.9500178 ]])
         """
         super().__init__(add_encoders=add_encoders)
         self.dim_x = dim_x
diff --git a/darts/models/forecasting/lgbm.py b/darts/models/forecasting/lgbm.py
index ce62425f84..26faa4f7d2 100644
--- a/darts/models/forecasting/lgbm.py
+++ b/darts/models/forecasting/lgbm.py
@@ -122,19 +122,19 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = LightGBMModel(
-        >>>             lags=12,
-        >>>             lags_past_covariates=12,
-        >>>             lags_future_covariates=[0,1,2,3,4,5],
-        >>>             output_chunk_length=6,
-        >>>             verbose=-1
-        >>>             )
+        >>>   lags=12,
+        >>>   lags_past_covariates=12,
+        >>>   lags_future_covariates=[0,1,2,3,4,5],
+        >>>   output_chunk_length=6,
+        >>>   verbose=-1
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/linear_regression_model.py b/darts/models/forecasting/linear_regression_model.py
index a36c3e1abb..b41f20ffc8 100644
--- a/darts/models/forecasting/linear_regression_model.py
+++ b/darts/models/forecasting/linear_regression_model.py
@@ -105,18 +105,18 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = LinearRegressionModel(
-        >>>             lags=12,
-        >>>             lags_past_covariates=12,
-        >>>             lags_future_covariates=[0,1,2,3,4,5],
-        >>>             output_chunk_length=6,
-        >>>             )
+        >>>   lags=12,
+        >>>   lags_past_covariates=12,
+        >>>   lags_future_covariates=[0,1,2,3,4,5],
+        >>>   output_chunk_length=6,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -126,20 +126,6 @@ def __init__(
                [1005.6846175 ],
                [1005.75753605],
                [1005.81830675]])
-
-        Probabilistic forecasting, without covariates
-        >>> # train the model with a quantile regression
-        >>> model = LinearRegressionModel(
-        >>>             lags=12,
-        >>>             output_chunk_length=6,
-        >>>             likelihood="quantile",
-        >>>             quantiles=[0.05, 0.5, 0.95]
-        >>>             )
-        >>> model.fit(target)
-        >>> pred = model.predict(6, num_samples=100)
-        >>> # forecast contains 100 samples for each forecasted timestamp
-        >>> pred.all_values().shape
-        (6, 1, 100)
         """
         self.kwargs = kwargs
         self._median_idx = None
diff --git a/darts/models/forecasting/nbeats.py b/darts/models/forecasting/nbeats.py
index c9c5727631..5edfd4b314 100644
--- a/darts/models/forecasting/nbeats.py
+++ b/darts/models/forecasting/nbeats.py
@@ -730,15 +730,15 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> # changing the activation function of the encoder/decoder to LeakyReLU
         >>> model = NBEATSModel(
-                        input_chunk_length=6,
-                        output_chunk_length=6,
-                        n_epochs=5,
-                        activation='LeakyReLU'
-                        )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=5,
+        >>>   activation='LeakyReLU'
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/nhits.py b/darts/models/forecasting/nhits.py
index 108e6ece19..ad411909e9 100644
--- a/darts/models/forecasting/nhits.py
+++ b/darts/models/forecasting/nhits.py
@@ -667,15 +667,15 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> # increasing the number of blocks
         >>> model = NHiTSModel(
-                        input_chunk_length=6,
-                        output_chunk_length=6,
-                        num_blocks=2,
-                        n_epochs=5,
-                        )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   num_blocks=2,
+        >>>   n_epochs=5,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/nlinear.py b/darts/models/forecasting/nlinear.py
index 060bde8cdb..f857224a4d 100644
--- a/darts/models/forecasting/nlinear.py
+++ b/darts/models/forecasting/nlinear.py
@@ -359,17 +359,17 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = NLinearModel(
-                        input_chunk_length=6,
-                        output_chunk_length=6,
-                        n_epochs=20,
-                        )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=20,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/prophet_model.py b/darts/models/forecasting/prophet_model.py
index 37df119cfd..4c5dd26f51 100644
--- a/darts/models/forecasting/prophet_model.py
+++ b/darts/models/forecasting/prophet_model.py
@@ -135,24 +135,28 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import Prophet
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dt_attr
         >>> series = AirPassengersDataset().load()
-        >>> # supplying the seasonality information to improve accuracy
+        >>> # optionally, one-hot encode the months as a future covariates
+        >>> future_cov = dt_attr(series, "month", one_hot=True, add_length=6)
+        >>> # adding a seasonality (yearly and weekly are included by default) and holidays
         >>> model = Prophet(
-                        add_seasonalities={
-                            'name':"yearly_seasonality",
-                            'seasonal_periods':12,
-                            'fourier_order':20
-                            },
-                        )
-        >>> model.fit(target)
+        >>>   add_seasonalities={
+        >>>       'name':"quarterly_seasonality",
+        >>>       'seasonal_periods':4,
+        >>>       'fourier_order':5
+        >>>       },
+        >>>   country_holidays="US"
+        >>>   )
+        >>> model.fit(series, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[469.84025187],
-               [465.97709479],
-               [493.98029195],
-               [493.66439198],
-               [498.16068783],
-               [540.44780324]])
+        array([[472.26891239],
+               [467.56955721],
+               [494.47230467],
+               [493.10568429],
+               [497.54686113],
+               [539.11716811]])
         """
 
         super().__init__(add_encoders=add_encoders)
diff --git a/darts/models/forecasting/random_forest.py b/darts/models/forecasting/random_forest.py
index a5514b61f6..f019db2add 100644
--- a/darts/models/forecasting/random_forest.py
+++ b/darts/models/forecasting/random_forest.py
@@ -95,25 +95,24 @@ def __init__(
 
         Examples
         --------
-        Deterministic forecasting, using past/future covariates (optional)
         >>> from darts.datasets import WeatherDataset
         >>> from darts.models import RandomForest
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # random forest with 200 trees trained with MAE
         >>> model = RandomForest(
-        >>>             lags=12,
-        >>>             lags_past_covariates=12,
-        >>>             lags_future_covariates=[0,1,2,3,4,5],
-        >>>             output_chunk_length=6,
-        >>>             n_estimators=200,
-        >>>             criterion="absolute_error",
-        >>>             )
+        >>>   lags=12,
+        >>>   lags_past_covariates=12,
+        >>>   lags_future_covariates=[0,1,2,3,4,5],
+        >>>   output_chunk_length=6,
+        >>>   n_estimators=200,
+        >>>   criterion="absolute_error",
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/regression_ensemble_model.py b/darts/models/forecasting/regression_ensemble_model.py
index f4926d3052..07065fbed2 100644
--- a/darts/models/forecasting/regression_ensemble_model.py
+++ b/darts/models/forecasting/regression_ensemble_model.py
@@ -74,37 +74,22 @@ def __init__(
 
         Examples
         --------
-        Deterministic forecasting
         >>> from darts.datasets import AirPassengersDataset
-        >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, NaiveDrift, LinearRegressionModel
+        >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, LinearRegressionModel
         >>> series = AirPassengersDataset().load()
         >>> model = RegressionEnsembleModel(
-                        forecasting_models = [NaiveSeasonal(K=12), NaiveDrift()],
-                        regression_train_n_points=20
-                        )
+              forecasting_models = [NaiveSeasonal(K=12), LinearRegressionModel(lags=4)],
+              regression_train_n_points=20
+              )
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[492.02657266],
-               [465.8913335 ],
-               [494.75724139],
-               [537.88270593],
-               [549.43343789],
-               [613.9482374 ]])
-
-        Probabilistic forecasting
-        >>> model = RegressionEnsembleModel(
-        >>>             forecasting_models = [NaiveSeasonal(K=12), NaiveDrift()],
-        >>>             regression_train_n_points=20,
-        >>>             regression_model=LinearRegressionModel(
-        >>>                     lags_future_covariates=[0],
-        >>>                     likelihood="quantile",
-        >>>                     quantiles=[0.05, 0.5, 0.95]
-        >>>                     )
-        >>> model.fit(series)
-        >>> pred = model.predict(6, num_samples=100)
-        >>> pred.all_values().shape
-        (6, 1, 100)
+        array([[494.24050364],
+               [464.3869697 ],
+               [496.53180506],
+               [544.82269341],
+               [557.35256055],
+               [630.24334385]])
         """
         super().__init__(
             models=forecasting_models,
diff --git a/darts/models/forecasting/regression_model.py b/darts/models/forecasting/regression_model.py
index 4aa743112e..785da1dd22 100644
--- a/darts/models/forecasting/regression_model.py
+++ b/darts/models/forecasting/regression_model.py
@@ -129,21 +129,33 @@ def __init__(
 
         Examples
         --------
-        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.datasets import WeatherDataset
         >>> from darts.models import RegressionModel
         >>> from sklearn.linear_model import Ridge
-        >>> series = AirPassengersDataset().load()
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
+        >>> future_cov = series['T (degC)'][:106]
         >>> # wrap around the sklearn Ridge model
-        >>> model = RegressionModel(model=Ridge(), output_chunk_length=6, lags=12)
-        >>> model.fit(series)
+        >>> model = RegressionModel(
+        >>>   model=Ridge(),
+        >>>   lags=12,
+        >>>   lags_past_covariates=4,
+        >>>   lags_future_covariates=(0,6),
+        >>>   output_chunk_length=6
+        >>>   )
+        >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[465.35957261],
-               [431.07506438],
-               [459.23606073],
-               [503.10942733],
-               [528.02603021],
-               [588.43860056]])
+        array([[1005.73340676],
+               [1005.71159051],
+               [1005.7322616 ],
+               [1005.76314504],
+               [1005.82204348],
+               [1005.89100967]])
         """
 
         super().__init__(add_encoders=add_encoders)
diff --git a/darts/models/forecasting/rnn_model.py b/darts/models/forecasting/rnn_model.py
index 0c0047cb88..0e0e4c429e 100644
--- a/darts/models/forecasting/rnn_model.py
+++ b/darts/models/forecasting/rnn_model.py
@@ -391,15 +391,15 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # `training_length` > `input_chunk_length` to mimic inference constraints
         >>> model = RNNModel(
-                        model="RNN",
-                        input_chunk_length=6,
-                        training_length=18,
-                        n_epochs=20,
-                        )
+        >>>   model="RNN",
+        >>>   input_chunk_length=6,
+        >>>   training_length=18,
+        >>>   n_epochs=20,
+        >>>   )
         >>> model.fit(target, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/tcn_model.py b/darts/models/forecasting/tcn_model.py
index 63d4c6f759..51c326ae4d 100644
--- a/darts/models/forecasting/tcn_model.py
+++ b/darts/models/forecasting/tcn_model.py
@@ -432,14 +432,14 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> # `output_chunk_length` must be strictly smaller than `input_chunk_length`
         >>> model = TCNModel(
-                        input_chunk_length=12,
-                        output_chunk_length=6,
-                        n_epochs=20,
-                        )
+        >>>   input_chunk_length=12,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=20,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/tft_model.py b/darts/models/forecasting/tft_model.py
index 0111bb6137..4724e0456d 100644
--- a/darts/models/forecasting/tft_model.py
+++ b/darts/models/forecasting/tft_model.py
@@ -870,7 +870,7 @@ def __init__(
         References
         ----------
         .. [1] https://arxiv.org/pdf/1912.09363.pdf
-        ..[2] Shazeer, Noam, "GLU Variants Improve Transformer", 2020. arVix https://arxiv.org/abs/2002.05202.
+        .. [2] Shazeer, Noam, "GLU Variants Improve Transformer", 2020. arVix https://arxiv.org/abs/2002.05202.
 
         Examples
         --------
@@ -879,25 +879,31 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> # future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
+        >>> # by default, TFTModel is trained using a `QuantileRegression`
         >>> model = TFTModel(
-        >>>             input_chunk_length=6,
-        >>>             output_chunk_length=6,
-        >>>             n_epochs=5,
-        >>>             )
-        >>> # future_covariates is mandatory for `TFTModel`
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=5,
+        >>>   )
+        >>> # future_covariates are mandatory for `TFTModel`
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
-        >>> pred = model.predict(6)
-        >>> pred.values()
-        array([[0.09969039],
-               [0.27813781],
-               [0.45841935],
-               [0.15467635],
-               [0.17572287],
-               [0.55062653]])
+        >>> # using `num_samples > 1`, the model generates a probabilistic forecast
+        >>> pred = model.predict(6, num_samples=100)
+        >>> # shape : (forecast horizon, components, num_samples)
+        >>> pred.all_values().shape
+        (6, 1, 100)
+        >>> # showing the first 3 samples for each timestamp
+        >>> pred.all_values()[:,:,:3]
+        array([[[-0.06414202, -0.7188093 ,  0.52541292]],
+               [[ 0.02928407, -0.40867163,  1.19650033]],
+               [[ 0.77252372, -0.50859694,  0.360166  ]],
+               [[ 0.9586113 ,  1.24147138, -0.01625545]],
+               [[ 1.06863863,  0.2987822 , -0.69213369]],
+               [[-0.83076568, -0.25780816, -0.28318784]]])
         """
         model_kwargs = {key: val for key, val in self.model_params.items()}
         if likelihood is None and loss_fn is None:
diff --git a/darts/models/forecasting/tide_model.py b/darts/models/forecasting/tide_model.py
index c1c6be9f72..66ebf69f71 100644
--- a/darts/models/forecasting/tide_model.py
+++ b/darts/models/forecasting/tide_model.py
@@ -538,15 +538,15 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> model = TiDEModel(
-        >>>             input_chunk_length=6,
-        >>>             output_chunk_length=6,
-        >>>             n_epochs=20
-        >>>             )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=20
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/transformer_model.py b/darts/models/forecasting/transformer_model.py
index bb0a057965..79097cb90e 100644
--- a/darts/models/forecasting/transformer_model.py
+++ b/darts/models/forecasting/transformer_model.py
@@ -513,7 +513,7 @@ def __init__(
         .. [1] Ashish Vaswani, Noam Shazeer, Niki Parmar, Jakob Uszkoreit, Llion Jones, Aidan N Gomez, Lukasz Kaiser,
         and Illia Polosukhin, "Attention Is All You Need", 2017. In Advances in Neural Information Processing Systems,
         pages 6000-6010. https://arxiv.org/abs/1706.03762.
-        ..[2] Shazeer, Noam, "GLU Variants Improve Transformer", 2020. arVix https://arxiv.org/abs/2002.05202.
+        .. [2] Shazeer, Noam, "GLU Variants Improve Transformer", 2020. arVix https://arxiv.org/abs/2002.05202.
 
         Notes
         -----
@@ -533,13 +533,13 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> model = TransformerModel(
-        >>>             input_chunk_length=6,
-        >>>             output_chunk_length=6,
-        >>>             n_epochs=20
-        >>>             )
+        >>>   input_chunk_length=6,
+        >>>   output_chunk_length=6,
+        >>>   n_epochs=20
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/varima.py b/darts/models/forecasting/varima.py
index bc69045177..56d2b1a92f 100644
--- a/darts/models/forecasting/varima.py
+++ b/darts/models/forecasting/varima.py
@@ -76,20 +76,23 @@ def __init__(
         --------
         >>> from darts.datasets import ETTh2Dataset
         >>> from darts.models import VARIMA
+        >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> # forecasting the High UseFul Load ("HUFL") and Oil Temperature ("OT")
         >>> series = ETTh2Dataset().load()[:500][["HUFL", "OT"]]
+        >>> # optionally, encode the holidays as a future covariates
+        >>> future_cov = holidays_timeseries(series.time_index, "CN", add_length=6)
         >>> # no clear trend in the dataset
         >>> model = VARIMA(trend="n")
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> # the two targets are predicted together
         >>> pred.values()
-        array([[48.11908832, 47.94259927],
-               [49.85410722, 47.9768968 ],
-               [51.16256336, 47.99770988],
-               [52.14787078, 48.00830983],
-               [52.88837291, 48.01117491],
-               [53.44342041, 48.00818257]])
+        array([[48.11846185, 47.94272629],
+               [49.85314633, 47.97713346],
+               [51.16145791, 47.99804203],
+               [52.14674087, 48.00872598],
+               [52.88729152, 48.01166578],
+               [53.44242919, 48.00874069]])
         """
         super().__init__(add_encoders=add_encoders)
         self.p = p
diff --git a/darts/models/forecasting/xgboost.py b/darts/models/forecasting/xgboost.py
index f26864e98d..e7a83b8a3b 100644
--- a/darts/models/forecasting/xgboost.py
+++ b/darts/models/forecasting/xgboost.py
@@ -121,18 +121,18 @@ def __init__(
         >>> series = WeatherDataset().load()
         >>> # predicting atmospheric pressure
         >>> target = series['p (mbar)'][:100]
-        >>> # past observed rainfall (pretending to be unknown beyond index 100)
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
-        >>> # future temperatures (pretending this component is a forecast)
+        >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = XGBModel(
-        >>>             lags=12,
-        >>>             lags_past_covariates=12,
-        >>>             lags_future_covariates=[0,1,2,3,4,5],
-        >>>             output_chunk_length=6,
-        >>>             )
+        >>>   lags=12,
+        >>>   lags_past_covariates=12,
+        >>>   lags_future_covariates=[0,1,2,3,4,5],
+        >>>   output_chunk_length=6,
+        >>>   )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()

From 6f00e09908f022e756b95a3a1dbb8cf032397b1e Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Mon, 4 Sep 2023 10:55:01 +0200
Subject: [PATCH 3/8] fix: revert changes, will be included in a separate PR

---
 darts/models/forecasting/forecasting_model.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/darts/models/forecasting/forecasting_model.py b/darts/models/forecasting/forecasting_model.py
index 41c1eaf63e..452d2368cd 100644
--- a/darts/models/forecasting/forecasting_model.py
+++ b/darts/models/forecasting/forecasting_model.py
@@ -2303,7 +2303,6 @@ def fit(self, series: TimeSeries, future_covariates: Optional[TimeSeries] = None
         """
 
         if future_covariates is not None:
-            self.future_covariate_series = future_covariates
             if not series.has_same_time_as(future_covariates):
                 # fit() expects future_covariates to have same time as the target, so we intersect it here
                 future_covariates = future_covariates.slice_intersect(series)
@@ -2365,10 +2364,6 @@ def predict(
 
         super().predict(n, num_samples)
 
-        # retrieve the future covariate series saved in fit()
-        if future_covariates is None and self.future_covariate_series is not None:
-            future_covariates = self.future_covariate_series
-
         # avoid generating encodings again if subclass has already generated them
         if not self._supress_generate_predict_encoding:
             self._verify_passed_predict_covariates(future_covariates)

From 1c95b45832f502f960d2102c23f2bc359045ddc0 Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Mon, 4 Sep 2023 11:56:55 +0200
Subject: [PATCH 4/8] updated changelog

---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 843492d0b2..5553a67936 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,8 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 - `TimeSeries` with a `RangeIndex` starting in the negative start are now supported by `historical_forecasts`. [#1866](https://github.com/unit8co/darts/pull/1866) by [Antoine Madrona](https://github.com/madtoinou).
 - Added a new argument `start_format` to `historical_forecasts()`, `backtest()` and `gridsearch` that allows to use an integer `start` either as the index position or index value/label for `series` indexed with a `pd.RangeIndex`. [#1866](https://github.com/unit8co/darts/pull/1866) by [Antoine Madrona](https://github.com/madtoinou).
 - Added `RINorm` (Reversible Instance Norm) as an input normalization option for all `TorchForecastingModel` except `RNNModel`. Activate it with model creation parameter `use_reversible_instance_norm`. [#1969](https://github.com/unit8co/darts/pull/1969) by [Dennis Bader](https://github.com/dennisbader).
-- Reduced the size of the Darts docker image `unit8/darts:latest`, and included all optional models as well as dev requirements. [#1878](https://github.com/unit8co/darts/pull/1878) by [Alex Colpitts](https://github.com/alexcolpitts96). 
+- Reduced the size of the Darts docker image `unit8/darts:latest`, and included all optional models as well as dev requirements. [#1878](https://github.com/unit8co/darts/pull/1878) by [Alex Colpitts](https://github.com/alexcolpitts96).
+- Added short examples in the docstring of all the models, including covariates usage and some model-specific parameters. [#1956](https://github.com/unit8co/darts/pull/1956) by [Antoine Madrona](https://github.com/madtoinou).
 
 **Fixed**
 - Fixed a bug in `TimeSeries.from_dataframe()` when using a pandas.DataFrame with `df.columns.name != None`. [#1938](https://github.com/unit8co/darts/pull/1938) by [Antoine Madrona](https://github.com/madtoinou).

From 34f82919bb3f5f2c66c8df791222e8ddcf340480 Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Tue, 12 Sep 2023 15:33:28 +0200
Subject: [PATCH 5/8] fix: addressed review comments

---
 darts/models/forecasting/arima.py             | 18 ++++-----
 darts/models/forecasting/auto_arima.py        | 18 ++++-----
 darts/models/forecasting/block_rnn_model.py   | 40 +++++++++++--------
 darts/models/forecasting/catboost_model.py    | 10 ++---
 darts/models/forecasting/dlinear.py           | 13 ++++--
 darts/models/forecasting/fft.py               | 12 ++++--
 darts/models/forecasting/kalman_forecaster.py | 25 +++++++-----
 darts/models/forecasting/lgbm.py              | 12 +++---
 .../forecasting/linear_regression_model.py    | 10 ++---
 darts/models/forecasting/nbeats.py            | 15 ++++---
 darts/models/forecasting/nhits.py             | 10 ++---
 darts/models/forecasting/nlinear.py           |  8 ++--
 darts/models/forecasting/prophet_model.py     | 21 +++++-----
 darts/models/forecasting/random_forest.py     | 14 +++----
 .../forecasting/regression_ensemble_model.py  |  9 +++--
 darts/models/forecasting/regression_model.py  | 12 +++---
 darts/models/forecasting/rnn_model.py         | 14 ++++---
 darts/models/forecasting/tcn_model.py         | 12 ++++--
 darts/models/forecasting/tft_model.py         | 16 +++++---
 darts/models/forecasting/tide_model.py        | 12 ++++--
 darts/models/forecasting/transformer_model.py | 13 ++++--
 darts/models/forecasting/varima.py            |  6 +--
 darts/models/forecasting/xgboost.py           | 10 ++---
 23 files changed, 189 insertions(+), 141 deletions(-)

diff --git a/darts/models/forecasting/arima.py b/darts/models/forecasting/arima.py
index d856f14f7b..39a6624702 100644
--- a/darts/models/forecasting/arima.py
+++ b/darts/models/forecasting/arima.py
@@ -84,21 +84,21 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import ARIMA
-        >>> from darts.utils.timeseries_generation import holidays_timeseries
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
         >>> series = AirPassengersDataset().load()
-        >>> # optionally, encode the holidays as a future covariates
-        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
         >>> # define ARIMA parameters
         >>> model = ARIMA(p=12, d=1, q=2)
         >>> model.fit(series, future_covariates=future_cov)
         >>> pred = model.predict(6, future_covariates=future_cov)
         >>> pred.values()
-        array([[447.94644074],
-               [414.35377794],
-               [437.74584582],
-               [477.87154457],
-               [498.54135753],
-               [554.29890434]])
+        array([[451.36489334],
+               [416.88972829],
+               [443.10520391],
+               [481.07892911],
+               [502.11286509],
+               [555.50153984]])
         """
         super().__init__(add_encoders=add_encoders)
         self.order = p, d, q
diff --git a/darts/models/forecasting/auto_arima.py b/darts/models/forecasting/auto_arima.py
index e17dc22249..5ad8046fea 100644
--- a/darts/models/forecasting/auto_arima.py
+++ b/darts/models/forecasting/auto_arima.py
@@ -69,19 +69,19 @@ def __init__(
         >>> from darts.models import AutoARIMA
         >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> series = AirPassengersDataset().load()
-        >>> # optionally, encode the holidays as a future covariates
-        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
         >>> # define some boundaries for the parameters
         >>> model = AutoARIMA(start_p=8, max_p=12, start_q=1)
         >>> model.fit(series, future_covariates=future_cov)
-        >>> pred = model.predict(6)
+        >>> pred = model.predict(6, future_covariates=future_cov)
         >>> pred.values()
-        array([[447.66109213],
-               [414.24345894],
-               [440.96002246],
-               [483.5631593 ],
-               [505.61540834],
-               [562.53749429]])
+        array([[449.79716178],
+               [416.31180633],
+               [445.28005229],
+               [485.27121314],
+               [507.61787454],
+               [561.26993332]])
         """
         super().__init__(add_encoders=add_encoders)
         self.model = PmdAutoARIMA(*autoarima_args, **autoarima_kwargs)
diff --git a/darts/models/forecasting/block_rnn_model.py b/darts/models/forecasting/block_rnn_model.py
index a08bfc2579..c5eff40a83 100644
--- a/darts/models/forecasting/block_rnn_model.py
+++ b/darts/models/forecasting/block_rnn_model.py
@@ -314,27 +314,33 @@ def encode_year(idx):
 
         Examples
         --------
-        >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.datasets import WeatherDataset
         >>> from darts.models import BlockRNNModel
-        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dt_attr
-        >>> series = AirPassengersDataset().load()
-        >>> # optionnaly, one-hot encode the months as a past covariates
-        >>> past_cov = dt_attr(series, "month")
+        >>> series = WeatherDataset().load()
+        >>> # predicting atmospheric pressure
+        >>> target = series['p (mbar)'][:100]
+        >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
+        >>> past_cov = series['rain (mm)'][:100]
+        >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> model = BlockRNNModel(
-        >>>   input_chunk_length=12,
-        >>>   output_chunk_length=6,
-        >>>   n_rnn_layers=2,
-        >>>   n_epochs=50,
-        >>>   )
-        >>> model.fit(series, past_covariates=past_cov)
+        >>>     input_chunk_length=12,
+        >>>     output_chunk_length=6,
+        >>>     n_rnn_layers=2,
+        >>>     n_epochs=50,
+        >>> )
+        >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
-        array([[5.6068386 ],
-               [6.10806508],
-               [6.48818782],
-               [5.30463617],
-               [5.24570622],
-               [6.42277716]])
+        array([[4.97979827],
+               [3.9707572 ],
+               [5.27869295],
+               [5.19697244],
+               [5.28424783],
+               [5.22497681]])
+
+        .. note::
+            `RNN example notebook <https://unit8co.github.io/darts/examples/04-RNN-examples.html>`_ presents techniques
+            that can be used to improve the forecasts quality compared to this simple usage example.
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/catboost_model.py b/darts/models/forecasting/catboost_model.py
index 70b7bfcfcd..b25b983a77 100644
--- a/darts/models/forecasting/catboost_model.py
+++ b/darts/models/forecasting/catboost_model.py
@@ -112,11 +112,11 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = CatBoostModel(
-        >>>   lags=12,
-        >>>   lags_past_covariates=12,
-        >>>   lags_future_covariates=[0,1,2,3,4,5],
-        >>>   output_chunk_length=6
-        >>>   )
+        >>>     lags=12,
+        >>>     lags_past_covariates=12,
+        >>>     lags_future_covariates=[0,1,2,3,4,5],
+        >>>     output_chunk_length=6
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/dlinear.py b/darts/models/forecasting/dlinear.py
index bb869957db..7b78c1a16b 100644
--- a/darts/models/forecasting/dlinear.py
+++ b/darts/models/forecasting/dlinear.py
@@ -429,10 +429,10 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = DLinearModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=20,
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=20,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -442,6 +442,11 @@ def encode_year(idx):
                [666.06625381],
                [665.8529289 ],
                [665.75320573]])
+
+        .. note::
+            This simple usage example produces poor forecasts. In order to obtain better performance, user should
+            transform the input data, increase the number of epochs, use a validation set, optimize the hyper-
+            parameters, ...
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/fft.py b/darts/models/forecasting/fft.py
index 65cb32e0ab..a2b59d45e6 100644
--- a/darts/models/forecasting/fft.py
+++ b/darts/models/forecasting/fft.py
@@ -260,10 +260,10 @@ def __init__(
         >>> series = AirPassengersDataset().load()
         >>> # increase the number of frequency and use a polynomial trend of degree 2
         >>> model = FFT(
-        >>>   nr_freqs_to_keep=20,
-        >>>   trend= "poly",
-        >>>   trend_poly_degree=2
-        >>>   )
+        >>>     nr_freqs_to_keep=20,
+        >>>     trend= "poly",
+        >>>     trend_poly_degree=2
+        >>> )
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -273,6 +273,10 @@ def __init__(
                [515.82463265],
                [520.59404623],
                [547.26720705]])
+
+        .. note::
+            `FFT example notebook <https://unit8co.github.io/darts/examples/03-FFT-examples.html>`_ presents techniques
+            that can be used to improve the forecasts quality compared to this simple usage example.
         """
         super().__init__()
         self.nr_freqs_to_keep = nr_freqs_to_keep
diff --git a/darts/models/forecasting/kalman_forecaster.py b/darts/models/forecasting/kalman_forecaster.py
index 52f20eadb3..70735cad97 100644
--- a/darts/models/forecasting/kalman_forecaster.py
+++ b/darts/models/forecasting/kalman_forecaster.py
@@ -80,21 +80,26 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import KalmanForecaster
-        >>> from darts.utils.timeseries_generation import holidays_timeseries
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
         >>> series = AirPassengersDataset().load()
-        >>> # optionally, encode the holidays as a future covariates
-        >>> future_cov = holidays_timeseries(series.time_index, "US", add_length=6)
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
         >>> # increasing the size of the state vector
         >>> model = KalmanForecaster(dim_x=12)
         >>> model.fit(series, future_covariates=future_cov)
-        >>> pred = model.predict(6)
+        >>> pred = model.predict(6, future_covariates=future_cov)
         >>> pred.values()
-        array([[446.14067242],
-               [419.48270858],
-               [456.67694119],
-               [481.59399823],
-               [511.5273642 ],
-               [574.9500178 ]])
+        array([[474.40680728],
+               [440.51801726],
+               [461.94512461],
+               [494.42090089],
+               [528.6436328 ],
+               [590.30647185]])
+
+        .. note::
+            `Kalman example notebook <https://unit8co.github.io/darts/examples/10-Kalman-filter-examples.html>`_
+            presents techniques that can be used to improve the forecasts quality compared to this simple usage
+            example.
         """
         super().__init__(add_encoders=add_encoders)
         self.dim_x = dim_x
diff --git a/darts/models/forecasting/lgbm.py b/darts/models/forecasting/lgbm.py
index a52120bc6d..7aa2e4cd76 100644
--- a/darts/models/forecasting/lgbm.py
+++ b/darts/models/forecasting/lgbm.py
@@ -132,12 +132,12 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = LightGBMModel(
-        >>>   lags=12,
-        >>>   lags_past_covariates=12,
-        >>>   lags_future_covariates=[0,1,2,3,4,5],
-        >>>   output_chunk_length=6,
-        >>>   verbose=-1
-        >>>   )
+        >>>     lags=12,
+        >>>     lags_past_covariates=12,
+        >>>     lags_future_covariates=[0,1,2,3,4,5],
+        >>>     output_chunk_length=6,
+        >>>     verbose=-1
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/linear_regression_model.py b/darts/models/forecasting/linear_regression_model.py
index 9ec3d59b83..19fc4617b6 100644
--- a/darts/models/forecasting/linear_regression_model.py
+++ b/darts/models/forecasting/linear_regression_model.py
@@ -115,11 +115,11 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = LinearRegressionModel(
-        >>>   lags=12,
-        >>>   lags_past_covariates=12,
-        >>>   lags_future_covariates=[0,1,2,3,4,5],
-        >>>   output_chunk_length=6,
-        >>>   )
+        >>>     lags=12,
+        >>>     lags_past_covariates=12,
+        >>>     lags_future_covariates=[0,1,2,3,4,5],
+        >>>     output_chunk_length=6,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/nbeats.py b/darts/models/forecasting/nbeats.py
index 1a67d0317f..e5c06c3af7 100644
--- a/darts/models/forecasting/nbeats.py
+++ b/darts/models/forecasting/nbeats.py
@@ -746,11 +746,11 @@ def encode_year(idx):
         >>> past_cov = series['rain (mm)'][:100]
         >>> # changing the activation function of the encoder/decoder to LeakyReLU
         >>> model = NBEATSModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=5,
-        >>>   activation='LeakyReLU'
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=5,
+        >>>     activation='LeakyReLU'
+        >>> )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -760,6 +760,11 @@ def encode_year(idx):
                [ 892.66032082],
                [ 921.09781534],
                [ 950.37965429]])
+
+        .. note::
+            `NBEATS example notebook <https://unit8co.github.io/darts/examples/07-NBEATS-examples.html>`_
+            presents techniques that can be used to improve the forecasts quality compared to this simple usage
+            example.
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/nhits.py b/darts/models/forecasting/nhits.py
index c4879aebc3..7b63cd3ca6 100644
--- a/darts/models/forecasting/nhits.py
+++ b/darts/models/forecasting/nhits.py
@@ -683,11 +683,11 @@ def encode_year(idx):
         >>> past_cov = series['rain (mm)'][:100]
         >>> # increasing the number of blocks
         >>> model = NHiTSModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   num_blocks=2,
-        >>>   n_epochs=5,
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     num_blocks=2,
+        >>>     n_epochs=5,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/nlinear.py b/darts/models/forecasting/nlinear.py
index aa34ca3088..6d654b82fb 100644
--- a/darts/models/forecasting/nlinear.py
+++ b/darts/models/forecasting/nlinear.py
@@ -378,10 +378,10 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = NLinearModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=20,
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=20,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/prophet_model.py b/darts/models/forecasting/prophet_model.py
index 4c5dd26f51..5c9073dd10 100644
--- a/darts/models/forecasting/prophet_model.py
+++ b/darts/models/forecasting/prophet_model.py
@@ -135,19 +135,18 @@ def __init__(
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import Prophet
-        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries as dt_attr
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
         >>> series = AirPassengersDataset().load()
-        >>> # optionally, one-hot encode the months as a future covariates
-        >>> future_cov = dt_attr(series, "month", one_hot=True, add_length=6)
-        >>> # adding a seasonality (yearly and weekly are included by default) and holidays
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
+        >>> # adding a seasonality (daily, weekly and yearly are included by default) and holidays
         >>> model = Prophet(
-        >>>   add_seasonalities={
-        >>>       'name':"quarterly_seasonality",
-        >>>       'seasonal_periods':4,
-        >>>       'fourier_order':5
-        >>>       },
-        >>>   country_holidays="US"
-        >>>   )
+        >>>     add_seasonalities={
+        >>>         'name':"quarterly_seasonality",
+        >>>         'seasonal_periods':4,
+        >>>         'fourier_order':5
+        >>>         },
+        >>> )
         >>> model.fit(series, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/random_forest.py b/darts/models/forecasting/random_forest.py
index c675865be1..d4e0b4e58e 100644
--- a/darts/models/forecasting/random_forest.py
+++ b/darts/models/forecasting/random_forest.py
@@ -109,13 +109,13 @@ def encode_year(idx):
         >>> future_cov = series['T (degC)'][:106]
         >>> # random forest with 200 trees trained with MAE
         >>> model = RandomForest(
-        >>>   lags=12,
-        >>>   lags_past_covariates=12,
-        >>>   lags_future_covariates=[0,1,2,3,4,5],
-        >>>   output_chunk_length=6,
-        >>>   n_estimators=200,
-        >>>   criterion="absolute_error",
-        >>>   )
+        >>>     lags=12,
+        >>>     lags_past_covariates=12,
+        >>>     lags_future_covariates=[0,1,2,3,4,5],
+        >>>     output_chunk_length=6,
+        >>>     n_estimators=200,
+        >>>     criterion="absolute_error",
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/regression_ensemble_model.py b/darts/models/forecasting/regression_ensemble_model.py
index 07065fbed2..ae749015e8 100644
--- a/darts/models/forecasting/regression_ensemble_model.py
+++ b/darts/models/forecasting/regression_ensemble_model.py
@@ -78,9 +78,12 @@ def __init__(
         >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, LinearRegressionModel
         >>> series = AirPassengersDataset().load()
         >>> model = RegressionEnsembleModel(
-              forecasting_models = [NaiveSeasonal(K=12), LinearRegressionModel(lags=4)],
-              regression_train_n_points=20
-              )
+        >>>     forecasting_models = [
+        >>>         NaiveSeasonal(K=12),
+        >>>         LinearRegressionModel(lags=4)
+        >>>     ],
+        >>>     regression_train_n_points=20
+        >>> )
         >>> model.fit(series)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/regression_model.py b/darts/models/forecasting/regression_model.py
index e164d27493..940ec4c2bc 100644
--- a/darts/models/forecasting/regression_model.py
+++ b/darts/models/forecasting/regression_model.py
@@ -144,12 +144,12 @@ def encode_year(idx):
         >>> future_cov = series['T (degC)'][:106]
         >>> # wrap around the sklearn Ridge model
         >>> model = RegressionModel(
-        >>>   model=Ridge(),
-        >>>   lags=12,
-        >>>   lags_past_covariates=4,
-        >>>   lags_future_covariates=(0,6),
-        >>>   output_chunk_length=6
-        >>>   )
+        >>>     model=Ridge(),
+        >>>     lags=12,
+        >>>     lags_past_covariates=4,
+        >>>     lags_future_covariates=(0,6),
+        >>>     output_chunk_length=6
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
diff --git a/darts/models/forecasting/rnn_model.py b/darts/models/forecasting/rnn_model.py
index 7b4ef68c9a..f26cd4a90b 100644
--- a/darts/models/forecasting/rnn_model.py
+++ b/darts/models/forecasting/rnn_model.py
@@ -402,11 +402,11 @@ def encode_year(idx):
         >>> future_cov = series['T (degC)'][:106]
         >>> # `training_length` > `input_chunk_length` to mimic inference constraints
         >>> model = RNNModel(
-        >>>   model="RNN",
-        >>>   input_chunk_length=6,
-        >>>   training_length=18,
-        >>>   n_epochs=20,
-        >>>   )
+        >>>     model="RNN",
+        >>>     input_chunk_length=6,
+        >>>     training_length=18,
+        >>>     n_epochs=20,
+        >>> )
         >>> model.fit(target, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -416,6 +416,10 @@ def encode_year(idx):
                [ 0.13277921],
                [ 0.02523252],
                [-0.01829086]])
+
+        .. note::
+            `RNN example notebook <https://unit8co.github.io/darts/examples/04-RNN-examples.html>`_ presents techniques
+            that can be used to improve the forecasts quality compared to this simple usage example.
         """
         # create copy of model parameters
         model_kwargs = {key: val for key, val in self.model_params.items()}
diff --git a/darts/models/forecasting/tcn_model.py b/darts/models/forecasting/tcn_model.py
index b3dda86453..3b9795b033 100644
--- a/darts/models/forecasting/tcn_model.py
+++ b/darts/models/forecasting/tcn_model.py
@@ -448,10 +448,10 @@ def encode_year(idx):
         >>> past_cov = series['rain (mm)'][:100]
         >>> # `output_chunk_length` must be strictly smaller than `input_chunk_length`
         >>> model = TCNModel(
-        >>>   input_chunk_length=12,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=20,
-        >>>   )
+        >>>     input_chunk_length=12,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=20,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -461,6 +461,10 @@ def encode_year(idx):
                [-41.76158729],
                [-41.76854107],
                [-41.78166819]])
+
+        .. note::
+            `DeepTCN example notebook <https://unit8co.github.io/darts/examples/09-DeepTCN-examples.html>`_ presents
+            techniques that can be used to improve the forecasts quality compared to this simple usage example.
         """
 
         raise_if_not(
diff --git a/darts/models/forecasting/tft_model.py b/darts/models/forecasting/tft_model.py
index 991708625d..af89d05e8f 100644
--- a/darts/models/forecasting/tft_model.py
+++ b/darts/models/forecasting/tft_model.py
@@ -895,15 +895,15 @@ def encode_year(idx):
         >>> past_cov = series['rain (mm)'][:100]
         >>> # future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
-        >>> # by default, TFTModel is trained using a `QuantileRegression`
+        >>> # by default, TFTModel is trained using a `QuantileRegression` making it a probabilistic forecasting model
         >>> model = TFTModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=5,
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=5,
+        >>> )
         >>> # future_covariates are mandatory for `TFTModel`
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
-        >>> # using `num_samples > 1`, the model generates a probabilistic forecast
+        >>> # TFTModel is probabilistic by definition; using `num_samples >> 1` to generate probabilistic forecasts
         >>> pred = model.predict(6, num_samples=100)
         >>> # shape : (forecast horizon, components, num_samples)
         >>> pred.all_values().shape
@@ -916,6 +916,10 @@ def encode_year(idx):
                [[ 0.9586113 ,  1.24147138, -0.01625545]],
                [[ 1.06863863,  0.2987822 , -0.69213369]],
                [[-0.83076568, -0.25780816, -0.28318784]]])
+
+        .. note::
+            `TFT example notebook <https://unit8co.github.io/darts/examples/13-TFT-examples.html>`_ presents
+            techniques that can be used to improve the forecasts quality compared to this simple usage example.
         """
         model_kwargs = {key: val for key, val in self.model_params.items()}
         if likelihood is None and loss_fn is None:
diff --git a/darts/models/forecasting/tide_model.py b/darts/models/forecasting/tide_model.py
index ef5a8698a9..0d0d478f07 100644
--- a/darts/models/forecasting/tide_model.py
+++ b/darts/models/forecasting/tide_model.py
@@ -532,10 +532,10 @@ def encode_year(idx):
         >>> # optionally, use future temperatures (pretending this component is a forecast)
         >>> future_cov = series['T (degC)'][:106]
         >>> model = TiDEModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=20
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=20
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -545,6 +545,10 @@ def encode_year(idx):
                [1005.10790392],
                [ 998.90537286],
                [1005.91534452]])
+
+        .. note::
+            `TiDE example notebook <https://unit8co.github.io/darts/examples/18-TiDE-examples.html>`_ presents
+            techniques that can be used to improve the forecasts quality compared to this simple usage example.
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/transformer_model.py b/darts/models/forecasting/transformer_model.py
index ed9ba38490..5287bcfc71 100644
--- a/darts/models/forecasting/transformer_model.py
+++ b/darts/models/forecasting/transformer_model.py
@@ -548,10 +548,10 @@ def encode_year(idx):
         >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
         >>> past_cov = series['rain (mm)'][:100]
         >>> model = TransformerModel(
-        >>>   input_chunk_length=6,
-        >>>   output_chunk_length=6,
-        >>>   n_epochs=20
-        >>>   )
+        >>>     input_chunk_length=6,
+        >>>     output_chunk_length=6,
+        >>>     n_epochs=20
+        >>> )
         >>> model.fit(target, past_covariates=past_cov)
         >>> pred = model.predict(6)
         >>> pred.values()
@@ -561,6 +561,11 @@ def encode_year(idx):
                [6.48695488],
                [7.63158655],
                [5.65417736]])
+
+        .. note::
+            `Transformer example notebook <https://unit8co.github.io/darts/examples/06-Transformer-examples.html>`_
+            presents techniques that can be used to improve the forecasts quality compared to this simple usage
+            example.
         """
         super().__init__(**self._extract_torch_model_params(**self.model_params))
 
diff --git a/darts/models/forecasting/varima.py b/darts/models/forecasting/varima.py
index 56d2b1a92f..1900cd317d 100644
--- a/darts/models/forecasting/varima.py
+++ b/darts/models/forecasting/varima.py
@@ -79,12 +79,12 @@ def __init__(
         >>> from darts.utils.timeseries_generation import holidays_timeseries
         >>> # forecasting the High UseFul Load ("HUFL") and Oil Temperature ("OT")
         >>> series = ETTh2Dataset().load()[:500][["HUFL", "OT"]]
-        >>> # optionally, encode the holidays as a future covariates
+        >>> # optionally, use some future covariates; e.g. encode each timestep whether it is on a holiday
         >>> future_cov = holidays_timeseries(series.time_index, "CN", add_length=6)
         >>> # no clear trend in the dataset
         >>> model = VARIMA(trend="n")
-        >>> model.fit(series)
-        >>> pred = model.predict(6)
+        >>> model.fit(series, future_covariates=future_cov)
+        >>> pred = model.predict(6, future_covariates=future_cov)
         >>> # the two targets are predicted together
         >>> pred.values()
         array([[48.11846185, 47.94272629],
diff --git a/darts/models/forecasting/xgboost.py b/darts/models/forecasting/xgboost.py
index 46b73c01d4..962eddbeba 100644
--- a/darts/models/forecasting/xgboost.py
+++ b/darts/models/forecasting/xgboost.py
@@ -131,11 +131,11 @@ def encode_year(idx):
         >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
         >>> # values corresponding to the forecasted period
         >>> model = XGBModel(
-        >>>   lags=12,
-        >>>   lags_past_covariates=12,
-        >>>   lags_future_covariates=[0,1,2,3,4,5],
-        >>>   output_chunk_length=6,
-        >>>   )
+        >>>     lags=12,
+        >>>     lags_past_covariates=12,
+        >>>     lags_future_covariates=[0,1,2,3,4,5],
+        >>>     output_chunk_length=6,
+        >>> )
         >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
         >>> pred = model.predict(6)
         >>> pred.values()

From 63c5078eac5e694e942b6ad258f71c4d0f06e98f Mon Sep 17 00:00:00 2001
From: madtoinou <antoine.madrona@unit8.co>
Date: Tue, 12 Sep 2023 15:35:28 +0200
Subject: [PATCH 6/8] added review suggestion

---
 darts/models/forecasting/tbats_model.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/darts/models/forecasting/tbats_model.py b/darts/models/forecasting/tbats_model.py
index 5ac43e2640..4dabf1fa05 100644
--- a/darts/models/forecasting/tbats_model.py
+++ b/darts/models/forecasting/tbats_model.py
@@ -177,7 +177,7 @@ def __init__(
         Examples
         --------
         >>> from darts.datasets import AirPassengersDataset
-        >>> from darts.models import TBATS
+        >>> from darts.models import TBATS # or BATS
         >>> series = AirPassengersDataset().load()
         >>> # based on preliminary analysis, the series contains a trend
         >>> model = TBATS(use_trend=True)

From cca58fddddafcc5536478b4278b674e1dd8051b6 Mon Sep 17 00:00:00 2001
From: dennisbader <dennis.bader@gmx.ch>
Date: Thu, 14 Sep 2023 10:24:55 +0200
Subject: [PATCH 7/8] update leftover lambda mentions in model docs

---
 darts/models/forecasting/arima.py             | 5 ++++-
 darts/models/forecasting/auto_arima.py        | 5 ++++-
 darts/models/forecasting/croston.py           | 5 ++++-
 darts/models/forecasting/kalman_forecaster.py | 5 ++++-
 darts/models/forecasting/prophet_model.py     | 5 ++++-
 darts/models/forecasting/sf_auto_arima.py     | 5 ++++-
 darts/models/forecasting/sf_auto_ets.py       | 5 ++++-
 darts/models/forecasting/varima.py            | 5 ++++-
 8 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/darts/models/forecasting/arima.py b/darts/models/forecasting/arima.py
index 39a6624702..dbca628ca3 100644
--- a/darts/models/forecasting/arima.py
+++ b/darts/models/forecasting/arima.py
@@ -71,11 +71,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/auto_arima.py b/darts/models/forecasting/auto_arima.py
index 5ad8046fea..4a9e7b6db2 100644
--- a/darts/models/forecasting/auto_arima.py
+++ b/darts/models/forecasting/auto_arima.py
@@ -54,11 +54,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/croston.py b/darts/models/forecasting/croston.py
index 1ce390f0ee..c5b6482f62 100644
--- a/darts/models/forecasting/croston.py
+++ b/darts/models/forecasting/croston.py
@@ -58,11 +58,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/kalman_forecaster.py b/darts/models/forecasting/kalman_forecaster.py
index 70735cad97..7d1cc7ef93 100644
--- a/darts/models/forecasting/kalman_forecaster.py
+++ b/darts/models/forecasting/kalman_forecaster.py
@@ -67,11 +67,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/prophet_model.py b/darts/models/forecasting/prophet_model.py
index 5c9073dd10..295e8286d3 100644
--- a/darts/models/forecasting/prophet_model.py
+++ b/darts/models/forecasting/prophet_model.py
@@ -98,11 +98,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/sf_auto_arima.py b/darts/models/forecasting/sf_auto_arima.py
index 4cf674a453..213c343597 100644
--- a/darts/models/forecasting/sf_auto_arima.py
+++ b/darts/models/forecasting/sf_auto_arima.py
@@ -51,11 +51,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/sf_auto_ets.py b/darts/models/forecasting/sf_auto_ets.py
index 9876234d23..73fbaa780b 100644
--- a/darts/models/forecasting/sf_auto_ets.py
+++ b/darts/models/forecasting/sf_auto_ets.py
@@ -56,11 +56,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..
diff --git a/darts/models/forecasting/varima.py b/darts/models/forecasting/varima.py
index 1900cd317d..ece88dba80 100644
--- a/darts/models/forecasting/varima.py
+++ b/darts/models/forecasting/varima.py
@@ -63,11 +63,14 @@ def __init__(
             .. highlight:: python
             .. code-block:: python
 
+                def encode_year(idx):
+                    return (idx.year - 1950) / 50
+
                 add_encoders={
                     'cyclic': {'future': ['month']},
                     'datetime_attribute': {'future': ['hour', 'dayofweek']},
                     'position': {'future': ['relative']},
-                    'custom': {'future': [lambda idx: (idx.year - 1950) / 50]},
+                    'custom': {'future': [encode_year]},
                     'transformer': Scaler()
                 }
             ..

From 25e7977069040937ee4f8e5ef2c319171ac173ec Mon Sep 17 00:00:00 2001
From: dennisbader <dennis.bader@gmx.ch>
Date: Thu, 14 Sep 2023 10:40:35 +0200
Subject: [PATCH 8/8] update statsforecast model examples

---
 darts/models/forecasting/sf_auto_arima.py | 17 ++++++++++++++---
 darts/models/forecasting/sf_auto_ces.py   | 14 +++++++++++---
 darts/models/forecasting/sf_auto_ets.py   | 15 +++++++++++++--
 darts/models/forecasting/sf_auto_theta.py | 14 +++++++++++---
 4 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/darts/models/forecasting/sf_auto_arima.py b/darts/models/forecasting/sf_auto_arima.py
index 213c343597..91cc12c0c0 100644
--- a/darts/models/forecasting/sf_auto_arima.py
+++ b/darts/models/forecasting/sf_auto_arima.py
@@ -67,12 +67,23 @@ def encode_year(idx):
 
         Examples
         --------
-        >>> from darts.models import StatsForecastAutoARIMA
         >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import StatsForecastAutoARIMA
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
         >>> series = AirPassengersDataset().load()
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
+        >>> # define StatsForecastAutoARIMA parameters
         >>> model = StatsForecastAutoARIMA(season_length=12)
-        >>> model.fit(series[:-36])
-        >>> pred = model.predict(36, num_samples=100)
+        >>> model.fit(series, future_covariates=future_cov)
+        >>> pred = model.predict(6, future_covariates=future_cov)
+        >>> pred.values()
+        array([[450.55179949],
+               [415.00597806],
+               [454.61353249],
+               [486.51218795],
+               [504.09229632],
+               [555.06463942]])
         """
         super().__init__(add_encoders=add_encoders)
         self.model = SFAutoARIMA(*autoarima_args, **autoarima_kwargs)
diff --git a/darts/models/forecasting/sf_auto_ces.py b/darts/models/forecasting/sf_auto_ces.py
index 53e0205eec..d12db5d5a5 100644
--- a/darts/models/forecasting/sf_auto_ces.py
+++ b/darts/models/forecasting/sf_auto_ces.py
@@ -30,12 +30,20 @@ def __init__(self, *autoces_args, **autoces_kwargs):
 
         Examples
         --------
-        >>> from darts.models import StatsForecastAutoCES
         >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import StatsForecastAutoCES
         >>> series = AirPassengersDataset().load()
+        >>> # define StatsForecastAutoCES parameters
         >>> model = StatsForecastAutoCES(season_length=12, model="Z")
-        >>> model.fit(series[:-36])
-        >>> pred = model.predict(36, num_samples=100)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[453.03417969],
+               [429.34039307],
+               [488.64471436],
+               [500.28955078],
+               [519.79962158],
+               [586.47503662]])
         """
         super().__init__()
         self.model = SFAutoCES(*autoces_args, **autoces_kwargs)
diff --git a/darts/models/forecasting/sf_auto_ets.py b/darts/models/forecasting/sf_auto_ets.py
index 73fbaa780b..d5971fa813 100644
--- a/darts/models/forecasting/sf_auto_ets.py
+++ b/darts/models/forecasting/sf_auto_ets.py
@@ -74,10 +74,21 @@ def encode_year(idx):
         --------
         >>> from darts.datasets import AirPassengersDataset
         >>> from darts.models import StatsForecastAutoETS
+        >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
         >>> series = AirPassengersDataset().load()
+        >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
+        >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
+        >>> # define StatsForecastAutoETS parameters
         >>> model = StatsForecastAutoETS(season_length=12, model="AZZ")
-        >>> model.fit(series[:-36])
-        >>> pred = model.predict(36)
+        >>> model.fit(series, future_covariates=future_cov)
+        >>> pred = model.predict(6, future_covariates=future_cov)
+        >>> pred.values()
+        array([[441.40323676],
+               [415.09871431],
+               [448.90785391],
+               [491.38584654],
+               [493.11817462],
+               [549.88974472]])
         """
         super().__init__(add_encoders=add_encoders)
         self.model = SFAutoETS(*autoets_args, **autoets_kwargs)
diff --git a/darts/models/forecasting/sf_auto_theta.py b/darts/models/forecasting/sf_auto_theta.py
index 3882d49470..559517b362 100644
--- a/darts/models/forecasting/sf_auto_theta.py
+++ b/darts/models/forecasting/sf_auto_theta.py
@@ -38,12 +38,20 @@ def __init__(self, *autotheta_args, **autotheta_kwargs):
 
         Examples
         --------
-        >>> from darts.models import StatsForecastAutoTheta
         >>> from darts.datasets import AirPassengersDataset
+        >>> from darts.models import StatsForecastAutoTheta
         >>> series = AirPassengersDataset().load()
+        >>> # define StatsForecastAutoTheta parameters
         >>> model = StatsForecastAutoTheta(season_length=12)
-        >>> model.fit(series[:-36])
-        >>> pred = model.predict(36, num_samples=100)
+        >>> model.fit(series)
+        >>> pred = model.predict(6)
+        >>> pred.values()
+        array([[442.94078295],
+               [432.22936898],
+               [495.30609727],
+               [482.30625563],
+               [487.49312172],
+               [555.57902659]])
         """
         super().__init__()
         self.model = SFAutoTheta(*autotheta_args, **autotheta_kwargs)