gears: GEARS Method for Time Series Forecasting

In gu-stat/gears: GEARS Method for Univariate and Multivariate Time Series Forecasting

Description

Use the GEARS Method for forecasting using data from univariate time series objects or from data frame objects.

Usage

gears(
  DATA,
  forecast.horizon,
  size.rs,
  number.rs,
  glm.family = c("gaussian", "binomial", "poisson", "Gamma", "quasi"),
  level = 95,
  details = FALSE,
  y.name = NULL,
  y.max.lags = NULL,
  x.names = NULL,
  x.max.lags = NULL,
  x.fixed.names = NULL,
  x.fixed.lags = NULL,
  x.interaction.names = NULL,
  x.interaction.lags = NULL,
  last.obs = NULL,
  use.intercept = c("both", "without", "with"),
  error.measure = c("mse", "mae", "mase", "smape", "owa"),
  betas.selection = c("last", "average", "both"),
  use.parallel = FALSE,
  num.cores = NULL,
  ...
)

Arguments

DATA	A data frame or a univariate time series.
forecast.horizon	Number of periods for forecasting.
size.rs	Number of observations in the rolling sample.
number.rs	Number of rolling samples.
glm.family	A description of the error distribution to be used in the model. See glm for details.
level	Confidence level for prediction intervals. Numeric value between 0 and 100.
details	If TRUE, the function outputs the entire glm object for all random samples for each forecast lead. To save memory, the default is FALSE.
y.name	The name of the Y (left-hand side) variable. If NULL (default), the function creates a temporary name.
y.max.lags	A numeric value that gives the maximum number of lags of the Y (left-hand side) variable (see Details). Can be NULL (default) if the past values of the Y variable are not included in the model.
x.names	List with names of the X (right-hand side) variables that have a maximum number of lags (see Details). Can be NULL (default) if univariate model or if your model does not have variables of this type.
x.max.lags	List of numeric values that give the maximum number of lags of the X (right-hand side) variables. Can be NULL (default).
x.fixed.names	List with names of the X (right-hand side) variables that have a fixed number of lags (see Details). Can be NULL (default) if univariate model or if your model does not have variables of this type.
x.fixed.lags	List of numeric values that give the fixed number of lags of the variables in x.fixed.names. Can be NULL (default).
x.interaction.names	List of character vectors with names of the variables to be included as interaction terms (see Details). Can be NULL (default) if your model does not have interaction terms.
x.interaction.lags	List of numeric vectors with lags of the variables to be included as interaction terms. List and numeric vectors should have the same length as the ones in x.interaction.names. Can be NULL (default) if your model does not have interaction terms.
last.obs	Index number of the last observation to be considered.
use.intercept	If use.intercept == "both" (default), the function returns all possible model equations with and without intercept. If use.intercept == "without", then the function returns all possible right-hand side equations without intercept. If use.intercept == "with", then only the right-hand side equations with intercept are returned.
error.measure	Error measure to be used when calculating the in-sample prediction errors.
betas.selection	If betas.selection == "last", the estimated coefficients from the last rolling sample will be used to obtain the out-of-sample forecasts. If betas.selection == "average", then the average of the coefficients from all rolling samples will be used. If betas.selection == "both", then two out-of-sample forecasts will be estimated (one with betas.selection == "last" and another with betas.selection == "average").
use.parallel	If parallel computing should be used. Default is FALSE.
num.cores	Number of cores to use if parallel computing is used. If use.parallel == TRUE, then the default is detectCores() - 1. For more details, see detectCores.
...	Further arguments passed to glm.

Details

If y.max.lags equals to a number, then all lags of y.name up to this number (and starting at 0) will be included in the list of variables to enter the right-hand side of the model equations. For example, if y.max.lags = 2, then Y_t, Y_t-1, Y_t-2 will be included in the list of variables to enter the right-hand side of the equation.

Value

An object of class "gears". The function summary is used to obtain and print a summary of the results, while the function plot produces a plot of the forecasts and prediction intervals. An object of class "gears" is a list containing the following elements:

out_sample_point_forecasts

If betas.selection != "both", the output is a ts object containing the out-of-sample point forecasts obtained from the best model. Otherwise, it is a list with two ts objects, each containing the out-of-sample point forecasts for the two cases. The first one is for when betas.selection == "last", and the second one is for when betas.selection == "average".

lower

If betas.selection != "both", the output is a ts object containing the lower limits for prediction intervals. Otherwise, it is a list with two ts objects, each containing the the lower limits for the two cases. The first one is for when betas.selection == "last", and the second one is for when betas.selection == "average".

upper

If betas.selection != "both", the output is a ts object containing the upper limits for prediction intervals. Otherwise, it is a list with two ts objects, each containing the the upper limits for the two cases. The first one is for when betas.selection == "last", and the second one is for when betas.selection == "average".

