collapse = TRUE,
  comment = "#>",

There are three well-known notions of "boxes" in modelling: 1. White box - the model that is completely transparent and does not have any randomness. One can see how the inputs are transformed into the specific outputs. 2. Black box - the model which does not have an apparent structure. One can only observe inputs and outputs but does not know what happens inside. 3. Grey box - the model that is in between the first two. We observe inputs and outputs plus have some information about the structure of the model, but there is still a part of unknown.

The white boxes are usually used in optimisations (e.g. linear programming), while black boxes are popular in machine learning. As for the grey box models, they are more often used in analysis and forecasting. So the package greybox contains models that are used for these purposes.

At the moment the package contains advanced linear model function and several basic functions that implement model selection and combinations using information criteria (IC). You won't find statistical tests in this package - there's plenty of them in the other packages. Here we try using the modern techniques and methods that do not rely on hypothesis testing. This is the main philosophical point of greybox.

Main functions

The package includes the following functions for models construction:

  1. alm() - Advanced Linear Model. This is something similar to GLM, but with a focus on forecasting and the information criteria usage for time series. It also supports mixture distribution models for the intermittent data.
  2. stepwise() - select the linear model with the lowest IC from all the possible in the provided data. Uses partial correlations. Works fast;
  3. lmCombine() - combine the linear models into one using IC weights;
  4. lmDynamic() - produce model with dynamic weights and time varying parameters based on IC weight.

See discussion of some of these functions in this vignette below.

Models evaluation functions

  1. ro() - produce forecasts with a specified function using rolling origin.
  2. measures() - function, returning a bunch of error measures for the provided forecast and the holdout sample.
  3. rmcb() - regression on ranks of forecasting methods. This is a fast alternative to the classical nemenyi / MCB test.

Marketing analytics tools

  1. tableplot() - creates a plot for two categorical variables based on table function with frequencies inside.
  2. cramer() - Cramer's V value.
  3. mcor() - the multiple correlation coefficient.
  4. association() - the matrix of measures of association.
  5. spread() - function that plots scatter / boxplot / tableplot diagrams between variables depending on the their types.
  6. determination() - coefficients of determination for the set of explanatory variables.

All these functions are discussed in a separate vignette on marketing analytics tools.


The following methods can be applied to the models, produced by alm(), stepwise(), lmCombine() and lmDynamic(): 1. logLik() - extracts log-likelihood. 2. AIC(), AICc(), BIC(), BICc() - calculates the respective information criteria. 3. pointLik() - extracts the point likelihood. 4. pAIC(), pAICc(), pBIC(), pBICc() - calculates the respective point information criteria, based on pointLik. 5. actuals() - extracts the actual values of the response variable. 6. coef(), coefficients() - extract the parameters of the model. 7. confint() - extracts the confidence intervals for the parameters. 8. vcov() - extracts the variance-covariance matrix of the parameters. 9. sigma() - extracts the standard deviation of the residuals. 10. nobs() - the number of the in-sample observations of the model. 11. nparam() - the number of all the estimated parameters in the model. 12. summary() - produces the summary of the model. 13. predict() - produces the predictions based on the model and the provided newdata. If the newdata is not provided, then it uses the already available data in the model. Can also produce confidence and prediction intervals. 14. forecast() - acts similarly to predict() with few differences. It has a parameter h - forecast horizon - which is NULL by default and is set to be equal to the number of rows in newdata. However, if the newdata is not provided, then it will produce forecasts of the explanatory variables to the horizon h and use them as newdata. Finally, if h and newdata are provided, then the number of rows to use will be regulated by h. 15. plot() - produces several plots for the analysis of the residuals. This includes: Fitted over time, Standardised residuals vs Fitted, Absolute residuals vs Fitted, Q-Q plot with the specified distribution, Squared residuals vs Fitted, ACF of the residuals and PACF of the residuals, which is regulated by which parameter. See documentation for more info: ?plot.greybox.

Exogenous variables transformation tools

  1. xregExpander() - expand the provided data by including leads and lags of the variables.
  2. xregTransformer() - produce non-linear transformations of the provided data (logs, inverse etc).
  3. xregMultiplier() - produce cross-products of the variables in the provided matrix. Could be useful when exploring interaction effects of dummy variables.

See details on (1) below.

