auto.vets {legion}

Vector ETS-PIC model

Description

Function constructs vector ETS model based on VETS-PIC taxonomy and returns forecast, fitted values, errors and matrix of states along with other useful variables.

Usage

auto.vets(data, model = "PPP", lags = c(frequency(data)),
  loss = c("likelihood", "diagonal", "trace"), ic = c("AICc", "AIC", "BIC",
  "BICc"), h = 10, holdout = FALSE, occurrence = c("none", "fixed",
  "logistic"), bounds = c("admissible", "usual", "none"), silent = TRUE,
  parallel = FALSE, ...)

vets(data, model = "PPP", lags = c(frequency(data)),
  parameters = c("level", "trend", "seasonal", "damped"),
  initials = c("seasonal"), components = c("none"),
  loss = c("likelihood", "diagonal", "trace"), ic = c("AICc", "AIC", "BIC",
  "BICc"), h = 10, holdout = FALSE, occurrence = c("none", "fixed",
  "logistic"), bounds = c("admissible", "usual", "none"), silent = TRUE,
  ...)

Arguments

data

The matrix with the data, where series are in columns and observations are in rows.

model

The type of ETS model. Can consist of 3 or 4 chars: ANN, AAN, AAdN, AAA, AAdA, MMdM etc. PPP means that the best pure model will be selected based on the chosen information criteria type. ATTENTION! ONLY PURE ADDITIVE AND PURE MULTIPLICATIVE MODELS ARE AVAILABLE! Pure multiplicative models are done as additive model applied to log(y).

Also model can accept a previously estimated VETS model and use all its parameters.

lags

The lags of the model. Needed for seasonal models.

loss

Type of Loss Function used in optimization. loss can be:

• "likelihood" - which implies the maximisation of likelihood of multivariate normal distribution (or log Normal if the multiplicative model is constructed);

• "diagonal" - similar to "likelihood", but assumes that covariances between the error terms are zero.

• "trace" - the trace of the covariance matrix of errors. The sum of variances is minimised in this case.

• Provided by user as a custom function of actual, fitted and B. Note that internally function transposes the data, so that actual and fitted contain observations in columns and series in rows.

An example of the latter option is: lossFunction <- function(actual,fitted,B){return(mean(abs(actual - fitted)))} followed by loss=lossFunction.

ic

The information criterion used in the model selection procedure.

h

Length of forecasting horizon.

holdout

If TRUE, holdout sample of size h is taken from the end of the data.

occurrence

Defines type of occurrence model used. Can be:

• none, meaning that the data should be considered as non-intermittent;

• fixed, taking into account constant Bernoulli distribution of demand occurrences;

• logistic, based on logistic regression.

In this case, the ETS model inside the occurrence part will correspond to model and probability="dependent". Alternatively, model estimated using oves function can be provided here.

bounds

What type of bounds to use in the model estimation. The first letter can be used instead of the whole word. "admissible" means that the model stability is ensured, while "usual" means that the all the parameters are restricted by the (0, 1) region.

silent

If silent="none", then nothing is silent, everything is printed out and drawn. silent="all" means that nothing is produced or drawn (except for warnings). In case of silent="graph", no graph is produced. If silent="legend", then legend of the graph is skipped. And finally silent="output" means that nothing is printed out in the console, but the graph is produced. silent also accepts TRUE and FALSE. In this case silent=TRUE is equivalent to silent="all", while silent=FALSE is equivalent to silent="none". The parameter also accepts first letter of words ("n", "a", "g", "l", "o").

parallel

If TRUE, the estimation of ADAM models is done in parallel (used in auto.adam only). If the number is provided (e.g. parallel=41), then the specified number of cores is set up. WARNING! Packages foreach and either doMC (Linux and Mac only) or doParallel are needed in order to run the function in parallel.

...

Other non-documented parameters. For example FI=TRUE will make the function also produce Fisher Information matrix, which then can be used to calculated variances of smoothing parameters and initial states of the model. The vector of initial parameter for the optimiser can be provided here as the variable B. The upper bound for the optimiser is provided via ub, while the lower one is lb. Also, the options for nloptr can be passed here:

• maxeval=40*k is the default number of iterations for both optimisers used in the function (k is the number of parameters to estimate).

• algorithm1="NLOPT_LN_BOBYQA" is the algorithm used in the first optimiser, while algorithm2="NLOPT_LN_NELDERMEAD" is the second one.

• xtol_rel1=1e-8 is the relative tolerance in the first optimiser, while xtol_rel2=1e-6 is for the second one. All of this can be amended and passed in ellipsis for finer tuning.

• print_level - the level of output for the optimiser (0 by default). If equal to 41, then the detailed results of the optimisation are returned.

parameters

The character vector, specifying, which of the parameters should be common between time series. This includes smoothing parameters for "level", "trend", "seasonal" components and "damped" trend parameter. If parameters="none", then all parameters are set to be individual. An example is the model with all parameters being common: parameters=c("level","trend","seasonal","damped"). The order is not important and the first letters can be used instead of the full words as well.

initials

