Random Forest

A forecasting model using a random forest regression. It uses some of the target series’ lags, as well as optionally some covariate series’ lags in order to obtain a forecast.

See [1] for a reference around random forests.

The implementations is wrapped around RandomForestRegressor.

References

1

https://en.wikipedia.org/wiki/Random_forest

class darts.models.forecasting.random_forest.RandomForest(lags=None, lags_past_covariates=None, lags_future_covariates=None, output_chunk_length=1, n_estimators=100, max_depth=None, **kwargs)[source]

Bases: darts.models.forecasting.regression_model.RegressionModel

Random Forest Model

Parameters
  • lags (Union[int, list, None]) – Lagged target values used to predict the next time step. If an integer is given the last lags past lags are used (from -1 backward). Otherwise a list of integers with lags is required (each lag must be < 0).

  • lags_past_covariates (Union[int, List[int], None]) – Number of lagged past_covariates values used to predict the next time step. If an integer is given the last lags_past_covariates past lags are used (inclusive, starting from lag -1). Otherwise a list of integers with lags < 0 is required.

  • lags_future_covariates (Union[Tuple[int, int], List[int], None]) – Number of lagged future_covariates values used to predict the next time step. If an tuple (past, future) is given the last past lags in the past are used (inclusive, starting from lag -1) along with the first future future lags (starting from 0 - the prediction time - up to future - 1 included). Otherwise a list of integers with lags is required.

  • output_chunk_length (int) – Number of time steps predicted at once by the internal regression model. Does not have to equal the forecast horizon n used in predict(). However, setting output_chunk_length equal to the forecast horizon may be useful if the covariates don’t extend far enough into the future.

  • n_estimators (int) – The number of trees in the forest.

  • max_depth (int) – The maximum depth of the tree. If None, then nodes are expanded until all leaves are pure or until all leaves contain less than min_samples_split samples.

  • **kwargs – Additional keyword arguments passed to sklearn.ensemble.RandomForest.

Attributes

model_params

Methods

backtest(series[, past_covariates, ...])

Compute error values that the model would have produced when used on series.

fit(series[, past_covariates, ...])

Fit/train the model on one or multiple series.

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 the series.

predict(n[, series, past_covariates, ...])

Forecasts values for n time steps after the end of the series.

residuals(series[, forecast_horizon, verbose])

Compute the residuals produced by this model on a univariate time series.

backtest(series, past_covariates=None, future_covariates=None, num_samples=1, train_length=None, start=0.5, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False)

Compute error values that the model would have produced when used on series.

It repeatedly builds a training set from the beginning of series. 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. A metric (given by the metric function) 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 model will only be trained on the initial training window (up to start time stamp), and only if it has not been trained before. Then, at every iteration, the newly expanded input sequence will be fed to the model to produce the new output.

Parameters
  • series (TimeSeries) – The target time series to use to successively train and evaluate the historical forecasts

  • past_covariates (Optional[TimeSeries]) – An optional past-observed covariate series. This applies only if the model supports past covariates.

  • future_covariates (Optional[TimeSeries]) – An optional 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. Should be left set to 1 for deterministic models.

  • train_length (Optional[int]) – Number of time steps in our training set (size of backtesting window to train on). 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]) – The first prediction time, at which a prediction is computed for a future time. This parameter supports 3 different types: float, int and pandas.Timestamp. In the case of float, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. In the case of int, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. In case of pandas.Timestamp, this time stamp will be used to determine the first prediction time directly.

  • forecast_horizon (int) – The forecast horizon for the point prediction.

  • stride (int) – The number of time steps between two consecutive training sets.

  • retrain (bool) – Whether to retrain the model for every prediction or not. Not all models support setting retrain to False. Notably, this is supported by neural networks based models.

  • 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 (Callable[[TimeSeries, TimeSeries], float]) – A function that takes two TimeSeries 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. If explicitely set to None, the method will return a list of the individual error scores instead. Set to np.mean by default.

  • verbose (bool) – Whether to print progress

Returns

The error score, or the list of individual error scores if reduction is None

Return type

float or List[float]

fit(series, past_covariates=None, future_covariates=None, max_samples_per_ts=None, n_jobs_multioutput_wrapper=None, **kwargs)

Fit/train the model on one or multiple series.