Distribution functions

  1. qlaplace(), dlaplace(), rlaplace(), plaplace() - functions for Laplace distribution.
  2. qalaplace(), dalaplace(), ralaplace(), palaplace() - functions for Asymmetric Laplace distribution.
  3. qs(), ds(), rs(), ps() - functions for S distribution.
  4. qfnorm(), dfnorm(), rfnorm(), pfnorm() - functions for folded normal distribution.
  5. qtplnorm(), dtplnorm(), rtplnorm(), ptplnorm() - functions for three parameter log normal distribution.
  6. qbcnorm(), dbcnorm(), rbcnorm(), pbcnorm() - functions for the Box-Cox normal distribution.

Additional functions

  1. graphmaker() - produces linear plots for the variable, its forecasts and fitted values.

The first two construct a model of a class lm, that could be used for the purposes of analysis or forecasting. The last one expands the exogenous variables to the matrix with lags and leads. Let's see how all of them work. Let's start from the end.



The function xregExpander() is useful in cases when the exogenous variable may influence the response variable either via some lags or leads. As an example, consider BJsales.lead series from the datasets package. Let's assume that the BJsales variable is driven by the today's value of the indicator, the value five and 10 days ago. This means that we need to produce lags of BJsales.lead. This can be done using xregExpander():

BJxreg <- xregExpander(BJsales.lead,lags=c(-5,-10))

The BJxreg is a matrix, which contains the original data, the data with the lag 5 and the data with the lag 10. However, if we just move the original data several observations ahead or backwards, we will have missing values in the beginning / end of series, so xregExpander() fills in those values with the forecasts using es() and iss() functions from smooth package (depending on the type of variable we are dealing with). This also means that in cases of binary variables you may have weird averaged values as forecasts (e.g. 0.7812), so beware and look at the produced matrix. Maybe in your case it makes sense to just substitute these weird numbers with zeroes...

You may also need leads instead of lags. This is regulated with the same lags parameter but with positive values:

BJxreg <- xregExpander(BJsales.lead,lags=c(7,-5,-10))

Once again, the values are shifted, and now the first 7 values are backcasted. In order to simplify things we can produce all the values from 10 lags till 10 leads, which returns the matrix with 21 variables:

BJxreg <- xregExpander(BJsales.lead,lags=c(-10:10))


The function stepwise() does the selection based on an information criterion (specified by user) and partial correlations. In order to run this function the response variable needs to be in the first column of the provided matrix. The idea of the function is simple, it works iteratively the following way:

  1. The basic model of the first variable and the constant is constructed (this corresponds to simple mean). An information criterion is calculated;
  2. The correlations of the residuals of the model with all the original exogenous variables are calculated;
  3. The regression model of the response variable and all the variables in the previous model plus the new most correlated variable from (2) is constructed using lm() function;
  4. An information criterion is calculated and is compared with the one from the previous model. If it is greater or equal to the previous one, then we stop and use the previous model. Otherwise we go to step 2.

This way we do not do a blind search, going forward or backwards, but we follow some sort of "trace" of a good model: if the residuals contain a significant part of variance that can be explained by one of the exogenous variables, then that variable is included in the model. Following partial correlations makes sure that we include only meaningful (from technical point of view) variables in the model. In general the function guarantees that you will have the model with the lowest information criterion. However this does not guarantee that you will end up with a meaningful model or with a model that produces the most accurate forecasts. So analyse what you get as a result.

Let’s see how the function works with the Box-Jenkins data. First we expand the data and form the matrix with all the variables:

BJxreg <-,lags=c(-10:10)))
BJxreg <- cbind(as.matrix(BJsales),BJxreg)
colnames(BJxreg)[1] <- "y"
ourModel <- stepwise(BJxreg)

This way we have a nice data frame with nice names, not something weird with strange long names. It is important to note that the response variable should be in the first column of the resulting matrix. After that we use stepwise function:

ourModel <- stepwise(BJxreg)

And here’s what it returns (the object of class lm):


The values in the function are listed in the order of most correlated with the response variable to the least correlated ones. The function works very fast because it does not need to go through all the variables and their combinations in the dataset.

All the basic methods can be used together with the final model (e.g. predict(), forecast(), summary() etc).


