combine_forecasts {forecastML}

Combine multiple horizon-specific forecast models to produce one forecast

Description

The horizon-specific models can either be combined to (a) produce final forecasts for only those horizons at which they were trained (i.e., shorter-horizon models override longer-horizon models when producing final short-horizon h-step-ahead forecasts) or (b) produce final forecasts using any combination of horizon-specific models that minimized error over the validation/training dataset.

Usage

combine_forecasts(
  ...,
  type = c("horizon", "error"),
  aggregate = stats::median,
  data_error = list(NULL),
  metric = NULL
)

Arguments

...

One or more objects of class 'forecast_results' from running predict.forecast_model() on an input forward-looking forecast dataset. These are the forecasts from the horizon-specific direct forecasting models trained over the entire training dataset by setting create_windows(..., window_length = 0). If multiple models are passed in ... with the same direct forecast horizon, for type = 'horizon', forecasts for the same direct forecast horizon are combined with aggregate; for type = 'error', the model that minimizes the error metric at the given direct forecast horizon produces the forecast.

type

Default: 'horizon'. A character vector of length 1 that identifies the forecast combination method.

aggregate

Default median for type = 'horizon'. A function–without parentheses–that aggregates forecasts if more than one model passed in ... has the same direct forecast horizon and type = 'horizon'].

data_error

Optional. A list of objects of class 'validation_error' from running return_error() on a training dataset. The length and order of data_error should match the models passed in ....

metric

Required if data_error is given. A length 1 character vector naming the forecast error metric used to select the optimal model at each forecast horizon from the models passed in '...' e.g., 'mae'.

Value

An S3 object of class 'forecastML' with final h-step-ahead forecasts.

Forecast combination type:

• type = 'horizon': 1 final h-step-ahead forecast is returned for each model object passed in ....

• type = 'error': 1 final h-step-ahead forecast is returned by selecting, for each forecast horizon, the model that minimized the chosen error metric at that horizon on the outer-loop validation data sets.

Columns in returned 'forecastML' data.frame:

• model: User-supplied model name in train_model().

• model_forecast_horizon: The direct-forecasting time horizon that the model was trained on.

• horizon: Forecast horizons, 1:h, measured in dataset rows.

• forecast_period: The forecast period in row indices or dates. The forecast period starts at either attributes(create_lagged_df())$data_stop + 1 for row indices or attributes(create_lagged_df())$data_stop + 1 * frequency for date indices.

• "groups": If given, the user-supplied groups in create_lagged_df().

• "outcome_name"_pred: The final forecasts.

• "outcome_name"_pred_lower: If given, the lower forecast bounds returned by the user-supplied prediction function.

• "outcome_name"_pred_upper: If given, the upper forecast bounds returned by the user-supplied prediction function.

Methods and related functions

The output of combine_forecasts() has the following generic S3 methods

• plot

Examples

# Example with "type = 'horizon'".
data("data_seatbelts", package = "forecastML")

horizons <- c(1, 3, 12)
lookback <- 1:15

data_train <- create_lagged_df(data_seatbelts, type = "train", outcome_col = 1,
                               lookback = lookback, horizon = horizons)

windows <- create_windows(data_train, window_length = 0)

model_function <- function(data, my_outcome_col) {
  model <- lm(DriversKilled ~ ., data = data)
  return(model)
}

model_results <- train_model(data_train, windows, model_name = "LM", model_function)

data_forecast <- create_lagged_df(data_seatbelts, type = "forecast", outcome_col = 1,
                                  lookback = lookback, horizon = horizons)

prediction_function <- function(model, data_features) {
  x <- data_features
  data_pred <- data.frame("y_pred" = predict(model, newdata = x))
  return(data_pred)
}

data_forecasts <- predict(model_results, prediction_function = list(prediction_function),
                          data = data_forecast)

data_combined <- combine_forecasts(data_forecasts)

plot(data_combined)