Parameters
  • series (Union[TimeSeries, Sequence[TimeSeries]]) – TimeSeries or Sequence[TimeSeries] object containing the target values.

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a series or sequence of series specifying past-observed covariates

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a series or sequence of series specifying future-known covariates

  • max_samples_per_ts (Optional[int]) – This is an integer upper bound on the number of tuples that can be produced per time series. It can be used in order to have an upper bound on the total size of the dataset and ensure proper sampling. If None, it will read all of the individual time series in advance (at dataset creation) to know their sizes, which might be expensive on big datasets. If some series turn out to have a length that would allow more than max_samples_per_ts, only the most recent max_samples_per_ts samples will be considered.

  • n_jobs_multioutput_wrapper (Optional[int]) – Number of jobs of the MultiOutputRegressor wrapper to run in parallel. Only used if the model doesn’t support multi-output regression natively.

  • **kwargs – Additional keyword arguments passed to the fit method of the model.

classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=0.5, last_points_only=False, 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, forcing n_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 TimeSeries instance used as input and target for training.

  • past_covariates (Optional[TimeSeries]) – An optional past-observed covariate series. This applies only if the model supports past covariates.

  • future_covariates (Optional[TimeSeries]) – An optional 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]) – The int, float or pandas.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.

  • last_points_only (bool) – Whether to use the whole forecasts or only the last point of each forecast to compute the error

  • 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 if fitted_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=0.5, forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False)

Compute the historical forecasts that would have been obtained by this model on the series.

This method uses an expanding training window; it repeatedly builds a training set from the beginning of series. 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 a 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 a 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 will only be trained on the initial training window (up to start time stamp), and only if it has not been trained before. This is not supported by all models.

Parameters
  • series (TimeSeries) – The target time series to use to successively train and evaluate the historical forecasts.

  • past_covariates (Optional[TimeSeries]) – An optional past-observed covariate series. This applies only if the model supports past covariates.

  • future_covariates (Optional[TimeSeries]) – An optional 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. Should be left set to 1 for deterministic models.

  • train_length (Optional[int]) – Number of time steps in our training set (size of backtesting window to train on). 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]) – The first point of time at which a prediction is computed for a future time. This parameter supports 3 different data types: float, int and pandas.Timestamp. In the case of float, the parameter will be treated as the proportion of the time series that should lie before the first prediction point. In the case of int, the parameter will be treated as an integer index to the time index of series that will be used as first prediction time. In case of pandas.Timestamp, this time stamp will be used to determine the first prediction time directly.

  • forecast_horizon (int) – The forecast horizon for the predictions

  • stride (int) – The number of time steps between two consecutive predictions.

  • retrain (bool) – Whether to retrain the model for every prediction or not. Not all models support setting retrain to False. Notably, this is supported by neural networks based models.

  • 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 single TimeSeries containing the successive point forecasts. Otherwise returns a list of historical TimeSeries forecasts.

  • verbose (bool) – Whether to print progress

Returns

By default, a single TimeSeries instance created from the last point of each individual forecast. If last_points_only is set to False, a list of the historical forecasts.

Return type

TimeSeries or List[TimeSeries]

property model_params: dict
Return type

dict

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, **kwargs)

Forecasts values for n time steps after the end of the series.

Parameters
  • n (int) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.

  • series (TimeSeries or list of TimeSeries, optional) – Optionally, one or several input TimeSeries, representing the history of the target series whose future is to be predicted. If specified, the method returns the forecasts of these series. Otherwise, the method returns the forecast of the (single) training series.

  • past_covariates (TimeSeries or list of TimeSeries, optional) – Optionally, the past-observed covariates series needed as inputs for the model. They must match the covariates used for training in terms of dimension and type.

  • future_covariates (TimeSeries or list of TimeSeries, optional) – Optionally, the future-known covariates series needed as inputs for the model. They must match the covariates used for training in terms of dimension and type.

  • num_samples (int, default: 1) – Currently this parameter is ignored for regression models.

  • **kwargs (dict, optional) – Additional keyword arguments passed to the predict method of the model. Only works with univariate target series.

Return type

Union[TimeSeries, Sequence[TimeSeries]]

residuals(series, forecast_horizon=1, verbose=False)

Compute the residuals produced by this model on a 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 and does not currently support covariates. It uses the median prediction (when dealing with stochastic forecasts).

Parameters
  • series (TimeSeries) – The univariate TimeSeries instance which the residuals will be computed for.

  • forecast_horizon (int) – The forecasting horizon used to predict each fitted value.

  • verbose (bool) – Whether to print progress.

Returns

The vector of residuals.

Return type

TimeSeries