Package 'bvartools'

Description

A generic function used to add dummy variables to the deterministic terms of a model.

Usage

add_dummy_variables(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_dummy_variables.bvarmodel, add_dummy_variables.bvecmodel, add_dummy_variables.expandingwindow, add_dummy_variables.modellist.

Description

Adds dummy variables to the deterministic terms of a model: impulse dummies for single unusual periods, step dummies for level shifts, or any other series that is known in advance.

Usage

## S3 method for class 'bvarmodel'
add_dummy_variables(object, impulse = NULL, step = NULL, data = NULL, ...)

## S3 method for class 'bvecmodel'
add_dummy_variables(object, impulse = NULL, step = NULL, data = NULL, ...)

## S3 method for class 'expandingwindow'
add_dummy_variables(object, impulse = NULL, step = NULL, data = NULL, ...)

## S3 method for class 'modellist'
add_dummy_variables(object, ...)

Arguments

Details

A dummy variable takes up what a model otherwise has no explanation for: an impulse dummy the one period of a strike, a tax change or a pandemic, a step dummy a lasting shift in the level of the series, such as a change in how they are measured. Without one, a single extreme observation pulls the coefficients of every equation towards itself and inflates the estimated error variance for the whole sample.

The dummies are deterministic terms like the constant. They are appended to the end of the deterministic terms of the regressors, named after their type and period – impulse.2020Q2, step.2008M09 – or after the columns of data, and their coefficients take the prior of the deterministic terms, v_i_det in add_priors. The coefficient of an impulse dummy is estimated from a single observation, so its prior matters more than that of the constant: a tight one leaves most of the observation to the other coefficients, which is what the dummy was meant to prevent.

The function has to be called before add_priors, since it changes the number of coefficients the priors are given for. A dummy variable that is zero in every period of the estimation sample, or that the other regressors already span – a step dummy that is one in every period is the constant again – is refused.

A forecast continues the dummies by their definition: an impulse dummy is zero after its period and a step dummy stays one. The series in data are continued with the values they were given, so for a forecast they have to reach the last forecast period, or all deterministic terms of the forecast have to be given in argument deterministic of add_forecast_input.

Of a list of models of class 'expandingwindow', each window gets the dummies whose periods it reaches and leaves out the rest: a forecast made at the end of a window that ends before a period could not have known about what happened in it. use_expanding_window applied to a model with dummy variables does the same.

In a VEC model the dummies enter the equations of the differences, not the cointegration term. An impulse dummy there shifts the level of the series for good, since a one-off change in a difference is a lasting change in the level. A one-off blip in the level is a dummy that is one in its period and minus one in the next, which can be given in data. vec_to_var carries the dummies into the VAR representation.

Value

The object in object with the dummy variables added to data$train$x and its SUR form data$train$z, to data$original$deterministic and to the names in model$deterministic, model$n increased by their number, and model$dummy_variables, a data frame with one row per dummy variable giving its name, its type ("impulse", "step" or "data") and the time of its period, which is what a forecast continues it by.

See Also

Other model set-up: add_initial_values.bvarmodel(), add_initial_values.bvecmodel(), add_prior_options(), add_priors.bvarmodel(), add_priors.bvecmodel(), aggregation_weights(), combine_models(), create_bvarmodel(), create_bvecmodel(), transform_variables(), use_expanding_window.bvarmodel(), use_expanding_window.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# An impulse dummy for the first quarter of 1975 and a step dummy from 1979
model <- add_dummy_variables(model, impulse = c(1975, 1), step = c(1979, 1))
model[["model"]][["deterministic"]]

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

Description

Generic function used to calculate forecast errors and add them to a model object.

Usage

add_forecast_errors(object, test_sample = NULL, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_forecast_errors.bvarmodel, add_forecast_errors.expandingwindow, add_forecast_errors.modellist.

Description

Calculates forecast errors and adds them to an object of class 'bvarmodel'.

Usage

## S3 method for class 'bvarmodel'
add_forecast_errors(object, test_sample = NULL, ...)

Arguments

Value

The object in object with posterior$forecast$errors added, a mcmc object with one row per draw and $Kh$ columns in the order of posterior$forecast$forecasts, which it is stored beside. selection_criteria summarises them.

See Also

bvartools_model describes the object this returns, element by element.

Other model comparison: add_forecast_errors.bvecmodel(), add_predictive_loglik(), add_predictive_loglik.bvarmodel(), add_predictive_loglik.bvecmodel(), aggregate_forecasts(), align_model_obs.modellist(), analysis_of_stored_models, choose_best_model.selcritlist(), create_external_forecast(), folder_steps, map_draws(), map_models(), open_model(), open_models(), plot_forecast_errors_by_period(), pool_forecasts(), selection_criteria.bvarmodel(), selection_criteria.bvecmodel(), selection_criteria.default(), selection_criteria.modellist()

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

# Add forecast errors
model <- add_forecast_errors(model, test_sample = orig)

Description

Calculates the forecast errors of a VEC model against a test sample, in levels.

Usage

## S3 method for class 'bvecmodel'
add_forecast_errors(object, test_sample = NULL, ...)

Arguments

Details

The forecasts of a VEC model are of the levels, so the errors are taken against the levels of test_sample, exactly as for the VAR representation vec_to_var would give.

Value

The object in object with posterior$forecast$errors added, as described in add_forecast_errors.bvarmodel.

See Also

Other model comparison: add_forecast_errors.bvarmodel(), add_predictive_loglik(), add_predictive_loglik.bvarmodel(), add_predictive_loglik.bvecmodel(), aggregate_forecasts(), align_model_obs.modellist(), analysis_of_stored_models, choose_best_model.selcritlist(), create_external_forecast(), folder_steps, map_draws(), map_models(), open_model(), open_models(), plot_forecast_errors_by_period(), pool_forecasts(), selection_criteria.bvarmodel(), selection_criteria.bvecmodel(), selection_criteria.default(), selection_criteria.modellist()

Description

Calculates and adds forecast errors for a list of Bayesian models.

Usage

## S3 method for class 'expandingwindow'
add_forecast_errors(object, test_sample = NULL, ...)

Arguments

Value

The object in object with forecast errors added to each of its models, as described in add_forecast_errors.bvarmodel.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

model <- use_expanding_window(model, start = 1982.25)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

# Add forecast errors
model <- add_forecast_errors(model, test_sample = orig)

Description

Calculates and adds forecast errors for a list of Bayesian models.

Usage

## S3 method for class 'modellist'
add_forecast_errors(object, test_sample = NULL, ...)

Arguments

Value

The object in object with forecast errors added to each of its models, as described in add_forecast_errors.bvarmodel.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 0:2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

# Add forecast errors
model <- add_forecast_errors(model, test_sample = orig)

Description

Generic function used to generate and add data matrices for forecast simulation to a model object.

Usage

add_forecast_input(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_forecast_input.bvarmodel, add_forecast_input.bvecmodel, add_forecast_input.expandingwindow, add_forecast_input.externalforecast, add_forecast_input.modellist.

Description

Generates and adds data matrices for forecast simulation to the elements of an object of class 'bvarmodel'.

Usage

## S3 method for class 'bvarmodel'
add_forecast_input(
  object,
  n_ahead = 10,
  deterministic = NULL,
  exogen = NULL,
  ...
)

Arguments

Value

The object in object with model$h set to n_ahead and data$forecast$x added, the regressors of the forecast periods in the layout of data$train$x, one row per period.

See Also

Other posterior simulation: add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

Description

Prepares the input data of the forecast periods of a VEC model.

Usage

## S3 method for class 'bvecmodel'
add_forecast_input(
  object,
  n_ahead = 10,
  deterministic = NULL,
  exogen = NULL,
  ...
)

Arguments

Details

A VEC model is forecast in levels: it is the same model as its VAR representation, and the forecast of the differences follows from that of the levels. The regressors of the forecast periods are therefore those of the VAR in levels, and are assembled from the data and specification that vec_to_var builds. The posterior draws are not converted.

Value

The object in object with the forecast horizon in model$h and the regressors of the forecast periods, in levels, in data$forecast$x.

See Also

Other posterior simulation: add_forecast_input.bvarmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Description

Generates and adds data matrices for forecast simulation to the elements of an object of class 'expandingwindow'.

Usage

## S3 method for class 'expandingwindow'
add_forecast_input(object, ...)

Arguments

Value

The object in object with forecast input added to each of its models, as described in add_forecast_input.bvarmodel.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

model <- use_expanding_window(model, start = 1982.25)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

Description

Generates and adds data matrices for forecast simulation to the elements of an object of class 'modellist'.

Usage

## S3 method for class 'modellist'
add_forecast_input(object, ...)

Arguments

Value

The object in object with forecast input added to each of its models, as described in add_forecast_input.bvarmodel.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 0:2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

Description

A generic function used to generate initial values of an MCMC chain. The function invokes particular methods which depend on the class of the first argument.

Usage

add_initial_values(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_initial_values.bvarmodel, add_initial_values.bvecmodel, add_initial_values.expandingwindow, add_initial_values.externalforecast, add_initial_values.modellist.

Description

Adds initial values to a VAR model.

Usage

## S3 method for class 'bvarmodel'
add_initial_values(object, method = "ols", ...)

Arguments

Details

For argument method the following specifications are possible:

"ols"

Inital values are equal to estimates from an unrestricted LS regression.

"prior"

Initial values are drawn from the prior. Not possible for uninformative priors.

In case method = "ols", the initial draw of $a$ is the result of the unrestricted LS regression $(Z^{\prime}Z)^{-1}Z^{\prime}y$ of the model $y_{t} = Z_{t} a + u_{t}$, where $Z$ is the matrix of regressors in SUR form and $y$ is the vector of endogenous variables.

The initial draw of $\Sigma^u$ is the sum of squared residuals divided by the number of observations, i.e. $\frac{uu^{\prime}}{T}$, with $u$ as the residuals of the LS regression.

In case of a model with time varying parameters (TVP), the initial states are obtained using the approach specified in argument method. The precisions of the state equations start at the means of their gamma priors in case method = "ols" and are drawn from those priors in case method = "prior". So method = "ols" uses no random numbers, and a seed set after add_initial_values fixes the posterior draws.

Value

The object in object with the element initial added, a list of starting values with

a

the coefficients, an $M \times 1$ matrix, or $TM \times 1$ for TVP models, whose initial states and state precisions are held in a_init and a_sigma_inv.

u_sigma_inv

for error = "wishart", the $K \times K$ inverse error covariance matrix.

u_omega_inv

for gamma priors, the $K \times K$ diagonal matrix of error precisions.

h, h_init

for stochastic volatility, the $T \times K$ log-volatilities and their initial states.

psi

for "gamma+covar" and "sv+covar", the error covariance coefficients.

a_lambda

with variable selection, the inclusion indicators.

u_scale, w

for error = "ald", the $K \times 1$ scales and the $T \times K$ latent weights of the asymmetric Laplace distribution.

Elements that do not apply to a model are absent.

Seed

The function also stores the seed of the posterior simulation as element seed of object$model, unless the model has one already. It is drawn from R's random number generator, so set.seed() before this call makes it reproducible. add_seed replaces it.

See Also

Other model set-up: add_dummy_variables.bvarmodel(), add_initial_values.bvecmodel(), add_prior_options(), add_priors.bvarmodel(), add_priors.bvecmodel(), aggregation_weights(), combine_models(), create_bvarmodel(), create_bvecmodel(), transform_variables(), use_expanding_window.bvarmodel(), use_expanding_window.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 50, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add prior specifications
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

Description

Adds initial values to a VEC model, which was produced by function create_bvecmodel in combination with add_priors.

Usage

## S3 method for class 'bvecmodel'
add_initial_values(object, method = "maxlik", ...)

Arguments

Details

For argument method the following specifications are possible:

"maxlik"

Inital values are equal to estimates from maximum likelihood regressions.

"prior"

Initial values are drawn from the prior. Not possible for uninformative priors.

In case method = "maxlik", the initial draw of $a$ is the result of a maximum likelihood estimation of the reduced rank model. When used with a Wishart prior, the initial draw of $\Sigma^u$ is the sum of squared residuals of ML regression divided by the number of observations, i.e. $\frac{uu^{\prime}}{T}$. In all other cases, the diagonal elements of $\Sigma^u$ are set to the variances of the variables in $u$.

In case method = "prior", all initial draws in the model are random draws from the respective prior distributions.

In case of a model with time varying parameters (TVP), the initial states are obtained using the approach specified in argument method. The precisions of the state equations start at the means of their gamma priors in case method = "maxlik" and are drawn from those priors in case method = "prior". The autocorrelation coefficient rho of the state equation of $\beta$ is taken from the prior specification, whether it is held there or drawn from the prior on it that coint$rho_min and coint$rho_max set up.

Value

The object in object with the element initial added, a list with the starting values beta of the cointegration coefficients, a $K_\beta r \times 1$ matrix, or $T K_\beta r \times 1$ with initial state beta_init for time varying cointegration, and the starting values of the remaining coefficients and the error term with the elements described in add_initial_values.bvarmodel.

Seed

The function also stores the seed of the posterior simulation as element seed of object$model, unless the model has one already. It is drawn from R's random number generator, so set.seed() before this call makes it reproducible. add_seed replaces it.

See Also

Other model set-up: add_dummy_variables.bvarmodel(), add_initial_values.bvarmodel(), add_prior_options(), add_priors.bvarmodel(), add_priors.bvecmodel(), aggregation_weights(), combine_models(), create_bvarmodel(), create_bvecmodel(), transform_variables(), use_expanding_window.bvarmodel(), use_expanding_window.bvecmodel()

Examples

# Load data 
data("e6")
e6 <- e6 * 100

# Generate model
model <- create_bvecmodel(e6, p = 4, r = 1,
                          const = "unrestricted",
                          seasonal = "unrestricted",
                          iterations = 10, burnin = 10)
# Chosen number of iterations and burn-in should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    coint = list(v_i = 0, p_tau_i = 1),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

Description

Adds initial values to a list of models by passing each element to the respective method.

Usage

## S3 method for class 'expandingwindow'
add_initial_values(object, ...)

Arguments

Value

The object in object with initial values added to each of its models, as described in add_initial_values.bvarmodel.

Examples

data("us_macrodata")

# Starting period of the forecasting exercise
start_period <- 2007

# AR(1) models as benchmark
model <- create_bvarmodel(data = us_macrodata, p = 1,
                          deterministic = "none",
                          error = "gamma",
                          iterations = 10, burnin = 10)
# Chosen number of iterations and burn-in draws should be much higher.

# Obtain objects for expanding window estimation
model <- use_expanding_window(model, start = start_period)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(shape = 3, rate = 1))

# Add initial values
model <- add_initial_values(model)

Description

Adds initial values to a list of models by passing each element to the respective method.

Usage

## S3 method for class 'modellist'
add_initial_values(object, ...)

Arguments

Value

The object in object with initial values added to each of its models, as described in add_initial_values.bvarmodel.

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 0:2, deterministic = "const",
                          iterations = 10, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add prior specifications
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

Description

Generic function used for posterior simulation of model coefficients.

Usage

add_posterior_coefficients(object, ...)

Arguments

Details

Before the method is called, the size the object will have once its draws are complete is compared with options(bvartools.size_warning), and a warning is given if it is larger. See expected_model_size.

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_posterior_coefficients.bvarmodel, add_posterior_coefficients.bvecmodel, add_posterior_coefficients.expandingwindow, add_posterior_coefficients.externalforecast, add_posterior_coefficients.modellist.

Description

Forwards model input to posterior simulation functions for vector autoregressive models.

Usage

## S3 method for class 'bvarmodel'
add_posterior_coefficients(
  object,
  posterior_function = NULL,
  chains = NULL,
  ...
)

Arguments

Details

Unless posterior_function is specified, the function forwards the model input to the package's own posterior functions.

The internal samplers draw with the seed in object$model$seed, which add_initial_values sets and add_seed replaces. R's random number generator is set to that seed, with R's default kinds, for the simulation and put back as it was afterwards. A call of set.seed() between add_initial_values() and this function therefore does not change the draws. A model without a seed draws from R's generator as it stands. A posterior_function is called as it is and decides itself what to do with the seed; see bayests_posterior.

A sampler that cannot run raises its error rather than returning something. The message names what about the input it could not work with. Applied to a list of models – a 'modellist', an 'expandingwindow' or, in bgvars, a 'gvarmodel' – that ends the run on the first specification that fails, rather than leaving that one without a posterior and carrying it into whatever reads the results.

Value

The object in object with the element posterior added. Each of its elements is a list whose element coeffs holds the draws after burn-in as a mcmc object with one row per draw and one column per parameter:

a

the coefficients, $M$ columns or $TM$ for TVP models, in the order of the columns of data$train$z with the contemporaneous coefficients of structural models last. With variable selection element lambda holds the inclusion indicators, and for TVP models element sigma the state variances.

u_sigma_inv

the inverse error covariance matrix, $K^2$ columns, or $TK^2$ if the error variances vary over time.

u_omega_inv

for all errors but "wishart", the error precisions, $K$ columns or $TK$.

psi

for "gamma+covar" and "sv+covar", the error covariance coefficients.

u_scale

for error = "ald", the $K$ scales of the asymmetric Laplace distribution.

y

for a model estimated from a panel not observed whole, the completed panel, $TK$ columns ordered by period, and constraints_inv the error precisions of its soft constraints. See create_bvarmodel.

mu

under a steady-state prior, the $K$ unconditional means. Under an adaptive prior, a holds the scales of its groups in element shrinkage and, for the horseshoe and the normal-gamma prior, the scales of its coefficients in local; where the normal-gamma prior draws $\theta$, its draws are in theta. See add_prior_options.

Elements that do not apply to a model are absent or NULL. Note that bvar expects draws in the transposed orientation.

See Also

bvartools_model describes the object this returns, element by element.

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

Description

Forwards model input to posterior simulation functions for vector error correction models.

Usage

## S3 method for class 'bvecmodel'
add_posterior_coefficients(
  object,
  posterior_function = NULL,
  chains = NULL,
  ...
)

Arguments

Details

The function implements commonly used posterior simulation algorithms for Bayesian VAR models with both constant and time varying parameters (TVP) as well as stochastic volatility. It can produce posterior draws for standard BVAR models with independent normal-Wishart priors, which can be augmented by stochastic search variable selection (SSVS) as proposed by Geroge et al. (2008) or Bayesian variable selection (BVS) as proposed in Korobilis (2013). Both SSVS or BVS can also be applied to the covariances of the error term.

The implementation follows the descriptions in Chan et al. (2019), George et al. (2008) and Korobilis (2013). For all approaches the SUR form of a VAR model is used to obtain posterior draws. The algorithm is implemented in C++ to reduce calculation time.

The function also supports structural BVEC models, where the structural coefficients are estimated from contemporary endogenous variables, which corresponds to the so-called (A-model). Currently, only specifications are supported, where the structural matrix contains ones on its diagonal and all lower triangular elements are freely estimated. Since posterior draws are obtained based on the SUR form of the VEC model, the structural coefficients are drawn jointly with the other coefficients.

The internal samplers draw with the seed in object$model$seed, which add_initial_values sets and add_seed replaces. R's random number generator is set to that seed, with R's default kinds, for the simulation and put back as it was afterwards. A call of set.seed() between add_initial_values() and this function therefore does not change the draws. A model without a seed draws from R's generator as it stands. A posterior_function is called as it is and decides itself what to do with the seed; see bayests_posterior.

A sampler that cannot run raises its error rather than returning something. The message names what about the input it could not work with. Applied to a list of models – a 'modellist', an 'expandingwindow' or, in bgvars, a 'gvecmodel' – that ends the run on the first specification that fails, rather than leaving that one without a posterior and carrying it into whatever reads the results.

Value

The object in object with the element posterior added, whose elements hold the draws after burn-in as mcmc objects with one row per draw and one column per parameter, in element coeffs: beta, the cointegration coefficients, $K_\beta r$ columns or $T K_\beta r$ for time varying cointegration, a, the loadings and the remaining coefficients, and the draws of the error term as described in add_posterior_coefficients.bvarmodel.

References

Chan, J., Koop, G., Poirier, D. J., & Tobias J. L. (2019). Bayesian econometric methods (2nd ed.). Cambridge: Cambridge University Press.

George, E. I., Sun, D., & Ni, S. (2008). Bayesian stochastic search for VAR model restrictions. Journal of Econometrics, 142(1), 553–580. doi:10.1016/j.jeconom.2007.08.017

Koop, G., León-González, R., & Strachan R. W. (2010). Efficient posterior simulation for cointegrated models with priors on the cointegration space. Econometric Reviews, 29(2), 224–242. doi:10.1080/07474930903382208

Korobilis, D. (2013). VAR forecasting using Bayesian variable selection. Journal of Applied Econometrics, 28(2), 204–230. doi:10.1002/jae.1271

See Also

bvartools_model describes the object this returns, element by element.

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data 
data("e6")
e6 <- e6 * 100

# Generate model
model <- create_bvecmodel(e6, p = 1, r = 1, const = "restricted",
                          iterations = 10, burnin = 10)
# Chosen number of iterations and burn-in should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    coint = list(v_i = 0, p_tau_i = 1),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

Description

Forwards model input to posterior simulation functions.

Usage

## S3 method for class 'expandingwindow'
add_posterior_coefficients(object, ..., cores = 1)

Arguments

Value

The object in object with posterior draws added to each of its models, as described in add_posterior_coefficients.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 10, burnin = 2)
# Number of iterations and burnin should be much higher.

model <- use_expanding_window(model, start = 1982.25)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

Description

Forwards model input to posterior simulation functions.

Usage

## S3 method for class 'modellist'
add_posterior_coefficients(object, ..., cores = 1)

Arguments

Value

The object in object with posterior draws added to each of its models, as described in add_posterior_coefficients.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data 
data("e1")
e1 <- diff(log(e1)) * 100

# Generate model
model <- create_bvarmodel(e1, p = 1:2, deterministic = 2,
                          iterations = 20, burnin = 10)
# Chosen number of iterations and burn-in should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws
model <- add_posterior_coefficients(model)


# The same on two worker processes
model <- add_posterior_coefficients(model, cores = 2)

Description

Generic function that calculates and adds forecasts.

Usage

add_posterior_forecasts(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_posterior_forecasts.bvarmodel, add_posterior_forecasts.expandingwindow, add_posterior_forecasts.externalforecast, add_posterior_forecasts.modellist.

Description

Calculates and adds forecasts to an object of class 'bvarmodel'.

Usage

## S3 method for class 'bvarmodel'
add_posterior_forecasts(
  object,
  forecast_states = NULL,
  scenario = NULL,
  forecast_quantile = NULL,
  ...
)

Arguments

Value

The object in object with posterior$forecast$forecasts added, a mcmc object with one row per draw and $Kh$ columns, stacked by period: the $K$ variables of the first forecast period, then those of the second, and so on. posterior$forecast is the group everything the forecast periods produce hangs below, the errors of add_forecast_errors beside these. predict summarises them. A forecast_states that was given is stored in model$forecast_states.

Simulating the volatility forward needs the variance of the log-volatility innovations, posterior$u_sigma_inv$sigma, which add_posterior_coefficients stores. A stochastic volatility model fitted with an earlier version of the package lacks it and stops with an error unless forecast_states = "hold".

References

Chavleishvili, S., & Manganelli, S. (2019). Forecasting and stress testing with quantile vector autoregression. ECB Working Paper, 2330.

See Also

bvartools_model describes the object this returns, element by element.

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

Description

Simulates forecasts of a VEC model, in levels, from its posterior draws.

Usage

## S3 method for class 'bvecmodel'
add_posterior_forecasts(object, forecast_states = NULL, ...)

Arguments

Details

The forecasts are those of the VAR in levels the VEC model implies. For a model with constant coefficients they are the forecasts vec_to_var followed by add_posterior_forecasts.bvarmodel gives. For a model with time varying coefficients they are not: its VAR representation has no state equation of its own and holds its coefficients at the last period, while this method steps the states of the VEC model and converts them to levels anew in every forecast period.

Simulating the cointegration vectors forward depends on the units of the data. A step $\eta_t$ of their state equation moves the error correction term by $\eta_t^{\prime} w_t$, which for series far from zero – log levels times 100, say – is of the order of their levels rather than of their variation: the random walk intercept described in section 'Prior on the cointegration space' of cointspace_prior, carried forward with nothing in the data to restrain it. The forecast is then mostly that drift, and its intervals widen accordingly. A warning names the series in the error correction term that are more than 50 times their standard deviation per period away from zero at the end of the sample; forecast_states = "hold" is the alternative. Series near zero, such as interest rates and inflation in percent, do not draw it.

A time varying model estimated on series that scale_error_correction centred or scaled cannot be simulated forward and stops with an error unless forecast_states = "hold": the state equation of its cointegration vectors belongs to the transformed series, while rescale_error_correction has put the vectors back on the scale of the data and moved the means into the constant of the last sample period only.

Simulating the volatility forward needs posterior$u_sigma_inv$sigma, the variance of the log-volatility innovations, which add_posterior_coefficients stores. A model with stochastic volatility estimated with an earlier version of the package lacks it and stops with an error unless forecast_states = "hold".

Value

The object in object with posterior$forecast$forecasts added, a mcmc object with one row per draw and $Kh$ columns of forecasts of the levels, stacked by period. predict summarises them. A forecast_states that was given is stored in model$forecast_states.

See Also

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_loglik.bvarmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Description

Calculates and adds forecasts to the elements of an object of class 'expandingwindow'.

Usage

## S3 method for class 'expandingwindow'
add_posterior_forecasts(object, ..., cores = 1)

Arguments

Value

The object in object with forecast draws added to each of its models, as described in add_posterior_forecasts.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 10, burnin = 2)
# Number of iterations and burnin should be much higher.

model <- use_expanding_window(model, start = 1982.25)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

Description

Calculates and adds forecasts to the elements of an object of class 'modellist'.

Usage

## S3 method for class 'modellist'
add_posterior_forecasts(object, ..., cores = 1)

Arguments

Value

The object in object with forecast draws added to each of its models, as described in add_posterior_forecasts.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 0:2, deterministic = "const",
                          iterations = 10, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add forecasts
model <- add_posterior_forecasts(model)

Description

Generic function that calculates the posterior log-likelihoods of a model.

Usage

add_posterior_loglik(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_posterior_loglik.bvarmodel, add_posterior_loglik.bvecmodel, add_posterior_loglik.expandingwindow, add_posterior_loglik.externalforecast, add_posterior_loglik.modellist.

Description

Calculates and adds posterior log-likelihoods to an object of class 'bvarmodel'.

Usage

## S3 method for class 'bvarmodel'
add_posterior_loglik(object, ...)

Arguments

Value

The object in object with posterior$loglik added, a mcmc object with one row per draw and one column per period of the training sample, holding the pointwise log-likelihood that selection_criteria uses.

See Also

bvartools_model describes the object this returns, element by element.

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvecmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
object <- add_posterior_coefficients(model)

# Add log-likelihoods
object <- add_posterior_loglik(object)

Description

Calculates and adds posterior log-likelihoods to an object of class 'bvecmodel'.

Usage

## S3 method for class 'bvecmodel'
add_posterior_loglik(object, ...)

Arguments

Value

The object in object with posterior$loglik added, a mcmc object with one row per draw and one column per period of the training sample, holding the pointwise log-likelihood that selection_criteria uses.

See Also

Other posterior simulation: add_forecast_input.bvarmodel(), add_forecast_input.bvecmodel(), add_posterior_coefficients.bvarmodel(), add_posterior_coefficients.bvecmodel(), add_posterior_forecasts.bvarmodel(), add_posterior_forecasts.bvecmodel(), add_posterior_loglik.bvarmodel(), add_seed(), bayests_files(), bayests_posterior(), bvar(), bvec(), chain_diagnostics(), predict.bvecmodel()

Examples

# Load data
data("e6")

# Create model
model <- create_bvecmodel(e6, p = 4, r = 1,
                          const = "unrestricted",
                          seasonal = "unrestricted",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    coint = list(v_i = 0, p_tau_i = 1),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add log-likelihoods
model <- add_posterior_loglik(model)

Description

Forwards its elements to methods used to calculate posterior log-likelihoods.

Usage

## S3 method for class 'expandingwindow'
add_posterior_loglik(object, ..., cores = 1)

Arguments

Value

The object in object with log-likelihood draws added to each of its models, as described in add_posterior_loglik.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1982, 2))


# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 10, burnin = 10)
# Number of iterations and burnin should be much higher.

model <- use_expanding_window(model, start = 1982.25)

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws 
model <- add_posterior_coefficients(model)

# Add data used for forecast calculation
model <- add_forecast_input(model, n_ahead = 4)

# Add log-likelihoods
model <- add_posterior_loglik(model)

Description

Forwards its elements to methods used to calculate posterior log-likelihoods.

Usage

## S3 method for class 'modellist'
add_posterior_loglik(object, ..., cores = 1)

Arguments

Value

The object in object with log-likelihood draws added to each of its models, as described in add_posterior_loglik.bvarmodel.

Parallel simulation

With cores above 1 the models are simulated on a cluster of that many worker processes, started with makeCluster and stopped when the call returns, but on no more workers than there are models. Nested lists, such as the 'modellist' of 'expandingwindow' lists that use_expanding_window returns for several specifications, are shared out model by model.

Each worker runs with a single BLAS thread: the function sets OPENBLAS_NUM_THREADS, OMP_NUM_THREADS, MKL_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1 while the workers start, whatever this session has set, and puts them back afterwards. An optimised BLAS would otherwise start one thread per core in every worker, and the samplers do not become faster with more threads. The thread count of this session is not changed.

The workers use the library paths of this session and load the installed version of the package, together with every package that provides a method the models of the list need – dfmtools for its dynamic factor models, for example. A function passed as posterior_function, such as the one bayests_posterior returns, is sent to the workers along with the variables of the environment it was created in, and must not rely on anything else of this session.

Coefficient draws do not depend on the number of workers. Every model is simulated with its own seed, see add_seed, and a model without one is given one from R's random number generator before it is sent off. The draws equal those of a simulation on one core in a session whose BLAS runs on one thread, as R's reference BLAS always does. An optimised BLAS such as OpenBLAS rounds some results differently in the last digits on one thread than on several, and a Markov chain carries such a difference forward, so a session running it on several threads gets different draws from the same posterior. Draws that are not seeded per model, such as those of add_posterior_forecasts, come from independent random number streams of the workers, set up with clusterSetRNGStream from R's generator. They are reproduced by set.seed for a given number of workers, but differ from those of a simulation on one core.

Starting the workers takes a moment, so a cluster pays off for lists of models that take longer than that to simulate.

Examples

# Load data 
data("e1")
e1 <- diff(log(e1)) * 100

# Generate model
model <- create_bvarmodel(e1, p = 1:2, deterministic = 2,
                          iterations = 10, burnin = 10)
# Chosen number of iterations and burn-in should be much higher.

# Add priors
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

# Add initial values
model <- add_initial_values(model)

# Obtain posterior draws
object <- add_posterior_coefficients(model)

# Add log-likelihoods
object <- add_posterior_loglik(object)

Description

Adds the draws of the one-step-ahead log predictive density to the windows of an expanding window exercise, which selection_criteria sums to the log predictive likelihood.

Usage

add_predictive_loglik(object, ...)

## S3 method for class 'expandingwindow'
add_predictive_loglik(object, ...)

## S3 method for class 'modellist'
add_predictive_loglik(object, ...)

Arguments

Details

The windows of an expanding window exercise grow by one period at a time, so window $i + 1$ holds exactly one observation that window $i$ has not seen. For every window but the last, the function evaluates the density of that observation, $\Delta y_{t}$, given the regressors of period $t$, at each posterior draw of the window, and stores the draws in element predictive of the window, together with the period $t$. The log of their mean is the log predictive density $\ln p(\Delta y_t | y_{t-1}, \ldots, y_1)$, and its sum over the windows is the log predictive likelihood of Geweke and Amisano (2011), which Koop, León-González and Strachan (2011) use to choose between time varying cointegration models and their ranks.

A draw of a model with constant coefficients and a constant error covariance describes period $t$ as it describes the sample. Everything that follows a state equation is carried one period forward with that equation first:

• time varying coefficients by one step of their random walk with the drawn state variance, and a coefficient that variable selection excluded stays at zero;

• a time varying cointegration space by $\beta_t = \rho (I_r \otimes P_\tau) \beta_{t-1} + \eta_t$, $\eta_t \sim N(0, I)$, with the drawn $\rho$ or the one of the prior, where $P_\tau$ is the identity unless the prior centres the space;

• time varying error covariances by one step of their random walk;

• stochastic volatilities by one step of the random walk of the log variances. Its state variance is taken from posterior$u_sigma_inv$sigma if the sampler stored it, and is otherwise drawn from its conditional posterior given the drawn path of the log variances and the prior in priors$u_sigma.

Unlike the pointwise log-likelihood of add_posterior_loglik, whose states have seen the observation they are evaluated at, the predictive density conditions only on the data before period $t$. This is what makes it the criterion for models whose coefficients or variances follow a state equation, where leave-one-out importance sampling fails for exactly the periods a path bends towards.

The function is available for VEC models, which includes the rank zero models in differences that ranks are compared with, and for VAR models, whose regressors are the lags of the endogenous variables, the exogenous variables and the deterministic terms of the period that is predicted. A VAR model is the case of a VEC model without an error correction term, so the density is the same expression with the cointegration block left out. The windows of a VEC model must have been simulated on error correction terms that are neither scaled nor centred, or put back with rescale_error_correction first, and structural models are not supported.

The windows need not share their regressors. use_expanding_window leaves an impulse, step or data dummy of add_dummy_variables out of the windows that end before its event, so the window just before the event has fewer regressors than the observation the next window adds. The density of that observation uses only the regressors of the window that predicts it: the regressors of the observation are matched to the ones of the window by name, and a dummy the window does not have is left out, because a forecast made at the end of the window could not have known about the event. The event period is therefore scored as an ordinary forecast, and the dummy only enters the densities of the windows that contain its event. This applies to VAR and VEC models alike.

The expression is the normal density of the observation, so the function is available for the algorithms whose observation is normal given the parameters of a draw, and refuses the others. The asymmetric Laplace algorithms of quantile estimation, "VarNormalAld" and "VarTvpAld", are refused: the precision their samplers store is the one of the normal that their scale mixture conditions on period by period, not the density of an observation, whose mixing variable would have to be integrated out.

The methods for a single fitted model, add_predictive_loglik.bvarmodel and add_predictive_loglik.bvecmodel, score a forecast against the observations its horizon realised instead. That is the same statistic over a different set of periods – one step ahead densities, each conditioning on the realised history before it – and it is BayesTS that computes it rather than the R code here. It is stored in posterior$forecast$loglik, beside the forecasts it scores, rather than in predictive.

Value

The object in object, with element predictive added to every window but the last. It is a list with loglik, the draws of the log predictive density, and period, the time of the predicted observation.

References

Geweke, J., & Amisano, G. (2011). Hierarchical Markov normal mixture models with applications to financial asset returns. Journal of Applied Econometrics, 26(1), 1–29. doi:10.1002/jae.1119

Koop, G., León-González, R., & Strachan, R. W. (2011). Bayesian inference in a time varying cointegration model. Journal of Econometrics, 165(2), 210–220. doi:10.1016/j.jeconom.2011.07.007

See Also

Methods for a single fitted model: add_predictive_loglik.bvarmodel, add_predictive_loglik.bvecmodel.

Other model comparison: add_forecast_errors.bvarmodel(), add_forecast_errors.bvecmodel(), add_predictive_loglik.bvarmodel(), add_predictive_loglik.bvecmodel(), aggregate_forecasts(), align_model_obs.modellist(), analysis_of_stored_models, choose_best_model.selcritlist(), create_external_forecast(), folder_steps, map_draws(), map_models(), open_model(), open_models(), plot_forecast_errors_by_period(), pool_forecasts(), selection_criteria.bvarmodel(), selection_criteria.bvecmodel(), selection_criteria.default(), selection_criteria.modellist()

Examples

# Load data
data("e6")
e6 <- e6 * 100

# Create model
model <- create_bvecmodel(e6, p = 2, r = 1, const = "unrestricted",
                          iterations = 20, burnin = 10)
# Number of iterations and burn-in should be much higher.

model <- add_priors(model,
                    coef = list(v_i = 0, v_i_det = 0),
                    coint = list(v_i = 0, p_tau_i = 1),
                    sigma = list(df = "k", scale = 0.0001))

# Estimate the model on the last four expanding windows
model <- use_expanding_window(model, start = c(1998, 1))
model <- add_initial_values(model)
model <- add_posterior_coefficients(model)

# One-step-ahead log predictive densities
model <- add_predictive_loglik(model)

# The log predictive likelihood is criterion "LPL"
selection_criteria(model)

Description

Scores the forecast of an object of class 'bvarmodel' against the observations its horizon realised.

Usage

## S3 method for class 'bvarmodel'
add_predictive_loglik(object, test_sample = NULL, ...)

Arguments

Details

The draws of the log predictive density of period $T + i$ are stored in posterior$forecast$loglik, one row per draw and one column per scored period, beside the paths in posterior$forecast$forecasts that they score. The numbers are BayesTS's own: this method fills data$test$y and hands the object to the same C++ that computes the score when the bayests programme is run on a model file.

Each column conditions on the observations the periods before it realised, not on the path the forecast simulated. The log of the mean of the draws of a column is therefore the one step ahead predictive density given everything known up to that period, and those sum over the columns to $\ln p(y_{T+1}, \ldots, y_{T+h} | y_{1}, \ldots, y_{T})$, the log predictive likelihood of the whole realised stretch, which selection_criteria reports as LPL. Scoring against a simulated history instead would give the marginal density of each period on its own, which is a different quantity and one whose columns could not be added up.

With the history realised rather than simulated, the regressors of the scored periods do not depend on the draw. The score is then the model's own pointwise log-likelihood over those periods – the same expression as add_posterior_loglik evaluates, over a different sample – so nothing is written down twice and the two cannot drift apart. What still moves with the draw is everything that follows a state equation: time varying coefficients, time varying error covariances and stochastic volatilities take one step of their random walk per scored period, in the order and subject to the same model$forecast_states that add_posterior_forecasts steps them in. Under "simulate" those steps are drawn, so the score is drawn too and two runs give two answers, exactly as two runs of a forecast do.

Fewer realised periods than the horizon is not an error. The periods that are there are the ones that can be scored, and the rest of the forecast is left alone. A test_sample that does not reach the forecast at all leaves the object unchanged, which is what a model estimated to the end of a series looks like.

Structural models are refused: their regressors include the contemporaneous observations, so the realised row is not built from its lags alone, and their density carries the Jacobian of $A_0$ besides. So are the asymmetric Laplace algorithms of quantile estimation, which do not forecast in the first place.

Value

The object in object with posterior$forecast$loglik added, a mcmc object with one row per draw and one column per scored period, and with the values it was scored against in data$test$y.

See Also

bvartools_model describes the object this returns, element by element.

Other model comparison: add_forecast_errors.bvarmodel(), add_forecast_errors.bvecmodel(), add_predictive_loglik(), add_predictive_loglik.bvecmodel(), aggregate_forecasts(), align_model_obs.modellist(), analysis_of_stored_models, choose_best_model.selcritlist(), create_external_forecast(), folder_steps, map_draws(), map_models(), open_model(), open_models(), plot_forecast_errors_by_period(), pool_forecasts(), selection_criteria.bvarmodel(), selection_criteria.bvecmodel(), selection_criteria.default(), selection_criteria.modellist()

Examples

# Load data
data("e1")
orig <- diff(log(e1)) * 100
train <- window(orig, end = c(1978, 4))

# Create model
model <- create_bvarmodel(data = train, p = 2, deterministic = "const",
                          iterations = 20, burnin = 10)
# Number of iterations and burnin should be much higher.

model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

model <- add_initial_values(model)
model <- add_posterior_coefficients(model)

# Forecast the four periods that were held back
model <- add_forecast_input(model, n_ahead = 4)
model <- add_posterior_forecasts(model)

# Score them against what those periods realised
model <- add_predictive_loglik(model, test_sample = orig)
dim(model[["posterior"]][["forecast"]][["loglik"]])

# The log predictive likelihood is criterion "LPL"
selection_criteria(model)[["LPL"]]

Description

Scores the forecast of an object of class 'bvecmodel' against the levels its horizon realised.

Usage

## S3 method for class 'bvecmodel'
add_predictive_loglik(object, test_sample = NULL, ...)

Arguments

Details

The forecasts of a VEC model are of the levels, so the score is of the levels too, and it is taken in the VAR representation vec_to_var would give: every draw is converted to its level VAR coefficients and the realised row is evaluated against the lags of the realised rows before it. That is the same route add_forecast_errors.bvecmodel takes and the same one the forecast itself took, so the three describe one model rather than three.

Everything else is as add_predictive_loglik.bvarmodel describes it, including what each column conditions on and how a cointegration space or a volatility that moves with time is carried across the horizon. A model whose error correction term was scaled or centred has to be put back with rescale_error_correction first, since the score is taken against the levels themselves.

Value

The object in object with posterior$forecast$loglik added, a mcmc object with one row per draw and one column per scored period, and with the levels it was scored against in data$test$y.

See Also

bvartools_model describes the object this returns, element by element.

Other model comparison: add_forecast_errors.bvarmodel(), add_forecast_errors.bvecmodel(), add_predictive_loglik(), add_predictive_loglik.bvarmodel(), aggregate_forecasts(), align_model_obs.modellist(), analysis_of_stored_models, choose_best_model.selcritlist(), create_external_forecast(), folder_steps, map_draws(), map_models(), open_model(), open_models(), plot_forecast_errors_by_period(), pool_forecasts(), selection_criteria.bvarmodel(), selection_criteria.bvecmodel(), selection_criteria.default(), selection_criteria.modellist()

Examples

# Load data
data("e6")
e6 <- e6 * 100
train <- window(e6, end = c(1997, 4))

# Create model
model <- create_bvecmodel(train, p = 2, r = 1, const = "unrestricted",
                          iterations = 20, burnin = 10)
# Number of iterations and burn-in should be much higher.

model <- add_priors(model,
                    coef = list(v_i = 0, v_i_det = 0),
                    coint = list(v_i = 0, p_tau_i = 1),
                    sigma = list(df = "k", scale = 0.0001))

model <- add_initial_values(model)
model <- add_posterior_coefficients(model)

# Forecast the periods that were held back and score them
model <- add_forecast_input(model, n_ahead = 4)
model <- add_posterior_forecasts(model)
model <- add_predictive_loglik(model, test_sample = e6)

dim(model[["posterior"]][["forecast"]][["loglik"]])

Description

Adds the options of the prior that act on top of the one add_priors sets: hyperparameters estimated from the data, a restriction of the coefficients to a stationary model, a prior on the unconditional mean in place of one on the intercept, and the prior of the error of soft constraints.

Usage

add_prior_options(
  object,
  shrinkage = "none",
  stationary = FALSE,
  steady_state = NULL,
  constraints = NULL
)

Arguments

Details

Argument shrinkage lets the data decide how tightly the prior of add_priors shrinks the coefficients of the lagged endogenous variables. Their prior variances are multiplied by scales that are drawn with the coefficients:

• "minnesota": one scale per group of coefficients with an inverse gamma prior of shape and rate, the hierarchical Minnesota prior of Chan (2021). By default own lags form group 1 and the lags of the other variables group 2, with shape = 3 and rate = 2, a prior mean of one: the prior of add_priors is the centre of the one estimated.

• "horseshoe": the horseshoe prior of Carvalho, Polson and Scott (2010), a half-Cauchy scale per group and one per coefficient, drawn as in Makalic and Schmidt (2016). By default all lags form one group.

• "normal_gamma": the normal-gamma prior of Griffin and Brown (2010) as Huber and Feldkircher (2019) put it on a VAR. Each coefficient's scale $\psi_j$ has a gamma prior of shape theta and rate $\theta \lambda_g / 2$, and each group's $\lambda_g$ a gamma prior of shape and rate. By default the lags of order $l$ form group $l$, with theta = 0.1 and shape = rate = 0.01. theta is held fixed; the smaller it is, the more the prior pushes small coefficients to zero while leaving large ones alone. Give theta_rate instead to draw $\theta$ under an exponential prior of that rate, by a Metropolis-Hastings step tuned during the burn-in, as Huber and Feldkircher (2019) do; the draws come back as posterior$a$theta, and the chain needs a burn-in to tune the step.

Coefficients in group 0 – by default the deterministic terms and the exogenous variables – keep the prior of add_priors. A group of one's own has one element per coefficient, in the order of the columns of data$train$z. The prior must be diagonal wherever it shrinks.

Argument stationary redraws a draw of the coefficients that is not stationary up to 100 times, and keeps the previous draw if none of them is, which leaves the posterior restricted to the stationary region invariant.

Argument steady_state puts the prior on the unconditional mean $\mu$ of the endogenous variables rather than on the intercept, which is $(I - \sum_i A_i) \mu$ in every draw, following Villani (2009). A prior belief about the level a series returns to is more often available than one about an intercept. The model must have lags and an intercept and nothing else, and cannot be combined with shrinkage. The draws of $\mu$ come back as posterior$mu.

The three are available for models with constant coefficients and error = "wishart", "gamma", "gamma+covar", "sv" or "sv+covar", without variable selection or a structural form.

Value

The object in object with model$shrinkage, model$stationary and model$steady_state set where they apply, and the priors in priors$a$shrinkage, priors$mu and priors$constraints.

References

Carvalho, C. M., Polson, N. G., & Scott, J. G. (2010). The horseshoe estimator for sparse signals. Biometrika, 97(2), 465–480. doi:10.1093/biomet/asq017

Griffin, J. E., & Brown, P. J. (2010). Inference with normal-gamma prior distributions in regression problems. Bayesian Analysis, 5(1), 171–188. doi:10.1214/10-BA507

Huber, F., & Feldkircher, M. (2019). Adaptive shrinkage in Bayesian vector autoregressive models. Journal of Business & Economic Statistics, 37(1), 27–39. doi:10.1080/07350015.2016.1256217

Chan, J. C. C. (2021). Minnesota-type adaptive hierarchical priors for large Bayesian VARs. International Journal of Forecasting, 37(3), 1212–1226. doi:10.1016/j.ijforecast.2021.01.002

Makalic, E., & Schmidt, D. F. (2016). A simple sampler for the horseshoe estimator. IEEE Signal Processing Letters, 23(1), 179–182. doi:10.1109/LSP.2015.2503725

Villani, M. (2009). Steady-state priors for vector autoregressions. Journal of Applied Econometrics, 24(4), 630–650. doi:10.1002/jae.1065

See Also

Other model set-up: add_dummy_variables.bvarmodel(), add_initial_values.bvarmodel(), add_initial_values.bvecmodel(), add_priors.bvarmodel(), add_priors.bvecmodel(), aggregation_weights(), combine_models(), create_bvarmodel(), create_bvecmodel(), transform_variables(), use_expanding_window.bvarmodel(), use_expanding_window.bvecmodel()

Examples

data("e1")
e1 <- diff(log(e1)) * 100

model <- create_bvarmodel(e1, p = 2, iterations = 20, burnin = 10)
model <- add_priors(model, coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))
model <- add_prior_options(model, shrinkage = "minnesota", stationary = TRUE)
model <- add_initial_values(model)
model <- add_posterior_coefficients(model)

Description

A generic function used to generate prior vectors and matrices. The function invokes particular methods which depend on the class of the first argument.

Usage

add_priors(object, ...)

Arguments

Value

The value returned by the method for the class of object, as described on the pages of the methods.

See Also

Methods: add_priors.bvarmodel, add_priors.bvecmodel, add_priors.expandingwindow, add_priors.externalforecast, add_priors.modellist.

Description

Adds prior specifications to a BVAR model, which was produced by function create_bvarmodel.

Usage

## S3 method for class 'bvarmodel'
add_priors(object, coef, sigma, varsel = NULL, ...)

Arguments

Details

None of the arguments coef, sigma and varsel provides default hyperparameters: every value that a model needs must be given in the list it belongs to. A missing required element raises an error, as does an element that is not listed below.

Argument coef can contain the following elements:

v_i

a non-negative numeric specifying the prior precision of the coefficients, where 0 gives an uninformative prior. Required unless minnesota is given. It is also required together with minnesota if error is "gamma+covar" or "sv+covar", where it sets the prior precision of the error covariance coefficients. The precisions of the other coefficients are taken from minnesota if it is given, and from varsel for SSVS.

v_i_det

a numeric specifying the prior precision of coefficients corresponding to deterministic terms. If it is not given, v_i is used. Not used if minnesota is given or SSVS is applied.

coint_var

a logical specifying whether the prior mean of the first own lag of an endogenous variable should be set to 1, which is commonly used for cointegrated VAR models. Default is FALSE. Ignored, with a warning, under SSVS, which centres the prior of every coefficient it selects at zero; BVS keeps the prior mean.

const

a numeric or character specifying the prior mean of coefficients, which correspond to the intercept. If a numeric is provided, all prior means are set to this value. If coef$const = "mean", the mean of the respective endogenous variable is used as prior mean. If coef$const = "first", the first values of the respective endogenous variable is used as prior mean. This can be useful for trend estimation when using a TVP model.

minnesota

a named list containing the parameters for the calculation of the Minnesota prior. It must contain kappa1, kappa2 and kappa4, and kappa3 if the model has exogenous variables. For the endogenous variable $i$ the prior variance of the $l$th lag of regressor $j$ is obtained as

$\frac{\kappa_{1}}{l^2} \textrm{ for own lags of endogenous variables,}$

$\frac{\kappa_{1} \kappa_{2}}{l^2} \frac{\sigma_{i}^2}{\sigma_{j}^2} \textrm{ for endogenous variables other than own lags,}$

$\frac{\kappa_{1} \kappa_{3}}{(l+1)^2} \frac{\sigma_{i}^2}{\sigma_{j}^2} \textrm{ for exogenous variables,}$

$\kappa_{1} \kappa_{4} \sigma_{i}^2 \textrm{ for deterministic terms,}$

where $\sigma_{i}$ is the residual standard deviation of variable $i$ of an unrestricted LS estimate. For exogenous variables $\sigma_{i}$ is the sample standard deviation. If the model does not contain exogenous variables, kappa3 will be ignored.

max_var

a positive numeric specifying the maximum prior variance of the coefficients of non-deterministic variables in the Minnesota prior. Larger prior variances are set to this value. Only used if minnesota is given.

shape

a numeric specifying the shape of the gamma prior on the precisions, the inverse error variances, of the state equation, whose mean is shape / rate. Required for models with time varying parameters unless omega_v is given, and not used otherwise.

rate

a numeric specifying the rate of the gamma prior on the precisions of the state equation. Required together with shape.

rate_det

a numeric specifying the prior rate parameter of the error variances of the state equation for coefficients, which correspond to deterministic terms. If it is not given, rate is used. Only used for models with time varying parameters.

omega_v

a positive numeric, in place of shape and rate: the variance of a normal prior on the signed standard deviation $\omega$ of the state innovations, $\omega \sim N(0, V_\omega)$, which is also the prior mean of the state variance $\omega^2$. This is the non-centred parameterisation of Frühwirth-Schnatter and Wagner (2010), which makes a constant coefficient an interior point of the prior and lets the posterior carry the Savage-Dickey test for time variation of Chan (2018); see Details. It applies to the covariance coefficients as well. Only for models with time varying parameters, tvp = TRUE, whatever their error.

Argument sigma must contain the elements that belong to the error of the model:

• "wishart": df and scale. Not available for structural models.

• "gamma" and "gamma+covar": shape and rate.

• "sv" and "sv+covar": mu, v_i, shape, rate, state_variance and offset; with tvp = TRUE, omega_v may take the place of shape and rate.

• "ald": shape and rate.

The elements are

df

a positive integer, or a character expression in k, the number of endogenous variables, such as "k" or "k + 3", specifying the prior degrees of freedom of the inverse Wishart prior.

scale

a positive numeric specifying the prior error variance of the endogenous variables in the inverse Wishart prior.

shape

for "gamma" and "gamma+covar" a non-negative numeric, or a character expression in k as for df, specifying the shape of the gamma prior on the error precisions, the inverse error variances, whose mean is shape / rate. For "ald" a positive numeric specifying the shape of the inverse gamma prior on the scale of the asymmetric Laplace distribution. For both either one value or one per endogenous variable. For models with stochastic volatility a numeric specifying the shape of the gamma prior on the precision of the state equation of the log-volatilities.

rate

a positive numeric specifying the rate that corresponds to shape, for "gamma", "gamma+covar" and "ald" either one value or one per endogenous variable.

mu

numeric of the prior mean of the initial state of the log-volatilities. Only used for models with time varying volatility.

v_i

numeric of the prior precision of the initial state of the log-volatilities. Only used for models with time varying volatility.

state_variance

numeric of the initial draw for the variance of the log-volatilities. Only used for models with time varying volatility.

offset

numeric of the constant, which is added before taking the log of the squared errors. Only used for models with time varying volatility.

omega_v

a positive numeric, in place of shape and rate: the variance of a normal prior on the signed standard deviation of the log-volatility innovations, as coef$omega_v is for the coefficients. Only for models with time varying parameters and stochastic volatility.

Under omega_v a random walk $x_t = x_{t-1} + v_t$, $v_t \sim N(0, \omega^2)$, is estimated as $x_t = x_0 + \omega \tilde{x}_t$ with $\tilde{x}_t$ a standard random walk. The hypothesis that $x_t$ does not move is then $\omega = 0$, a point inside the prior, and its Bayes factor is the Savage-Dickey density ratio $p(\omega = 0) / p(\omega = 0 | y)$, which a single run of the time varying model estimates (Chan 2018). Each block of the posterior estimated this way holds, beside sigma, the draws of $\omega$ in omega, and the log density at zero of its conditional posterior, per state in omega_log_zero and for the whole block in omega_log_zero_joint. The log Bayes factor in favour of time variation in state $i$ is $\log N(0; 0, V_{\omega, i})$ less the log of the average over the draws of exp(omega_log_zero[, i]). The joint one compares "every state of the block moves" with "none does" rather than "at least one moves". Each block chooses its prior for itself, so the volatilities can be tested while the coefficients keep shape and rate. For structural models only a gamma prior or stochastic volatility specification is allowed.

Argument varsel can contain the following elements:

inprior

a numeric between 0 and 1 specifying the prior probability of a variable to be included in the model.

covar

logical indicating if the variable selection algorithm should also be applied to the error covariance matrix.

exclude_det

logical indicating if deterministic terms should be excluded from the variable selection algorithm.

minnesota

a numeric vector of length 4 containing parameters for the calculation of the Minnesota-like inclusion priors. See below.

tau

a numeric vector of two elements containing the prior standard errors of restricted variables ($\tau_0$) as its first element and unrestricted variables ($\tau_1$) as its second. Only used for SSVS.

semiautomatic

an numeric vector of two elements containing the factors by which the standard errors associated with an unconstrained least squares estimate of the model are multiplied to obtain the prior standard errors of restricted ($\tau_0$) and unrestricted ($\tau_1$) variables, respectively. This is the semiautomatic approach described in George et al. (2008). Only used for SSVS.

In the case of SSVS, either tau or semiautomatic must be specified.

If varsel$minnesota is specified, prior inclusion probabilities are calculated in a Minnesota-like fashion as

for lag $l$ with $\kappa_1$, $\kappa_2$, $\kappa_3$, $\kappa_4$ as the first, second, third and forth element in varsel$minnesota, respectively.

Value

The object in object with the element priors added, a list with

a

the prior of the coefficients: type, the $M \times 1$ prior means mu and the $M \times M$ prior precision matrix v_inv, where $M$ is the number of coefficients. With variable selection also inprior and include, for SSVS tau0 and tau1, and for TVP models shape and rate of the state variances, or omega_v.

psi

for error = "gamma+covar" or "sv+covar", the prior of the error covariance coefficients with type, mu, v_inv and varsel, and the variable selection and state variance elements as for a.

u_sigma

the prior of the error variances with its type: "wishart" with df and scale, "gamma" with shape and rate, or "sv" with mu, v_inv, shape, rate (or omega_v), sigma and offset. With a Minnesota prior it also holds u_sigma_inv, the inverse error covariance matrix the prior was scaled with. Not present for error = "ald".

u_scale

for error = "ald", the prior of the scales of the asymmetric Laplace distribution with type, shape and rate.

References

Chan, J. C. C. (2018). Specification tests for time-varying parameter models with stochastic volatility. Econometric Reviews, 37(8), 807–823. doi:10.1080/07474938.2016.1167948

Chan, J., Koop, G., Poirier, D. J., & Tobias J. L. (2019). Bayesian econometric methods (2nd ed.). Cambridge: Cambridge University Press.

Frühwirth-Schnatter, S., & Wagner, H. (2010). Stochastic model specification search for Gaussian and partial non-Gaussian state space models. Journal of Econometrics, 154(1), 85–100. doi:10.1016/j.jeconom.2009.07.003

George, E. I., Sun, D., & Ni, S. (2008). Bayesian stochastic search for VAR model restrictions. Journal of Econometrics, 142(1), 553–580. doi:10.1016/j.jeconom.2007.08.017

Korobilis, D. (2013). VAR forecasting using Bayesian variable selection. Journal of Applied Econometrics, 28(2), 204–230. doi:10.1002/jae.1271

Lütkepohl, H. (2006). New introduction to multiple time series analysis (2nd ed.). Berlin: Springer.

See Also

Other model set-up: add_dummy_variables.bvarmodel(), add_initial_values.bvarmodel(), add_initial_values.bvecmodel(), add_prior_options(), add_priors.bvecmodel(), aggregation_weights(), combine_models(), create_bvarmodel(), create_bvecmodel(), transform_variables(), use_expanding_window.bvarmodel(), use_expanding_window.bvecmodel()

Examples

# Load data
data("e1")
e1 <- diff(log(e1)) * 100

# Create model
model <- create_bvarmodel(e1, p = 2, deterministic = "const",
                          iterations = 10, burnin = 10)
# Number of iterations and burn-in should be much higher.

# Add prior specifications
model <- add_priors(model,
                    coef = list(v_i = 1, v_i_det = 1 / 10),
                    sigma = list(df = "k", scale = 1))

Description

Adds prior specifications to a list of models, which was produced by function create_bvecmodel.

Usage

## S3 method for class 'bvecmodel'
add_priors(object, coef, coint = NULL, sigma, varsel = NULL, ...)

Arguments

Details

None of the arguments coef, coint, sigma and varsel provides default hyperparameters: every value that a model needs must be given in the list it belongs to. A missing required element raises an error, as does an element that is not listed below.

Argument coef can contain the following elements:

v_i

a non-negative numeric specifying the prior precision of the coefficients, where 0 gives an uninformative prior. Required unless minnesota is given. It is also required together with minnesota if error is "gamma+covar" or "sv+covar". The precisions of the other coefficients are taken from minnesota if it is given, and from varsel for SSVS.

v_i_det

a numeric specifying the prior precision of coefficients corresponding to deterministic terms. If it is not given, v_i is used. Not used if minnesota is given or SSVS is applied.

const

a numeric or character specifying the prior mean of coefficients, which correspond to the intercept. If a numeric is provided, all prior means are set to this value. If coef$const = "mean", the mean of the respective endogenous variable is used as prior mean. If coef$const = "first", the first values of the respective endogenous variable is used as prior mean.

minnesota

a named list containing the parameters for the calculation of the Minnesota prior. It must contain kappa1, kappa2 and kappa4, and kappa3 if the model has exogenous variables. For the endogenous variable $i$ the prior variance of the $l$th lag of regressor $j$ is obtained as

$\frac{\kappa_{1}}{l^2} \textrm{ for own lags of endogenous variables,}$

$\frac{\kappa_{1} \kappa_{2}}{l^2} \frac{\sigma_{i}^2}{\sigma_{j}^2} \textrm{ for endogenous variables other than own lags,}$

$\frac{\kappa_{1} \kappa_{3}}{(l+1)^2} \frac{\sigma_{i}^2}{\sigma_{j}^2} \textrm{ for exogenous variables,}$

$\kappa_{1} \kappa_{4} \sigma_{i}^2 \textrm{ for deterministic terms,}$

where $\sigma_{i}$ is the residual standard deviation of variable $i$ of an unrestricted LS estimate. For exogenous variables $\sigma_{i}$ is the sample standard deviation. If the model does not contain exogenous variables, kappa3 will be ignored. The function only provides priors for the non-cointegration part of the model. However, the residual standard errors $\sigma_i$ are based on an unrestricted LS regression of the endogenous variables on the error correction term and the non-cointegration regressors.

max_var

a positive numeric specifying the maximum prior variance of the coefficients of non-deterministic variables in the Minnesota prior. Larger prior variances are set to this value. Only used if minnesota is given.

shape

a numeric specifying the shape of the gamma prior on the precisions, the inverse error variances, of the state equation, whose mean is shape / rate. Required for models with time varying parameters and not used otherwise.

rate

a numeric specifying the rate of the gamma prior on the precisions of the state equation. Required for models with time varying parameters and not used otherwise.

rate_det

a numeric specifying the prior rate parameter of the error variances of the state equation for coefficients, which correspond to deterministic terms. If it is not given, rate is used. Only used for models with time varying parameters.

rate_alpha

a numeric specifying the rate of the gamma prior on the precisions of the state equation of the loadings. If it is not given, rate is used. Only used for models with time varying parameters and a positive rank. The loadings multiply the levels in the error correction term, so a drift that is negligible for a coefficient on a differenced regressor moves the fitted value by much more; a rate several orders of magnitude below rate keeps their drift from absorbing the residuals while the other coefficients vary. It does not reach the steps of the cointegration vectors, which can absorb the residuals as well; see section 'Prior on the cointegration space'.

omega_v

a positive numeric, in place of shape, rate, rate_det and rate_alpha: the variance of a normal prior on the signed standard deviation of the state innovations of the coefficients, loadings included unless omega_v_alpha is given, and of the covariance coefficients – the non-centred parameterisation that lets the posterior carry the test for time variation of time_variation_test; see add_priors.bvarmodel for the model and the draws it adds. The cointegration space keeps its state equation. Only for models with time varying parameters, tvp = TRUE, whatever their error.

omega_v_alpha

a positive numeric, the omega_v of the loadings, as rate_alpha is their rate under the centred prior. If it is not given, omega_v is used. The loadings multiply the levels in the error correction term, so a standard deviation of their innovations that is small for a coefficient on a differenced regressor moves the fitted value by much more, and the test for time variation of time_variation_test compares each loading's posterior at zero with its own prior: a prior on the wrong scale makes the Bayes factor of a loading say more about the prior than about the loading. Only used with omega_v and a positive rank.

Argument coint specifies the prior on the cointegration space. Its elements, and the priors they give, are described in section 'Prior on the cointegration space' below, which is shared with cointspace_prior.

Argument sigma must contain the elements that belong to the error of the model:

• "wishart": df and scale. Not available for structural models.

• "gamma" and "gamma+covar": shape and rate.

• "sv" and "sv+covar": mu, v_i, shape, rate, state_variance and offset; with tvp = TRUE, omega_v may take the place of shape and rate, as coef$omega_v does for the coefficients.

The elements are

df

a positive integer, or a character expression in k, the number of endogenous variables, such as "k" or "k + 3", specifying the prior degrees of freedom of the inverse Wishart prior. The samplers add the rank $r$ of the cointegration matrix to the posterior degrees of freedom, as the prior of the loadings requires.

scale

a positive numeric specifying the prior error variance of the endogenous variables in the inverse Wishart prior.

shape

for "gamma" and "gamma+covar" a non-negative numeric, or a character expression in k as for df, specifying the shape of the gamma prior on the error precisions, the inverse error variances, whose mean is shape / rate, either one value or one per endogenous variable. For models with stochastic volatility a numeric specifying the shape of the gamma prior on the precision of the state equation of the log-volatilities.

rate

a positive numeric specifying the rate that corresponds to shape, for "gamma" and "gamma+covar" either one value or one per endogenous variable.

mu

numeric of the prior mean of the initial state of the log-volatilities. Only used for models with time varying volatility.

v_i

numeric of the prior precision of the initial state of the log-volatilities. Only used for models with time varying volatility.

state_variance

numeric of the initial draw for the variance of the log-volatilities. Only used for models with time varying volatility.

offset

numeric of the constant, which is added before taking the log of the squared errors. Only used for models with time varying volatility.

For structural models only a gamma prior or stochastic volatility specification is allowed.

Argument varsel can contain the following elements:

inprior

a numeric between 0 and 1 specifying the prior probability of a variable to be included in the model.

covar

logical indicating if the variable selection algorithm should also be applied to the error covariance matrix.

exclude_det

logical indicating if deterministic terms should be excluded from the variable selection algorithm.

minnesota

a numeric vector of length 4 containing parameters for the calculation of the Minnesota-like inclusion priors. See below.

tau

a numeric vector of two elements containing the prior standard errors of restricted variables ($\tau_0$) as its first element and unrestricted variables ($\tau_1$) as its second. Only used for SSVS.

semiautomatic

an numeric vector of two elements containing the factors by which the standard errors associated with an unconstrained least squares estimate of the model are multiplied to obtain the prior standard errors of restricted ($\tau_0$) and unrestricted ($\tau_1$) variables, respectively. This is the semiautomatic approach described in George et al. (2008). Only used for SSVS.

In the case of SSVS, either tau or semiautomatic must be specified.

If varsel$minnesota is specified, prior inclusion probabilities are calculated in a Minnesota-like fashion as

for lag $l$ with $\kappa_1$, $\kappa_2$, $\kappa_3$, $\kappa_4$ as the first, second, third and forth element in varsel$minnesota, respectively.

Value

The object in object with the element priors added, a list with

beta

the prior of the cointegration space with type "cointspace": v_inv and p_tau_inv for constant cointegration parameters, with g_inv if coint$g_i was given, or rho, mu and v_inv of the state equation for time varying ones, together with the elements added by p_tau_i = "ml" or a uniform prior on $\rho$.

a

the prior of the loadings and the remaining coefficients, with the same elements as for a VAR model in add_priors.bvarmodel.

psi, u_sigma

the priors of the error covariance coefficients and error variances, as for a VAR model.

Prior on the cointegration space

Argument coint can contain the following elements. Which of them are required depends on whether the cointegration vectors are constant or time varying, since the two are given different kinds of prior: a matric-variate prior on the cointegration space in the first case, and a state equation in the second. Any other element raises an error.

v_i

non-negative numeric specifying the shrinkage of the cointegration space prior, or "ml". See below. Required for models with constant cointegration parameters and not used otherwise.

p_tau_i

the inverse of the matrix $P_\tau$, which determines the central location of the cointegration space $sp(\beta)$. Either a numeric of its diagonal elements, a full symmetric matrix, or "ml", with one row and column per series in the error correction term data$train$w. See below. Required for models with constant cointegration parameters. For models with time varying cointegration parameters only "ml" is used.

weight

positive numeric specifying the weight of a prior centred on the maximum likelihood estimate in units of the information of the sample. Default is 1. Only used if p_tau_i = "ml".

rho

a numeric specifying the autocorrelation coefficient of the state equation of $\beta$. It must be smaller than 1. Required for models with time varying cointegration parameters and not used otherwise. If rho_min and rho_max are given as well, this is the value the chain starts $\rho$ at rather than the value it keeps, and it must lie between them.

rho_min, rho_max

numerics specifying the support of a uniform prior on $\rho$, which makes it a drawn parameter rather than a fixed hyperparameter. Optional, and either both or neither; they must satisfy $0 <$rho_min$<$rho_max$\le 1$. Koop et al. (2011) use $(0.999, 1)$. Only used for models with time varying cointegration parameters.

g_i

the inverse of the matrix $G$ that scales the prior of the loadings, for models with constant cointegration parameters and stochastic volatility, error = "sv" or "sv+covar", and refused for every other model. Either a numeric of its diagonal elements, a full symmetric positive definite matrix with one row and column per endogenous variable, or "ml" for the inverse of the maximum likelihood estimate of the error covariance. Optional. See below.

For a model with constant cointegration parameters the prior is that of Koop et al. (2010). The sampler uses v_i and p_tau_i only through their product, so with v_i = 0 the prior on the cointegration space is uniform whatever p_tau_i is. An informative prior on the space therefore needs a positive v_i, which also shrinks the loadings: for $\beta$ close to the centre of the space they have prior $N(0, \Sigma / v)$.