Theta Method¶
- class darts.models.forecasting.theta.FourTheta(theta=2, seasonality_period=None, season_mode=SeasonalityMode.MULTIPLICATIVE, model_mode=ModelMode.ADDITIVE, trend_mode=TrendMode.LINEAR, normalization=True)[source]¶
Bases:
darts.models.forecasting.forecasting_model.LocalForecastingModel
An implementation of the 4Theta method with configurable theta parameter.
See M4 competition solution.
The training time series is de-seasonalized according to seasonality_period, or an inferred seasonality period.
season_mode must be a
SeasonalityMode
Enum member. model_mode must be aModelMode
Enum member. trend_mode must be aTrendMode
Enum member.You can access the different Enums with
from darts import SeasonalityMode, TrendMode, ModelMode
.When called with theta = X, model_mode = Model.ADDITIVE and trend_mode = Trend.LINEAR, this model is equivalent to calling Theta(theta=X).
- Parameters
theta (
int
) – Value of the theta parameter. Defaults to 2. If theta = 1, then the fourtheta method restricts to a simple exponential smoothing (SES). If theta = 0, then the fourtheta method restricts to a simple trend_mode regression.seasonality_period (
Optional
[int
]) – User-defined seasonality period. If not set, will be tentatively inferred from the training series upon calling fit().model_mode (
ModelMode
) – Type of model combining the Theta lines. Either ModelMode.ADDITIVE or ModelMode.MULTIPLICATIVE. Defaults to ModelMode.ADDITIVE.season_mode (
SeasonalityMode
) – Type of seasonality. Either SeasonalityMode.MULTIPLICATIVE, SeasonalityMode.ADDITIVE or SeasonalityMode.NONE. Defaults to SeasonalityMode.MULTIPLICATIVE.trend_mode (
TrendMode
) – Type of trend to fit. Either TrendMode.LINEAR or TrendMode.EXPONENTIAL. Defaults to TrendMode.LINEAR.normalization (
bool
) – If True, the data is normalized so that the mean is 1. Defaults to True.
Notes
Even though this model is an improvement of
Theta
, it is a naive implementation of the algorithm, which can potentially be slower.Attributes
Whether the model considers static covariates, if there are any.
A 6-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag).
The minimum number of samples for training the model.
Whether model supports future covariates
Whether model supports past covariates
Whether model supports static covariates
Whether the model uses future covariates, once fitted.
Whether the model uses past covariates, once fitted.
Whether the model uses static covariates, once fitted.
model_params
Methods
backtest
(series[, past_covariates, ...])Compute error values that the model would have produced when used on (potentially multiple) series.
fit
(series)Fit/train the model on the provided series.
generate_fit_encodings
(series[, ...])Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
generate_predict_encodings
(n, series[, ...])Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
gridsearch
(parameters, series[, ...])Find the best hyper-parameters among a given set using a grid search.
historical_forecasts
(series[, ...])Compute the historical forecasts that would have been obtained by this model on (potentially multiple) series.
load
(path)Loads the model from a given path or file handle.
predict
(n[, num_samples, verbose])Forecasts values for n time steps after the end of the training series.
residuals
(series[, past_covariates, ...])Compute the residuals produced by this model on a (or sequence of) univariate time series.
save
([path])Saves the model under a given path or file handle.
select_best_model
(ts[, thetas, m, ...])Performs a grid search over all hyper parameters to select the best model, using the fitted values on the training series ts.
- backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, num_samples=1, train_length=None, start=None, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True)¶
Compute error values that the model would have produced when used on (potentially multiple) series.
If historical_forecasts are provided, the metric (given by the metric function) is evaluated directly on the forecast and the actual values. Otherwise, it repeatedly builds a training set: either expanding from the beginning of series or moving with a fixed length train_length. It trains the current model on the training set, emits a forecast of length equal to forecast_horizon, and then moves the end of the training set forward by stride time steps. The metric is then evaluated on the forecast and the actual values. Finally, the method returns a reduction (the mean by default) of all these metric scores.
By default, this method uses each historical forecast (whole) to compute error scores. If last_points_only is set to True, it will use only the last point of each historical forecast. In this case, no reduction is used.
By default, this method always re-trains the models on the entire available history, corresponding to an expanding window strategy. If retrain is set to False (useful for models for which training might be time-consuming, such as deep learning models), the trained model will be used directly to emit the forecasts.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The (or a sequence of) target time series used to successively train and evaluate the historical forecasts.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) future-known covariate series. This applies only if the model supports future covariates.historical_forecasts (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the (or a sequence of) historical forecasts time series to be evaluated. Corresponds to the output ofhistorical_forecasts()
. If provided, will skip historical forecasting and ignore all parameters except series, metric, and reduction.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Use values >1 only for probabilistic models.train_length (
Optional
[int
]) – Number of time steps in our training set (size of backtesting window to train on). Only effective when retrain is notFalse
. Default is set to train_length=None where it takes all available time steps up until prediction time, otherwise the moving window strategy is used. If larger than the number of time steps available, all steps up until prediction time are used, as in default case. Needs to be at least min_train_series_length.start (
Union
[Timestamp
,float
,int
,None
]) –Optionally, the first point in time at which a prediction is computed for a future time. This parameter supports:
float
,int
andpandas.Timestamp
, andNone
. If afloat
, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. If anint
, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. If apandas.Timestamp
, the time stamp will be used to determine the first prediction time directly. IfNone
, the first prediction time will automatically be set to:the first predictable point if retrain is
False
, or retrain is a Callable and the first
predictable point is earlier than the first trainable point.
the first trainable point if retrain is
True
orint
(given train_length),
or retrain is a Callable and the first trainable point is earlier than the first predictable point.
the first trainable point (given train_length) otherwise
Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with
None
) and start at the first trainable/predictable point.forecast_horizon (
int
) – The forecast horizon for the point predictions.stride (
int
) – The number of time steps between two consecutive predictions.retrain (
Union
[bool
,int
,Callable
[…,bool
]]) –Whether and/or on which condition to retrain the model before predicting. This parameter supports 3 different datatypes:
bool
, (positive)int
, andCallable
(returning abool
). In the case ofbool
: retrain the model at each step (True), or never retrains the model (False). In the case ofint
: the model is retrained every retrain iterations. In the case ofCallable
: the model is retrained whenever callable returns True. The callable must have the following positional arguments:counter (int): current retrain iteration
pred_time (pd.Timestamp or int): timestamp of forecast time (end of the training series)
train_series (TimeSeries): train series up to pred_time
past_covariates (TimeSeries): past_covariates series up to pred_time
future_covariates (TimeSeries): future_covariates series up to min(pred_time + series.freq * forecast_horizon, series.end_time())
Note: if any optional *_covariates are not passed to historical_forecast,
None
will be passed to the corresponding retrain function argument. Note: some models do require being retrained every time and do not support anything other than retrain=True.overlap_end (
bool
) – Whether the returned forecasts can go beyond the series’ end or not.last_points_only (
bool
) – Whether to use the whole historical forecasts or only the last point of each forecast to compute the error.metric (
Union
[Callable
[[TimeSeries
,TimeSeries
],float
],List
[Callable
[[TimeSeries
,TimeSeries
],float
]]]) – A function or a list of function that takes twoTimeSeries
instances as inputs and returns an error value.reduction (
Optional
[Callable
[[ndarray
],float
]]) – A function used to combine the individual error scores obtained when last_points_only is set to False. When providing several metric functions, the function will receive the argument axis = 0 to obtain single value for each metric function. If explicitly set to None, the method will return a list of the individual error scores instead. Set tonp.mean
by default.verbose (
bool
) – Whether to print progress.show_warnings (
bool
) – Whether to show warnings related to parameters start, and train_length.
- Returns
The (sequence of) error score on a series, or list of list containing error scores for each provided series and each sample.
- Return type
float or List[float] or List[List[float]]
- property considers_static_covariates¶
Whether the model considers static covariates, if there are any.
- property extreme_lags: Tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int]]¶
A 6-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag). If 0 is the index of the first prediction, then all lags are relative to this index.
See examples below.
- If the model wasn’t fitted with:
target (concerning RegressionModels only): then the first element should be None.
past covariates: then the third and fourth elements should be None.
future covariates: then the fifth and sixth elements should be None.
Should be overridden by models that use past or future covariates, and/or for model that have minimum target lag and maximum target lags potentially different from -1 and 0.
Notes
maximum target lag (second value) cannot be None and is always larger than or equal to 0.
Examples
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2) >>> model.fit(train_series) >>> model.extreme_lags (-3, 1, None, None, None, None) >>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7) >>> model.fit(train_series, past_covariates=past_covariates) >>> model.extreme_lags (-5, 6, -4, -1, None, None) >>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7) >>> model.fit(train_series, future_covariates=future_covariates) >>> model.extreme_lags (-5, 6, None, None, 4, 6) >>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7) >>> model.fit(train_series) >>> model.extreme_lags (-10, 6, None, None, None, None) >>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6]) >>> model.fit(train_series, future_covariates) >>> model.extreme_lags (-10, 6, None, None, 4, 6)
- Return type
Tuple
[Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
]]
- fit(series)[source]¶
Fit/train the model on the provided series.
- Parameters
series – A target time series. The model will be trained to forecast this time series.
- Returns
Fitted model.
- Return type
self
- generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶
Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you used to train/fit the model.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The series or sequence of series with the target values used when fitting the model.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the series or sequence of series with the past-observed covariates used when fitting the model.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the series or sequence of series with the future-known covariates used when fitting the model.
- Returns
A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.
- Return type
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]
- generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you intend to use for prediction.
- Parameters
n (
int
) – The number of prediction time steps after the end of series intended to be used for prediction.series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The series or sequence of series with target values intended to be used for prediction.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the past-observed covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.
- Returns
A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.
- Return type
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]
- classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=0.5, last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None)¶
Find the best hyper-parameters among a given set using a grid search.
This function has 3 modes of operation: Expanding window mode, split mode and fitted value mode. The three modes of operation evaluate every possible combination of hyper-parameter values provided in the parameters dictionary by instantiating the model_class subclass of ForecastingModel with each combination, and returning the best-performing model with regard to the metric function. The metric function is expected to return an error value, thus the model resulting in the smallest metric output will be chosen.
The relationship of the training data and test data depends on the mode of operation.
Expanding window mode (activated when forecast_horizon is passed): For every hyperparameter combination, the model is repeatedly trained and evaluated on different splits of series. This process is accomplished by using the
backtest()
function as a subroutine to produce historic forecasts starting from start that are compared against the ground truth values of series. Note that the model is retrained for every single prediction, thus this mode is slower.Split window mode (activated when val_series is passed): This mode will be used when the val_series argument is passed. For every hyper-parameter combination, the model is trained on series and evaluated on val_series.
Fitted value mode (activated when use_fitted_values is set to True): For every hyper-parameter combination, the model is trained on series and evaluated on the resulting fitted values. Not all models have fitted values, and this method raises an error if the model doesn’t have a fitted_values member. The fitted values are the result of the fit of the model on series. Comparing with the fitted values can be a quick way to assess the model, but one cannot see if the model is overfitting the series.
Derived classes must ensure that a single instance of a model will not share parameters with the other instances, e.g., saving models in the same path. Otherwise, an unexpected behavior can arise while running several models in parallel (when
n_jobs != 1
). If this cannot be avoided, then gridsearch should be redefined, forcingn_jobs = 1
.Currently this method only supports deterministic predictions (i.e. when models’ predictions have only 1 sample).
- Parameters
model_class – The ForecastingModel subclass to be tuned for ‘series’.
parameters (
dict
) – A dictionary containing as keys hyperparameter names, and as values lists of values for the respective hyperparameter.series (
TimeSeries
) – The target series used as input and target for training.past_covariates (
Optional
[TimeSeries
]) – Optionally, a past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Optional
[TimeSeries
]) – Optionally, a future-known covariate series. This applies only if the model supports future covariates.forecast_horizon (
Optional
[int
]) – The integer value of the forecasting horizon. Activates expanding window mode.stride (
int
) – The number of time steps between two consecutive predictions. Only used in expanding window mode.start (
Union
[Timestamp
,float
,int
]) – Theint
,float
orpandas.Timestamp
that represents the starting point in the time index of series from which predictions will be made to evaluate the model. For a detailed description of how the different data types are interpreted, please see the documentation for ForecastingModel.backtest. Only used in expanding window mode.last_points_only (
bool
) – Whether to use the whole forecasts or only the last point of each forecast to compute the error. Only used in expanding window mode.show_warnings (
bool
) – Whether to show warnings related to the start parameter. Only used in expanding window mode.val_series (
Optional
[TimeSeries
]) – The TimeSeries instance used for validation in split mode. If provided, this series must start right after the end of series; so that a proper comparison of the forecast can be made.use_fitted_values (
bool
) – If True, uses the comparison with the fitted values. Raises an error iffitted_values
is not an attribute of model_class.metric (
Callable
[[TimeSeries
,TimeSeries
],float
]) – A function that takes two TimeSeries instances as inputs (actual and prediction, in this order), and returns a float error value.reduction (
Callable
[[ndarray
],float
]) – A reduction function (mapping array to float) describing how to aggregate the errors obtained on the different validation series when backtesting. By default it’ll compute the mean of errors.verbose – Whether to print progress.
n_jobs (
int
) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more parameters combinations to evaluate. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.n_random_samples (
Union
[int
,float
,None
]) – The number/ratio of hyperparameter combinations to select from the full parameter grid. This will perform a random search instead of using the full grid. If an integer, n_random_samples is the number of parameter combinations selected from the full grid and must be between 0 and the total number of parameter combinations. If a float, n_random_samples is the ratio of parameter combinations selected from the full grid and must be between 0 and 1. Defaults to None, for which random selection will be ignored.
- Returns
A tuple containing an untrained model_class instance created from the best-performing hyper-parameters, along with a dictionary containing these best hyper-parameters, and metric score for the best hyper-parameters.
- Return type
ForecastingModel, Dict, float
- historical_forecasts(series, past_covariates=None, future_covariates=None, num_samples=1, train_length=None, start=None, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True)¶
Compute the historical forecasts that would have been obtained by this model on (potentially multiple) series.
This method repeatedly builds a training set: either expanding from the beginning of series or moving with a fixed length train_length. It trains the model on the training set, emits a forecast of length equal to forecast_horizon, and then moves the end of the training set forward by stride time steps.
By default, this method will return one (or a sequence of) single time series made up of the last point of each historical forecast. This time series will thus have a frequency of
series.freq * stride
. If last_points_only is set to False, it will instead return one (or a sequence of) list of the historical forecasts series.By default, this method always re-trains the models on the entire available history, corresponding to an expanding window strategy. If retrain is set to False, the model must have been fit before. This is not supported by all models.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The (or a sequence of) target time series used to successively train and compute the historical forecasts.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) of future-known covariate series. This applies only if the model supports future covariates.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Use values >1 only for probabilistic models.train_length (
Optional
[int
]) – Number of time steps in our training set (size of backtesting window to train on). Only effective when retrain is notFalse
. Default is set to train_length=None where it takes all available time steps up until prediction time, otherwise the moving window strategy is used. If larger than the number of time steps available, all steps up until prediction time are used, as in default case. Needs to be at least min_train_series_length.start (
Union
[Timestamp
,float
,int
,None
]) –Optionally, the first point in time at which a prediction is computed for a future time. This parameter supports:
float
,int
andpandas.Timestamp
, andNone
. If afloat
, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. If anint
, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. If apandas.Timestamp
, the time stamp will be used to determine the first prediction time directly. IfNone
, the first prediction time will automatically be set to:the first predictable point if retrain is
False
, or retrain is a Callable and the first
predictable point is earlier than the first trainable point.
the first trainable point if retrain is
True
orint
(given train_length),
or retrain is a Callable and the first trainable point is earlier than the first predictable point.
the first trainable point (given train_length) otherwise
Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with
None
) and start at the first trainable/predictable point.forecast_horizon (
int
) – The forecast horizon for the predictions.stride (
int
) – The number of time steps between two consecutive predictions.retrain (
Union
[bool
,int
,Callable
[…,bool
]]) –Whether and/or on which condition to retrain the model before predicting. This parameter supports 3 different datatypes:
bool
, (positive)int
, andCallable
(returning abool
). In the case ofbool
: retrain the model at each step (True), or never retrains the model (False). In the case ofint
: the model is retrained every retrain iterations. In the case ofCallable
: the model is retrained whenever callable returns True. The callable must have the following positional arguments:counter (int): current retrain iteration
pred_time (pd.Timestamp or int): timestamp of forecast time (end of the training series)
train_series (TimeSeries): train series up to pred_time
past_covariates (TimeSeries): past_covariates series up to pred_time
future_covariates (TimeSeries): future_covariates series up to min(pred_time + series.freq * forecast_horizon, series.end_time())
Note: if any optional *_covariates are not passed to historical_forecast,
None
will be passed to the corresponding retrain function argument. Note: some models do require being retrained every time and do not support anything other than retrain=True.overlap_end (
bool
) – Whether the returned forecasts can go beyond the series’ end or not.last_points_only (
bool
) – Whether to retain only the last point of each historical forecast. If set to True, the method returns a singleTimeSeries
containing the successive point forecasts. Otherwise, returns a list of historicalTimeSeries
forecasts.verbose (
bool
) – Whether to print progress.show_warnings (
bool
) – Whether to show warnings related to parameters start, and train_length.
- Returns
If last_points_only is set to True and a single series is provided in input, a single
TimeSeries
is returned, which contains the the historical forecast at the desired horizon.A
List[TimeSeries]
is returned if either series is aSequence
ofTimeSeries
, or if last_points_only is set to False. A list of lists is returned if both conditions are met. In this last case, the outer list is over the series provided in the input sequence, and the inner lists contain the different historical forecasts.- Return type
TimeSeries or List[TimeSeries] or List[List[TimeSeries]]
- static load(path)¶
Loads the model from a given path or file handle.
- Parameters
path (
Union
[str
,BinaryIO
]) – Path or file handle from which to load the model.- Return type
ForecastingModel
- property min_train_samples: int¶
The minimum number of samples for training the model.
- Return type
int
- property model_params: dict¶
- Return type
dict
- predict(n, num_samples=1, verbose=False)[source]¶
Forecasts values for n time steps after the end of the training series.
- Parameters
n (
int
) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Should be left set to 1 for deterministic models.
- Returns
A time series containing the n next points after then end of the training series.
- Return type
- residuals(series, past_covariates=None, future_covariates=None, forecast_horizon=1, retrain=True, verbose=False)¶
Compute the residuals produced by this model on a (or sequence of) univariate time series.
This function computes the difference between the actual observations from series and the fitted values vector p obtained by training the model on series. For every index i in series, p[i] is computed by training the model on
series[:(i - forecast_horizon)]
and forecasting forecast_horizon into the future. (p[i] will be set to the last value of the predicted series.) The vector of residuals will be shorter than series due to the minimum training series length required by the model and the gap introduced by forecast_horizon. Most commonly, the term “residuals” implies a value for forecast_horizon of 1; but this can be configured.This method works only on univariate series. It uses the median prediction (when dealing with stochastic forecasts).
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The univariate TimeSeries instance which the residuals will be computed for.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – One or several past-observed covariate time series.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – One or several future-known covariate time series.forecast_horizon (
int
) – The forecasting horizon used to predict each fitted value.retrain (
bool
) – Whether to train the model at each iteration, for models that support it. If False, the model is not trained at all. Default: Trueverbose (
bool
) – Whether to print progress.
- Returns
The vector of residuals.
- Return type
TimeSeries (or Sequence[TimeSeries])
- save(path=None, **pkl_kwargs)¶
Saves the model under a given path or file handle.
Example for saving and loading a
RegressionModel
:from darts.models import RegressionModel model = RegressionModel(lags=4) model.save("my_model.pkl") model_loaded = RegressionModel.load("my_model.pkl")
- Parameters
path (
Union
[str
,BinaryIO
,None
]) – Path or file handle under which to save the model at its current state. If no path is specified, the model is automatically saved under"{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pkl"
. E.g.,"RegressionModel_2020-01-01_12_00_00.pkl"
.pkl_kwargs – Keyword arguments passed to pickle.dump()
- Return type
None
- static select_best_model(ts, thetas=None, m=None, normalization=True, n_jobs=1)[source]¶
Performs a grid search over all hyper parameters to select the best model, using the fitted values on the training series ts.
Uses ‘LocalForecastingModel.gridsearch’ with ‘use_fitted_values=True’ and ‘metric=metrics.mae`.
- Parameters
ts (
TimeSeries
) – The TimeSeries on which the model will be tested.thetas (
Optional
[List
[int
]]) – A list of thetas to loop over. Defaults to [1, 2, 3].m (
Optional
[int
]) – Optionally, the season used to decompose the time series.normalization (
bool
) – If True, the data is normalized so that the mean is 1. Defaults to True.n_jobs (
int
) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more theta values to be evaluated. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.
- Returns
The best performing model on the time series.
- Return type
- property supports_future_covariates¶
Whether model supports future covariates
- property supports_past_covariates¶
Whether model supports past covariates
- property supports_static_covariates: bool¶
Whether model supports static covariates
- Return type
bool
- property uses_future_covariates¶
Whether the model uses future covariates, once fitted.
- property uses_past_covariates¶
Whether the model uses past covariates, once fitted.
- property uses_static_covariates¶
Whether the model uses static covariates, once fitted.
- class darts.models.forecasting.theta.Theta(theta=2, seasonality_period=None, season_mode=SeasonalityMode.MULTIPLICATIVE)[source]¶
Bases:
darts.models.forecasting.forecasting_model.LocalForecastingModel
An implementation of the Theta method with configurable theta parameter. See [1].
The training time series is de-seasonalized according to seasonality_period, or an inferred seasonality period.
season_mode must be a
SeasonalityMode
Enum member.You can access the Enum with
from darts import SeasonalityMode
.- Parameters
theta (
int
) – Value of the theta parameter. Defaults to 2. Cannot be set to 0. If theta = 1, then the theta method restricts to a simple exponential smoothing (SES)seasonality_period (
Optional
[int
]) – User-defined seasonality period. If not set, will be tentatively inferred from the training series upon callingfit()
.season_mode (
SeasonalityMode
) – Type of seasonality. EitherSeasonalityMode.MULTIPLICATIVE
,SeasonalityMode.ADDITIVE
orSeasonalityMode.NONE
. Defaults toSeasonalityMode.MULTIPLICATIVE
.
References
- 1
Unmasking the Theta method <https://robjhyndman.com/papers/Theta.pdf
Attributes
Whether the model considers static covariates, if there are any.
A 6-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag).
The minimum number of samples for training the model.
Whether model supports future covariates
Whether model supports past covariates
Whether model supports static covariates
Whether the model uses future covariates, once fitted.
Whether the model uses past covariates, once fitted.
Whether the model uses static covariates, once fitted.
model_params
Methods
backtest
(series[, past_covariates, ...])Compute error values that the model would have produced when used on (potentially multiple) series.
fit
(series)Fit/train the model on the provided series.
generate_fit_encodings
(series[, ...])Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
generate_predict_encodings
(n, series[, ...])Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
gridsearch
(parameters, series[, ...])Find the best hyper-parameters among a given set using a grid search.
historical_forecasts
(series[, ...])Compute the historical forecasts that would have been obtained by this model on (potentially multiple) series.
load
(path)Loads the model from a given path or file handle.
predict
(n[, num_samples, verbose])Forecasts values for n time steps after the end of the training series.
residuals
(series[, past_covariates, ...])Compute the residuals produced by this model on a (or sequence of) univariate time series.
save
([path])Saves the model under a given path or file handle.
- backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, num_samples=1, train_length=None, start=None, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True)¶
Compute error values that the model would have produced when used on (potentially multiple) series.
If historical_forecasts are provided, the metric (given by the metric function) is evaluated directly on the forecast and the actual values. Otherwise, it repeatedly builds a training set: either expanding from the beginning of series or moving with a fixed length train_length. It trains the current model on the training set, emits a forecast of length equal to forecast_horizon, and then moves the end of the training set forward by stride time steps. The metric is then evaluated on the forecast and the actual values. Finally, the method returns a reduction (the mean by default) of all these metric scores.
By default, this method uses each historical forecast (whole) to compute error scores. If last_points_only is set to True, it will use only the last point of each historical forecast. In this case, no reduction is used.
By default, this method always re-trains the models on the entire available history, corresponding to an expanding window strategy. If retrain is set to False (useful for models for which training might be time-consuming, such as deep learning models), the trained model will be used directly to emit the forecasts.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The (or a sequence of) target time series used to successively train and evaluate the historical forecasts.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) future-known covariate series. This applies only if the model supports future covariates.historical_forecasts (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the (or a sequence of) historical forecasts time series to be evaluated. Corresponds to the output ofhistorical_forecasts()
. If provided, will skip historical forecasting and ignore all parameters except series, metric, and reduction.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Use values >1 only for probabilistic models.train_length (
Optional
[int
]) – Number of time steps in our training set (size of backtesting window to train on). Only effective when retrain is notFalse
. Default is set to train_length=None where it takes all available time steps up until prediction time, otherwise the moving window strategy is used. If larger than the number of time steps available, all steps up until prediction time are used, as in default case. Needs to be at least min_train_series_length.start (
Union
[Timestamp
,float
,int
,None
]) –Optionally, the first point in time at which a prediction is computed for a future time. This parameter supports:
float
,int
andpandas.Timestamp
, andNone
. If afloat
, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. If anint
, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. If apandas.Timestamp
, the time stamp will be used to determine the first prediction time directly. IfNone
, the first prediction time will automatically be set to:the first predictable point if retrain is
False
, or retrain is a Callable and the first
predictable point is earlier than the first trainable point.
the first trainable point if retrain is
True
orint
(given train_length),
or retrain is a Callable and the first trainable point is earlier than the first predictable point.
the first trainable point (given train_length) otherwise
Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with
None
) and start at the first trainable/predictable point.forecast_horizon (
int
) – The forecast horizon for the point predictions.stride (
int
) – The number of time steps between two consecutive predictions.retrain (
Union
[bool
,int
,Callable
[…,bool
]]) –Whether and/or on which condition to retrain the model before predicting. This parameter supports 3 different datatypes:
bool
, (positive)int
, andCallable
(returning abool
). In the case ofbool
: retrain the model at each step (True), or never retrains the model (False). In the case ofint
: the model is retrained every retrain iterations. In the case ofCallable
: the model is retrained whenever callable returns True. The callable must have the following positional arguments:counter (int): current retrain iteration
pred_time (pd.Timestamp or int): timestamp of forecast time (end of the training series)
train_series (TimeSeries): train series up to pred_time
past_covariates (TimeSeries): past_covariates series up to pred_time
future_covariates (TimeSeries): future_covariates series up to min(pred_time + series.freq * forecast_horizon, series.end_time())
Note: if any optional *_covariates are not passed to historical_forecast,
None
will be passed to the corresponding retrain function argument. Note: some models do require being retrained every time and do not support anything other than retrain=True.overlap_end (
bool
) – Whether the returned forecasts can go beyond the series’ end or not.last_points_only (
bool
) – Whether to use the whole historical forecasts or only the last point of each forecast to compute the error.metric (
Union
[Callable
[[TimeSeries
,TimeSeries
],float
],List
[Callable
[[TimeSeries
,TimeSeries
],float
]]]) – A function or a list of function that takes twoTimeSeries
instances as inputs and returns an error value.reduction (
Optional
[Callable
[[ndarray
],float
]]) – A function used to combine the individual error scores obtained when last_points_only is set to False. When providing several metric functions, the function will receive the argument axis = 0 to obtain single value for each metric function. If explicitly set to None, the method will return a list of the individual error scores instead. Set tonp.mean
by default.verbose (
bool
) – Whether to print progress.show_warnings (
bool
) – Whether to show warnings related to parameters start, and train_length.
- Returns
The (sequence of) error score on a series, or list of list containing error scores for each provided series and each sample.
- Return type
float or List[float] or List[List[float]]
- property considers_static_covariates¶
Whether the model considers static covariates, if there are any.
- property extreme_lags: Tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int]]¶
A 6-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag). If 0 is the index of the first prediction, then all lags are relative to this index.
See examples below.
- If the model wasn’t fitted with:
target (concerning RegressionModels only): then the first element should be None.
past covariates: then the third and fourth elements should be None.
future covariates: then the fifth and sixth elements should be None.
Should be overridden by models that use past or future covariates, and/or for model that have minimum target lag and maximum target lags potentially different from -1 and 0.
Notes
maximum target lag (second value) cannot be None and is always larger than or equal to 0.
Examples
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2) >>> model.fit(train_series) >>> model.extreme_lags (-3, 1, None, None, None, None) >>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7) >>> model.fit(train_series, past_covariates=past_covariates) >>> model.extreme_lags (-5, 6, -4, -1, None, None) >>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7) >>> model.fit(train_series, future_covariates=future_covariates) >>> model.extreme_lags (-5, 6, None, None, 4, 6) >>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7) >>> model.fit(train_series) >>> model.extreme_lags (-10, 6, None, None, None, None) >>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6]) >>> model.fit(train_series, future_covariates) >>> model.extreme_lags (-10, 6, None, None, 4, 6)
- Return type
Tuple
[Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
],Optional
[int
]]
- fit(series)[source]¶
Fit/train the model on the provided series.
- Parameters
series (
TimeSeries
) – A target time series. The model will be trained to forecast this time series.- Returns
Fitted model.
- Return type
self
- generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶
Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you used to train/fit the model.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The series or sequence of series with the target values used when fitting the model.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the series or sequence of series with the past-observed covariates used when fitting the model.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the series or sequence of series with the future-known covariates used when fitting the model.
- Returns
A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.
- Return type
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]
- generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you intend to use for prediction.
- Parameters
n (
int
) – The number of prediction time steps after the end of series intended to be used for prediction.series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The series or sequence of series with target values intended to be used for prediction.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the past-observed covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.
- Returns
A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.
- Return type
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]
- classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=0.5, last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None)¶
Find the best hyper-parameters among a given set using a grid search.
This function has 3 modes of operation: Expanding window mode, split mode and fitted value mode. The three modes of operation evaluate every possible combination of hyper-parameter values provided in the parameters dictionary by instantiating the model_class subclass of ForecastingModel with each combination, and returning the best-performing model with regard to the metric function. The metric function is expected to return an error value, thus the model resulting in the smallest metric output will be chosen.
The relationship of the training data and test data depends on the mode of operation.
Expanding window mode (activated when forecast_horizon is passed): For every hyperparameter combination, the model is repeatedly trained and evaluated on different splits of series. This process is accomplished by using the
backtest()
function as a subroutine to produce historic forecasts starting from start that are compared against the ground truth values of series. Note that the model is retrained for every single prediction, thus this mode is slower.Split window mode (activated when val_series is passed): This mode will be used when the val_series argument is passed. For every hyper-parameter combination, the model is trained on series and evaluated on val_series.
Fitted value mode (activated when use_fitted_values is set to True): For every hyper-parameter combination, the model is trained on series and evaluated on the resulting fitted values. Not all models have fitted values, and this method raises an error if the model doesn’t have a fitted_values member. The fitted values are the result of the fit of the model on series. Comparing with the fitted values can be a quick way to assess the model, but one cannot see if the model is overfitting the series.
Derived classes must ensure that a single instance of a model will not share parameters with the other instances, e.g., saving models in the same path. Otherwise, an unexpected behavior can arise while running several models in parallel (when
n_jobs != 1
). If this cannot be avoided, then gridsearch should be redefined, forcingn_jobs = 1
.Currently this method only supports deterministic predictions (i.e. when models’ predictions have only 1 sample).
- Parameters
model_class – The ForecastingModel subclass to be tuned for ‘series’.
parameters (
dict
) – A dictionary containing as keys hyperparameter names, and as values lists of values for the respective hyperparameter.series (
TimeSeries
) – The target series used as input and target for training.past_covariates (
Optional
[TimeSeries
]) – Optionally, a past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Optional
[TimeSeries
]) – Optionally, a future-known covariate series. This applies only if the model supports future covariates.forecast_horizon (
Optional
[int
]) – The integer value of the forecasting horizon. Activates expanding window mode.stride (
int
) – The number of time steps between two consecutive predictions. Only used in expanding window mode.start (
Union
[Timestamp
,float
,int
]) – Theint
,float
orpandas.Timestamp
that represents the starting point in the time index of series from which predictions will be made to evaluate the model. For a detailed description of how the different data types are interpreted, please see the documentation for ForecastingModel.backtest. Only used in expanding window mode.last_points_only (
bool
) – Whether to use the whole forecasts or only the last point of each forecast to compute the error. Only used in expanding window mode.show_warnings (
bool
) – Whether to show warnings related to the start parameter. Only used in expanding window mode.val_series (
Optional
[TimeSeries
]) – The TimeSeries instance used for validation in split mode. If provided, this series must start right after the end of series; so that a proper comparison of the forecast can be made.use_fitted_values (
bool
) – If True, uses the comparison with the fitted values. Raises an error iffitted_values
is not an attribute of model_class.metric (
Callable
[[TimeSeries
,TimeSeries
],float
]) – A function that takes two TimeSeries instances as inputs (actual and prediction, in this order), and returns a float error value.reduction (
Callable
[[ndarray
],float
]) – A reduction function (mapping array to float) describing how to aggregate the errors obtained on the different validation series when backtesting. By default it’ll compute the mean of errors.verbose – Whether to print progress.
n_jobs (
int
) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more parameters combinations to evaluate. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.n_random_samples (
Union
[int
,float
,None
]) – The number/ratio of hyperparameter combinations to select from the full parameter grid. This will perform a random search instead of using the full grid. If an integer, n_random_samples is the number of parameter combinations selected from the full grid and must be between 0 and the total number of parameter combinations. If a float, n_random_samples is the ratio of parameter combinations selected from the full grid and must be between 0 and 1. Defaults to None, for which random selection will be ignored.
- Returns
A tuple containing an untrained model_class instance created from the best-performing hyper-parameters, along with a dictionary containing these best hyper-parameters, and metric score for the best hyper-parameters.
- Return type
ForecastingModel, Dict, float
- historical_forecasts(series, past_covariates=None, future_covariates=None, num_samples=1, train_length=None, start=None, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True)¶
Compute the historical forecasts that would have been obtained by this model on (potentially multiple) series.
This method repeatedly builds a training set: either expanding from the beginning of series or moving with a fixed length train_length. It trains the model on the training set, emits a forecast of length equal to forecast_horizon, and then moves the end of the training set forward by stride time steps.
By default, this method will return one (or a sequence of) single time series made up of the last point of each historical forecast. This time series will thus have a frequency of
series.freq * stride
. If last_points_only is set to False, it will instead return one (or a sequence of) list of the historical forecasts series.By default, this method always re-trains the models on the entire available history, corresponding to an expanding window strategy. If retrain is set to False, the model must have been fit before. This is not supported by all models.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The (or a sequence of) target time series used to successively train and compute the historical forecasts.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) past-observed covariate series. This applies only if the model supports past covariates.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – Optionally, one (or a sequence of) of future-known covariate series. This applies only if the model supports future covariates.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Use values >1 only for probabilistic models.train_length (
Optional
[int
]) – Number of time steps in our training set (size of backtesting window to train on). Only effective when retrain is notFalse
. Default is set to train_length=None where it takes all available time steps up until prediction time, otherwise the moving window strategy is used. If larger than the number of time steps available, all steps up until prediction time are used, as in default case. Needs to be at least min_train_series_length.start (
Union
[Timestamp
,float
,int
,None
]) –Optionally, the first point in time at which a prediction is computed for a future time. This parameter supports:
float
,int
andpandas.Timestamp
, andNone
. If afloat
, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. If anint
, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. If apandas.Timestamp
, the time stamp will be used to determine the first prediction time directly. IfNone
, the first prediction time will automatically be set to:the first predictable point if retrain is
False
, or retrain is a Callable and the first
predictable point is earlier than the first trainable point.
the first trainable point if retrain is
True
orint
(given train_length),
or retrain is a Callable and the first trainable point is earlier than the first predictable point.
the first trainable point (given train_length) otherwise
Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with
None
) and start at the first trainable/predictable point.forecast_horizon (
int
) – The forecast horizon for the predictions.stride (
int
) – The number of time steps between two consecutive predictions.retrain (
Union
[bool
,int
,Callable
[…,bool
]]) –Whether and/or on which condition to retrain the model before predicting. This parameter supports 3 different datatypes:
bool
, (positive)int
, andCallable
(returning abool
). In the case ofbool
: retrain the model at each step (True), or never retrains the model (False). In the case ofint
: the model is retrained every retrain iterations. In the case ofCallable
: the model is retrained whenever callable returns True. The callable must have the following positional arguments:counter (int): current retrain iteration
pred_time (pd.Timestamp or int): timestamp of forecast time (end of the training series)
train_series (TimeSeries): train series up to pred_time
past_covariates (TimeSeries): past_covariates series up to pred_time
future_covariates (TimeSeries): future_covariates series up to min(pred_time + series.freq * forecast_horizon, series.end_time())
Note: if any optional *_covariates are not passed to historical_forecast,
None
will be passed to the corresponding retrain function argument. Note: some models do require being retrained every time and do not support anything other than retrain=True.overlap_end (
bool
) – Whether the returned forecasts can go beyond the series’ end or not.last_points_only (
bool
) – Whether to retain only the last point of each historical forecast. If set to True, the method returns a singleTimeSeries
containing the successive point forecasts. Otherwise, returns a list of historicalTimeSeries
forecasts.verbose (
bool
) – Whether to print progress.show_warnings (
bool
) – Whether to show warnings related to parameters start, and train_length.
- Returns
If last_points_only is set to True and a single series is provided in input, a single
TimeSeries
is returned, which contains the the historical forecast at the desired horizon.A
List[TimeSeries]
is returned if either series is aSequence
ofTimeSeries
, or if last_points_only is set to False. A list of lists is returned if both conditions are met. In this last case, the outer list is over the series provided in the input sequence, and the inner lists contain the different historical forecasts.- Return type
TimeSeries or List[TimeSeries] or List[List[TimeSeries]]
- static load(path)¶
Loads the model from a given path or file handle.
- Parameters
path (
Union
[str
,BinaryIO
]) – Path or file handle from which to load the model.- Return type
ForecastingModel
- property min_train_samples: int¶
The minimum number of samples for training the model.
- Return type
int
- property model_params: dict¶
- Return type
dict
- predict(n, num_samples=1, verbose=False)[source]¶
Forecasts values for n time steps after the end of the training series.
- Parameters
n (
int
) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.num_samples (
int
) – Number of times a prediction is sampled from a probabilistic model. Should be left set to 1 for deterministic models.
- Returns
A time series containing the n next points after then end of the training series.
- Return type
- residuals(series, past_covariates=None, future_covariates=None, forecast_horizon=1, retrain=True, verbose=False)¶
Compute the residuals produced by this model on a (or sequence of) univariate time series.
This function computes the difference between the actual observations from series and the fitted values vector p obtained by training the model on series. For every index i in series, p[i] is computed by training the model on
series[:(i - forecast_horizon)]
and forecasting forecast_horizon into the future. (p[i] will be set to the last value of the predicted series.) The vector of residuals will be shorter than series due to the minimum training series length required by the model and the gap introduced by forecast_horizon. Most commonly, the term “residuals” implies a value for forecast_horizon of 1; but this can be configured.This method works only on univariate series. It uses the median prediction (when dealing with stochastic forecasts).
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – The univariate TimeSeries instance which the residuals will be computed for.past_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – One or several past-observed covariate time series.future_covariates (
Union
[TimeSeries
,Sequence
[TimeSeries
],None
]) – One or several future-known covariate time series.forecast_horizon (
int
) – The forecasting horizon used to predict each fitted value.retrain (
bool
) – Whether to train the model at each iteration, for models that support it. If False, the model is not trained at all. Default: Trueverbose (
bool
) – Whether to print progress.
- Returns
The vector of residuals.
- Return type
TimeSeries (or Sequence[TimeSeries])
- save(path=None, **pkl_kwargs)¶
Saves the model under a given path or file handle.
Example for saving and loading a
RegressionModel
:from darts.models import RegressionModel model = RegressionModel(lags=4) model.save("my_model.pkl") model_loaded = RegressionModel.load("my_model.pkl")
- Parameters
path (
Union
[str
,BinaryIO
,None
]) – Path or file handle under which to save the model at its current state. If no path is specified, the model is automatically saved under"{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pkl"
. E.g.,"RegressionModel_2020-01-01_12_00_00.pkl"
.pkl_kwargs – Keyword arguments passed to pickle.dump()
- Return type
None
- property supports_future_covariates¶
Whether model supports future covariates
- property supports_past_covariates¶
Whether model supports past covariates
- property supports_static_covariates: bool¶
Whether model supports static covariates
- Return type
bool
- property uses_future_covariates¶
Whether the model uses future covariates, once fitted.
- property uses_past_covariates¶
Whether the model uses past covariates, once fitted.
- property uses_static_covariates¶
Whether the model uses static covariates, once fitted.