Doc/Adding basic usage example in each model docstring

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

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)

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,

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)

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

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(

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))
 

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

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

darts/models/forecasting/forecasting_model.py

@@ -2303,6 +2303,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)
@@ -2364,6 +2365,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)

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