The character vector, specifying, which of the initial values of components should be common. This can be "level", "trend" and / or "seasonal", setting initials of respective components to be common. This can also be "none", making the initials individual for all series. An example is the model with only seasonal initials being common: initials="seasonal". The order is not important, and the first letters can be used instead of the full words.

components

The character vector, specifying, which of the components components should be shared between time series. This can be "level", "trend" and / or "seasonal", setting respective components to be shared. This can also be "none", making them individual for all series. The order is not important, and the first letters can be used instead of the full words. Please, note that making components common automatically sets the respective initials common as well.

Details

Function estimates vector ETS in the form of the Single Source of Error state space model of the following type:

\mathbf{y}_{t} = \mathbf{o}_{t} (\mathbf{W} \mathbf{v}_{t-l} + \mathbf{x}_t \mathbf{a}_{t-1} + \mathbf{\epsilon}_{t})

\mathbf{v}_{t} = \mathbf{F} \mathbf{v}_{t-l} + \mathbf{G} \mathbf{\epsilon}_{t}

\mathbf{a}_{t} = \mathbf{F_{X}} \mathbf{a}_{t-1} + \mathbf{G_{X}} \mathbf{\epsilon}_{t} / \mathbf{x}_{t}

Where y_{t} is the vector of time series on observation t, o_{t} is the vector of Bernoulli distributed random variable (in case of normal data it becomes unit vector for all observations), \mathbf{v}_{t} is the matrix of states and l is the matrix of lags, \mathbf{x}_t is the vector of exogenous variables. \mathbf{W} is the measurement matrix, \mathbf{F} is the transition matrix and \mathbf{G} is the persistence matrix. Finally, \epsilon_{t} is the vector of error terms.

Conventionally we formulate values as:

\mathbf{y}'_t = (y_{1,t}, y_{2,t}, \dots, y_{m,t})

where m is the number of series in the group.

\mathbf{v}'_t = (v_{1,t}, v_{2,t}, \dots, v_{m,t})

where v_{i,t} is vector of components for i-th time series.

\mathbf{W}' = (w_{1}, \dots , 0; \vdots , \ddots , \vdots; 0 , \vdots , w_{m})

is matrix of measurement vectors.

The main idea of the function is in imposing restrictions on parameters / initials / components of the model in order to capture the common dynamics between series.

In case of multiplicative model, instead of the vector y_t we use its logarithms. As a result the multiplicative model is much easier to work with.

For some more information about the model and its implementation, see the vignette: vignette("vets","legion")

Value

Object of class "legion" is returned. It contains the following list of values:

• model - The name of the fitted model;

• timeElapsed - The time elapsed for the construction of the model;

• states - The matrix of states with components in columns and time in rows;

• persistence - The persistence matrix;

• transition - The transition matrix;

• measurement - The measurement matrix;

• phi - The damping parameter value;

• B - The vector of all the estimated coefficients;

• lagsAll - The vector of the internal lags used in the model;

• nParam - The number of estimated parameters;

• occurrence - The occurrence model estimated with VETS;

• data - The matrix with the original data;

• fitted - The matrix of the fitted values;

• holdout - The matrix with the holdout values (if holdout=TRUE in the estimation);

• residuals - The matrix of the residuals of the model;

• Sigma - The covariance matrix of the errors (estimated with the correction for the number of degrees of freedom);

• forecast - The matrix of point forecasts;

• ICs - The values of the information criteria;

• logLik - The log-likelihood function;

• lossValue - The value of the loss function;

• loss - The type of the used loss function;

• lossFunction - The loss function if the custom was used in the process;

• accuracy - the values of the error measures. Currently not available.

• FI - Fisher information if user asked for it using FI=TRUE.

Author(s)

Ivan Svetunkov, [e-mail]

References

• de Silva A., Hyndman R.J. and Snyder, R.D. (2010). The vector innovations structural time series framework: a simple approach to multivariate forecasting. Statistical Modelling, 10 (4), pp.353-374

• Hyndman, R.J., Koehler, A.B., Ord, J.K., and Snyder, R.D. (2008) Forecasting with exponential smoothing: the state space approach, Springer-Verlag.

• Lütkepohl, H. (2005). New Introduction to Multiple Time Series Analysis. New introduction to Multiple Time Series Analysis. Berlin, Heidelberg: Springer Berlin Heidelberg. doi:10.1007/978-3-540-27752-1

• Chen H., Svetunkov I., Boylan J. (2021). A New Taxonomy for Vector Exponential Smoothing and Its Application to Seasonal Time Series.

See Also

ves, es, adam

Examples

Y <- ts(cbind(rnorm(100,100,10),rnorm(100,75,8)),frequency=12)

# The simplest model applied to the data with the default values
vets(Y,model="ANN",h=10,holdout=TRUE)

# Multiplicative damped trend model with common parameters
# and initial seasonal indices
vets(Y,model="MMdM",h=10,holdout=TRUE,parameters=c("l","t","s","d"),
     initials="seasonal")

# Automatic selection of ETS components
vets(Y, model="PPP", h=10, holdout=TRUE, initials="seasonal")