x

A ts object with the original time series. If DATA is a data.frame, it returns the dependent variable as a ts object.

x.fitted

A ts object of length = number.rs with the in-sample predictions.

total_models

The total number of models evaluated by the function.

total_equations_estimated

The total number of equations estimated by the function. It is the value of total_models times the number of rolling samples (number.rs) and the forecast horizon (forecast.horizon).

betas

The beta.selection used.

error_measure

The error.measure used.

min_prediction_errors

A matrix object with two columns - one for the forecast lead number, and the other for the values of the minimum prediction error for the given measure -, and number of rows equal to number.rs.

mse_out_sample_prediction

A matrix object with two columns - one for the forecast lead number, and the other for the values of the MSE for the best model -, and number of rows equal to number.rs.

details

A list containing information about the best fitted model for each forecast lead. If details == FALSE, the list contains information on the best equation estimated for that particular forecast lead, and its associated in-sample predictions (for all rolling samples) and their associated prediction errors. If details == TRUE, it also includes all the information from the glm fit for each forecast lead.

model

A list with the model call used in this function.

Author(s)

Gustavo Varela-Alvarenga

Examples

# Univariate Time Series Forecasting - Data of class 'ts'.
gears(
  DATA                = datasets::WWWusage,
  forecast.horizon    = 12,
  size.rs             = 20,
  number.rs           = 10,
  level               = 95,
  details             = FALSE,
  glm.family          = "quasi",
  y.name              = NULL,
  y.max.lags          = 2,
  x.names             = NULL,
  x.max.lags          = NULL,
  x.fixed.names       = NULL,
  x.fixed.lags        = NULL,
  x.interaction.names = NULL,
  x.interaction.lags  = NULL,
  last.obs            = length(datasets::WWWusage),
  use.intercept       = "both",
  error.measure       = "mse",
  betas.selection     = "last"
)

# Using Parallel Computing - Univariate Time Series Forecasting - Data of
# class 'ts'.
gears:::gears(
  DATA                = datasets::WWWusage,
  forecast.horizon    = 10,
  size.rs             = 20,
  number.rs           = 12,
  glm.family          = "quasi",
  y.max.lags          = 2,
  error.measure       = "mse",
  betas.selection     = "last",
  use.parallel        = TRUE,
  num.cores           = 2
)

# Univariate Time Series Forecasting - Data from a data frame.
gears(
  DATA                = gears::commodities_prices,
  forecast.horizon    = 5,
  size.rs             = 20,
  number.rs           = 12,
  level               = 95,
  details             = FALSE,
  glm.family          = "quasi",
  y.name              = "PORK_PRICE",
  y.max.lags          = 2,
  x.names             = NULL,
  x.max.lags          = NULL,
  x.fixed.names       = NULL,
  x.fixed.lags        = NULL,
  x.interaction.names = NULL,
  x.interaction.lags  = NULL,
  last.obs            = 100,
  use.intercept       = "both",
  error.measure       = "mse",
  betas.selection     = "last"
)

# Multivariate Time Series Forecasting
gears(
  DATA                = gears::commodities_prices,
  forecast.horizon    = 1,
  size.rs             = 12,
  number.rs           = 5,
  level               = 95,
  details             = FALSE,
  glm.family          = "quasi",
  y.name              = "PORK_PRICE" ,
  y.max.lags          = 1,
  x.names             = list("BEEF_PRICE", "WHEAT_PRICE"),
  x.max.lags          = list(2, 1),
  x.fixed.names       = NULL,
  x.fixed.lags        = NULL,
  x.interaction.names = NULL,
  x.interaction.lags  = NULL,
  last.obs            = 150,
  use.intercept       = "both",
  error.measure       = "mse" ,
  betas.selection     = "last"
)

# Multivariate Time Series Forecasting - With Interactions
gears(
  DATA                = gears::commodities_prices,
  forecast.horizon    = 1,
  size.rs             = 25,
  number.rs           = 5,
  level               = 95,
  details             = FALSE,
  glm.family          = "quasi",
  y.name              = "PORK_PRICE",
  y.max.lags          = 1,
  x.names             = list("BEEF_PRICE"),
  x.max.lags          = list(2),
  x.fixed.names       = list("CORN_PRICE", "POULTRY_PRICE"),
  x.fixed.lags        = list(4, 5),
  x.interaction.names = list("CORN_PRICE*CORN_PRICE", "WHEAT_PRICE*BEEF_PRICE"),
  x.interaction.lags  = list(c(1, 1), c(2,3)),
  last.obs            = 150,
  use.intercept       = "without",
  error.measure       = "mse",
  betas.selection     = "last"
)

gu-stat/gears documentation built on Oct. 20, 2021, 2:53 a.m.