lmCombine() function creates a pool of linear models using lm(), writes down the parameters, standard errors and information criteria and then combines the models using IC weights. The resulting model is of the class "lm.combined". The speed of the function deteriorates exponentially with the increase of the number of variables $k$ in the dataset, because the number of combined models is equal to $2^k$. The advanced mechanism that uses stepwise() and removes a large chunk of redundant models is also implemented in the function and can be switched using bruteforce parameter.

Here's an example of the reduced data with combined model and the parameter bruteforce=TRUE:

ourModel <- lmCombine(BJxreg[,-c(3:7,18:22)],bruteforce=TRUE)

summary() function provides the table with the parameters, their standard errors, their relative importance and the 95% confidence intervals. Relative importance indicates in how many cases the variable was included in the model with high weight. So, in the example above variables xLag5, xLag4, xLag3 were included in the models with the highest weights, while all the others were in the models with lower ones. This may indicate that only these variables are needed for the purposes of analysis and forecasting.

The more realistic situation is when the number of variables is high. In the following example we use the data with 21 variables. So if we use brute force and estimate every model in the dataset, we will end up with $2^{21}$ = 2^21 combinations of models, which is not possible to estimate in the adequate time. That is why we use bruteforce=FALSE:

ourModel <- lmCombine(BJxreg,bruteforce=FALSE)

In this case first, the stepwise() function is used, which finds the best model in the pool. Then each variable that is not in the model is added to the model and then removed iteratively. IC, parameters values and standard errors are all written down for each of these expanded models. Finally, in a similar manner each variable is removed from the optimal model and then added back. As a result the pool of combined models becomes much smaller than it could be in case of the brute force, but it contains only meaningful models, that are close to the optimal. The rationale for this is that the marginal contribution of variables deteriorates with the increase of the number of parameters in case of the stepwise function, and the IC weights become close to each other around the optimal model. So, whenever the models are combined, there is a lot of redundant models with very low weights. By using the mechanism described above we remove those redundant models.

There are several methods for the lm.combined class, including:

  1. predict.greybox() - returns the point and interval predictions.
  2. forecast.greybox() - wrapper around predict() The forecast horizon is defined by the length of the provided sample of newdata.
  3. plot.lm.combined() - plots actuals and fitted values.
  4. plot.predict.greybox() - which uses graphmaker() function from smooth in order to produce graphs of actuals and forecasts.

As an example, let's split the whole sample with Box-Jenkins data into in-sample and the holdout:

BJInsample <- BJxreg[1:130,];
BJHoldout <- BJxreg[-(1:130),];
ourModel <- lmCombine(BJInsample,bruteforce=FALSE)

A summary and a plot of the model:


Importance tells us how important the respective variable is in the combination. 1 means 100% important, 0 means not important at all.

And the forecast using the holdout sample:

ourForecast <- predict(ourModel,BJHoldout)

These are the main functions implemented in the package for now. If you want to read more about IC model selection and combinations, I would recommend [@Burnham1998] textbook.


This function is based on the principles of lmCombine() and point ICs. It allows not only combining the models but also to capture the dynamics of it parameters. So in a way this corresponds to a time varying parameters model, but based on information criteria.

Continuing the example from lmCombine(), let's construct the dynamic model:

ourModel <- lmDynamic(BJInsample,bruteforce=FALSE)

We can plot the model and ask for the summary in the similar way as with lmCombine():

ourSummary <- summary(ourModel)

The coefficients in the summary are the averaged out over the whole sample. The more interesting elements are the time varying parameters, their standard errors (and respective confidence intervals) and time varying importance of the parameters.

# Coefficients in dynamics
# Standard errors of the coefficients in dynamics
# Importance of parameters in dynamics

The importance can also be plotted using plot() and coef() functions, which might produce a lot of images:


The plots show how the importance of each parameter changes over time. The values do not look as smooth as we would like them to, but nothing can be done with this at this point. If you want something smooth, then smooth these values out using, for example, cma() function from smooth package.

In fact, even degrees of freedom are now also time varying:


And as usual we can produce forecast from this function, the mean parameters are used in this case:

ourForecast <- predict(ourModel,BJHoldout)

This function is currently under development, so stay tuned.


Try the greybox package in your browser

Any scripts or data that you put into this service are public.

greybox documentation built on March 31, 2020, 5:09 p.m.