Title:	Bayesian Multivariate GARCH Models
Version:	2.0.0
Description:	Fit Bayesian multivariate GARCH models using 'Stan' for full Bayesian inference. Generate (weighted) forecasts for means, variances (volatility) and correlations. Currently DCC(P,Q), CCC(P,Q), pdBEKK(P,Q), and BEKK(P,Q) parameterizations are implemented, based either on a multivariate gaussian normal or student-t distribution. DCC and CCC models are based on Engle (2002) <doi:10.1198/073500102288618487> and Bollerslev (1990). The BEKK parameterization follows Engle and Kroner (1995) <doi:10.1017/S0266466600009063> while the pdBEKK as well as the estimation approach for this package is described in Rast et al. (2020) <doi:10.31234/osf.io/j57pk>. The fitted models contain 'rstan' objects and can be examined with 'rstan' functions.
License:	GPL (≥ 3)
Depends:	methods, R (≥ 4.0.0), Rcpp (≥ 1.0.5)
Imports:	forecast, ggplot2, loo, MASS, Rdpack, rstan (≥ 2.26.0), rstantools (≥ 2.1.1)
LinkingTo:	BH (≥ 1.72.0-0), Rcpp (≥ 1.0.5), RcppParallel (≥ 5.0.1), RcppEigen (≥ 0.3.3.7.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.26.0), StanHeaders (≥ 2.26.0)
RdMacros:	Rdpack
Encoding:	UTF-8
LazyData:	true
NeedsCompilation:	yes
SystemRequirements:	GNU make
RoxygenNote:	7.2.2
Suggests:	testthat (≥ 2.3.2)
BugReports:	https://github.com/ph-rast/bmgarch/issues
Biarch:	true
Packaged:	2023-09-11 23:22:51 UTC; philippe
Author:	Philippe Rast [aut, cre], Stephen Martin [aut]
Maintainer:	Philippe Rast <rast.ph@gmail.com>
Repository:	CRAN
Date/Publication:	2023-09-12 00:40:02 UTC

The 'bmgarch' package.

Description

The *bmgarch* package fits Bayesian multivariate GARCH models specified via stan, a C++ package providing HMC methods for full Bayesian inference (cf. [http://mc-stan.org]). The currently implemented parameterizations are DCC(Q,P), CCC(Q,P), and BEKK(Q,P) with arbitrary lags defined in Q, and P. The package provides summaries and plots for the estimates as well as forecasted series with corresponding plots. The fitted objects are rstan class objects that can be inspected and manipulated accordingly.

Author(s)

Philippe Rast

References

Stan Development Team (2018). RStan: the R interface to Stan. R package version 2.18.2. http://mc-stan.org

Quantiles within lists

Description

Obtain quantiles over columns in lists

Usage

.colQTs(x, probs)

Arguments

Value

Quantiles at the column level within lists

Author(s)

philippe

Internal function

Description

Internal function

Usage

.cp(x)

Arguments

Multiply matrices in array with a vector

Description

Multiply matrices in array with a vector

Usage

.f_MA(MA, theta, mu, rts, i)

Arguments

Value

matrix

Author(s)

Philippe Rast

Multiply matrices in array with a vector – generic

Description

Multiply matrices in array with a vector – generic

Usage

.f_array_x_mat(mat_out, array_obj, mat_obj, i)

Arguments

Value

matrix

Author(s)

Philippe Rast

Get stan summaries.

Description

Get stan summaries.

Usage

.get_stan_summary(model_fit, params, CrI, weights = NULL, sampling_algorithm)

Arguments

Value

Stan summary for parameters. Columns: mean, sd, mdn, and CrIs.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper - Return new line(s).

Description

Print helper - Return new line(s).

Usage

.newline(n = 1)

Arguments

Value

Prints new lines.

Author(s)

Stephen R. Martin

Convert predictive array to data.frame.

Description

Helper function for as.data.frame.fitted, forecast. Converts predictive array to data.frame.

Usage

.pred_array_to_df(arr, type = "backcast", param = "var")

Arguments

Value

data.frame. Columns: period, type (backcast, forecast), param (var, mean, cor), TS (which time series, or which correlation for param = cor), summary columns.

Author(s)

Stephen R. Martin

Print helper for Sampling Config.

Description

Print helper for Sampling Config.

Usage

.print.config(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for BEKK/pdBEKK.

Description

Print helper for BEKK/pdBEKK.

Usage

.print.summary.bekk(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for beta component.

Description

Print helper for beta component.

Usage

.print.summary.beta(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for CCC.

Description

Print helper for CCC.

Usage

.print.summary.ccc(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for DCC.

Description

Print helper for DCC.

Usage

.print.summary.dcc(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for LP component.

Description

Print helper for LP component.

Usage

.print.summary.lp(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for means component.

Description

Print helper for means component.

Usage

.print.summary.means(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Print helper for nu component.

Description

Print helper for nu component.

Usage

.print.summary.nu(bmsum)

Arguments

Value

Void.

Author(s)

Stephen R. Martin, Philippe Rast

Internal function to be used

Description

Internal function to be used

Usage

.qtile(x, CrI = c(0.025, 0.975))

Arguments

Refit model

Description

Refit model

Usage

.refit(object, data, xC_data)

Arguments

Print helper - Separator, new line

Description

Print helper - Separator, new line

Usage

.sep()

Value

Prints "—" and a new line.

Author(s)

Stephen R. Martin

Simulate BEKK data.

Description

Simulates time series data from specified BEKK model.

Usage

.sim.bekk(N, C, A, B, phi = NULL, theta = NULL)

Arguments

Details

Simulates timeseries data from specified BEKK model. Number of time series computed from the number of columns in C. All matrices must be of the same dimension. If ARMA parameters (phi, theta) unspecified (NULL), then assumes a constant mean of zero.

Value

Matrix of observations.

Author(s)

Stephen R. Martin

Internal function to be used in sweep()

Description

Internal function to be used in sweep()

Usage

.square(x)

Arguments

Value

Squared value

Author(s)

Philippe Rast

Print helper - tab

Description

Print helper - tab

Usage

.tab()

Value

Prints tab.

Author(s)

Stephen R. Martin

as.data.frame method for fitted.bmgarch objects.

Description

as.data.frame method for fitted.bmgarch objects.

Usage

## S3 method for class 'fitted.bmgarch'
as.data.frame(x, ...)

Arguments

Value

Data frame.

Author(s)

Stephen R. Martin

as.data.frame method for forecast.bmgarch objects.

Description

as.data.frame method for forecast.bmgarch objects.

Usage

## S3 method for class 'forecast.bmgarch'
as.data.frame(x, ..., backcast = TRUE)

Arguments

Value

Data frame.

Author(s)

Stephen R. Martin

Estimate Bayesian Multivariate GARCH

Description

Draw samples from a specified multivariate GARCH model using 'Stan', given multivariate time-series. Currently supports CCC, DCC, BEKK, and pdBEKK model parameterizations.

Usage

bmgarch(
  data,
  xC = NULL,
  parameterization = "CCC",
  P = 1,
  Q = 1,
  iterations = 2000,
  chains = 4,
  standardize_data = FALSE,
  distribution = "Student_t",
  meanstructure = "constant",
  sampling_algorithm = "MCMC",
  ...
)

Arguments

Details

Four types of paramerizations are implemented. The constant conditional correlation (CCC) and the dynamic conditional correlation (DCC; Engle2002,Engle2001a), as well as BEKK (Engle and Kroner 1995) and a BEKK model with positivity constraints on the diagonals of the ARCH and GARCH parameters "pdBEKK" (Rast et al. 2020).

The fitted models are 'rstan' objects and all posterior parameter estimates can be obtained and can be examined with either the 'rstan' toolbox, plotted and printed using generic functions or passed to 'bmgarch' functions to 'forecast' or compute 'model_weights' or compute fit statistics based on leave-future-out cross-validation.

Value

bmgarch object.

Author(s)

Philippe Rast, Stephen R. Martin

References

Engle RF, Kroner KF (1995). “Multivariate simultaneous generalized arch.” Econometric Theory, 11(1), 122–150. doi:10.1017/S0266466600009063.

Rast P, Martin SR, Liu S, Williams DR (2020). “A New Frontier for Studying Within-Person Variability: Bayesian Multivariate Generalized Autoregressive Conditional Heteroskedasticity Models.” Psychological Methods. https://psyarxiv.com/j57pk/.()

Examples

## Not run: 
data(panas)
# Fit BEKK(1,1) mgarch model with a ARMA(1,1) meanstructure,
# and student-t residual distribution
fit <- bmgarch(panas, parameterization = "BEKK",
               P = 1, Q = 1,
               meanstructure = "arma",
               distribution = "Student_t")

# Summarize the parameters
summary(fit)

# Forecast 5 ahead
fit.fc <- forecast(fit, ahead = 5)
print(fit.fc)

# Plot mean forecasts
plot(fit.fc, type = "mean")

# Plot variance forecasts
plot(fit.fc, type = "var")

# Plot correlation forecasts
plot(fit.fc, type = "cor")

# Plot modeled data ("backcasted values").
plot(fit, type = "mean")

# Save "backcasted" values
fit.bc <- fitted(fit)

# Save estimated and forecasted data as a data.frame
df.fc <- as.data.frame(fit.fc)

# Access rstan's model fit object
mf <- fit$model_fit

# Return diagnostics and a plot of the first 10 parameters
rstan::check_hmc_diagnostics(mf)
rstan::plot(mf)

## End(Not run)

Collect bmgarch objects into list.

Description

Collect bmgarch objects into list.

Usage

bmgarch_list(...)

Arguments

Value

List of bmgarch objects. Class: bmgarch_list and bmgarch.

Fitted (backcasting) method for bmgarch objects.

Description

Extracts the model-predicted means, variances, and correlations for the fitted data.

Usage

## S3 method for class 'bmgarch'
fitted(
  object,
  CrI = c(0.025, 0.975),
  digits = 2,
  weights = NULL,
  inc_samples = FALSE,
  ...
)

Arguments

Details

Whereas forecast.bmgarch computes the forecasted values for future time periods, fitted.bmgarch computes the backcasted (model-predicted) values for the observed time periods.

Value

fitted.bmgarch object. List containing metadata and the backcast. Backcast is a list containing three elements:

mean

[N, 7, TS] array of mean backcasts, where N is the timeseries length, and TS is the number of time series. E.g., bc$backcast$mean[3,,"tsA"] is the mean backcast for the third observation in time series "tsA".

var

[N, 7, TS] array of variance backcasts, where N is the timeseries length, and TS is the number of time series. E.g., bc$backcast$var[3,,"tsA"] is the variance backcast for the third observation in time series "tsA".

cor

[N, 7, TS(TS - 1)/2] array of correlation backcasts, where N is the timeseries length, and TS(TS - 1)/2 is the number of correlations. E.g., bc$backcast$cor[3,, "tsB_tsA"] is the backcast for the correlation between "tsB" and "tsA" on the third observation. Lower triangular correlations are saved.

samples

List

. If inc_samples is TRUE, then a list of arrays of MCMC samples for means, vars, and cors. Each array is [Iteration, Period, ..., ...].

Examples

## Not run: 
data(panas)
# Fit CCC(1,1) and constant meanstructure.
fit <- bmgarch(panas, parameterization = "CCC", meanstructure = "constant")

# Obtain fitted values
fit.bc <- fitted(fit)

# Print fitted values
print(fit.bc)

# Plot fitted values (plot.bmgarch calls fitted internally)
plot(fit, type = "var")

# Save fitted values as data frame
fit.bc.df <- as.data.frame(fit.bc)

## End(Not run)

Forecast method for bmgarch objects.

Description

Estimates (weighted) forecasted means, variances, and correlations from a fitted bmgarch model.

Usage

## S3 method for class 'bmgarch'
forecast(
  object,
  ahead = 1,
  xC = NULL,
  newdata = NULL,
  CrI = c(0.025, 0.975),
  seed = NA,
  digits = 2,
  weights = NULL,
  L = NA,
  method = "stacking",
  inc_samples = FALSE,
  ...
)

Arguments

Value

forecast.bmgarch object. List containing forecast, backcast, and metadata. See fitted.bmgarch for information on backcast. forecast is a list of four components:

mean

[N, 7, TS] array of mean forecasts, where N is the timeseries length, and TS is the number of time series. E.g., fc$forecast$mean[3,,"tsA"] is the 3-ahead mean forecast for time series "tsA".

var

[N, 7, TS] array of variance forecasts, where N is the timeseries length, and TS is the number of time series. E.g., fc$forecast$var[3,,"tsA"] is the 3-ahead variance forecast for time series "tsA".

cor

[N, 7, TS(TS - 1)/2] array of correlation forecasts, where N is the timeseries length, and TS(TS - 1)/2 is the number of correlations. E.g., fc$forecast$cor[3,, "tsB_tsA"] is the 3-ahead forecast for the correlation between "tsB" and "tsA". Lower triangular correlations are saved.

meta

Meta-data specific to the forecast. I.e., TS_length (number ahead) and xC.

samples

List

. If inc_samples is TRUE, then a list of arrays of MCMC samples for means, vars, and cors. Each array is [Iteration, Period, ..., ...].

Examples

## Not run: 
data(panas)
# Fit DCC(2,2) with constant mean structure.
fit <- bmgarch(panas, parameterization = "DCC", P = 2, Q = 2, meanstructure = "constant")

# Forecast 8 ahead
fit.fc <- forecast(fit, ahead = 8)

# Print forecasts
fit.fc
print(fit.fc)

# Plot variance forecasts
plot(fit.fc, type = "var")

# Plot correlation forecasts
plot(fit.fc, type = "cor")

# Save backcasted and forecasted values as data frame.
fit.fc.df <- as.data.frame(fit.fc)

# Save only forecasted values as data frame.
fit.fc.df <- as.data.frame(fit.fc, backcast = FALSE)

# Add another model, compute model weights and perform a model weighted forecast

# Fit a DCC(1,1) model
fit1 <- bmgarch(panas, parameterization = "DCC", P = 1, Q = 1, meanstructure = "constant")

# Compute model stacking weights based on the last 19 time points (with L = 80)
blist <- bmgarch_list( fit1, fit )
mw <- model_weights(blist, L = 80)

# Weighted forecasts:
w.fc <- forecast(object = blist, ahead = 8, weights = mw)

## End(Not run)

Leave-Future-Out Cross Validation (LFO-CV)

Description

lfocv returns the LFO-CV ELPD by either computing the exact ELDP or by approximating it via forward or backward approximation strategies based on Pareto smoothed importance sampling described in (Bürkner et al. 2020).

Usage

## S3 method for class 'bmgarch'
loo(x, ..., type = "lfo", L = NULL, M = 1, mode = "backward")

Arguments

Value

Approximate LFO-CV value and log-likelihood values across (L+1):N timepoints

References

Bürkner P, Gabry J, Vehtari A (2020). “Approximate leave-future-out cross-validation for Bayesian time series models.” Journal of Statistical Computation and Simulation, 1–25. doi:10.1080/00949655.2020.1783262.

Examples

## Not run: 
data(stocks)
# Fit a DCC model 
fit <- bmgarch(data = stocks[1:100, c("toyota",  "nissan" )],
               parameterization = "DCC", standardize_data = TRUE,
               iterations = 500)

# Compute expected log-predictive density (elpd) using the backward mode
# L is the upper boundary of the time-series before we engage in LFO-CV
lfob <- loo(fit, mode = 'backward',  L = 50 )
print(lfob)

## End(Not run)

Model weights

Description

Compute model weights for a list of candidate models based on leave-future-out cross validation (lfocv) expected log-predictive density (elpd). elpd can be approximated via the 'backward' mode described in Bürkner et al. (2020) or via exact cross-validation. The obtained weights can be passed to the forecast function to obtain weighted forecasts. bmgarch_objects takes a bmgarch_object lists.

Usage

model_weights(
  bmgarch_objects = NULL,
  L = NULL,
  M = 1,
  method = "stacking",
  mode = "backward"
)

Arguments

Details

‘model_weights()' is a wrapper around the leave-future-out ’lfo' type in 'loo.bmgarch()'. The weights can be either obtained from an approximate or exact leave-future-out cross-validation to compute expected log predictive density (ELPD).

We can either obtain stacking weights or pseudo-BMA+ weigths as described in (Yao et al. 2018).

Value

Model weights

References

Bürkner P, Gabry J, Vehtari A (2020). “Approximate leave-future-out cross-validation for Bayesian time series models.” Journal of Statistical Computation and Simulation, 1–25. doi:10.1080/00949655.2020.1783262.

Yao Y, Vehtari A, Simpson D, Gelman A (2018). “Using Stacking to Average Bayesian Predictive Distributions.” Bayesian Analysis, 13(3), 917–1007. doi:10.1214/17-BA1091.

Examples

## Not run: 
data(stocks)
# Fit at least two models on a subset of the stocks data
# to compute model weights
fit <- bmgarch(data = stocks[1:100, c("toyota",  "nissan" )],
               parameterization = "DCC", standardize_data = TRUE,
               iterations = 500)

fit2 <- bmgarch(data = stocks[1:100, c("toyota",  "nissan" )],
                P = 2, Q =  2,
               parameterization = "DCC", standardize_data = TRUE,
               iterations = 500)
# create a bmgarch_list object
blist <- bmgarch_list(fit, fit2 )

# Compute model weights with the default stacking metod
# L is the upper boundary of the time-series before we engage in LFO-CV
mw <- model_weights( blist, L =  50, method = 'stacking', order = 'backwards' )

# Print model weights in the ordert of the bmgarch_list()
print(mw)

## End(Not run)

Positive and Negative Affect Scores.

Description

A dataset containing simulated values for Positive and Negative Affect scores across 200 measurement occasions for a single individual.

Usage

panas

Format

Data frame with 200 rows and 2 variables:

Pos

Positive Affect score

Neg

Negative Affect score

Plot method for bmgarch objects.

Description

Plot method for bmgarch objects.

Usage

## S3 method for class 'bmgarch'
plot(x, type = "mean", askNewPage = TRUE, CrI = c(0.025, 0.975), ...)

Arguments

Value

List of ggplot objects (one per time series).

Author(s)

Stephen R. Martin

Plot method for forecast.bmgarch objects.

Description

Plot method for forecast.bmgarch objects.

Usage

## S3 method for class 'forecast.bmgarch'
plot(x, type = "mean", askNewPage = TRUE, last_t = 100, ...)

Arguments

Value

List of ggplot objects (one per time series).

Author(s)

Stephen R. Martin

Print method for fitted.bmgarch objects.

Description

Print method for fitted.bmgarch objects.

Usage

## S3 method for class 'fitted.bmgarch'
print(x, ...)

Arguments

Value

object (invisible).

Author(s)

Stephen R. Martin

Print method for forecast.bmgarch objects.

Description

Print method for forecast.bmgarch objects.

Usage

## S3 method for class 'forecast.bmgarch'
print(x, ...)

Arguments

Value

x (invisible).

Author(s)

Stephen R. Martin

print method for lfocv

Description

print method for lfocv

Usage

## S3 method for class 'loo.bmgarch'
print(x, ...)

Arguments

Value

Invisible lfocv object

Author(s)

philippe

Print method for model_weights

Description

Print method for model_weights

Usage

## S3 method for class 'model_weights'
print(x, ...)

Arguments

Value

model_weights objects with weights, list of log-likelihoods, and r_eff_list

Author(s)

philippe

Print method for bmgarch.summary objects.

Description

Print method for bmgarch.summary objects.

Usage

## S3 method for class 'summary.bmgarch'
print(x, ...)

Arguments

Value

x (invisible).

Author(s)

Philippe Rast, Stephen R. Martin

Standardize input data to facilitate computation

Description

Standardize input data to facilitate computation

Usage

standat(data, xC, P, Q, standardize_data, distribution, meanstructure)

Arguments

Value

bmgarch stan data list.

Daily data on returns of Toyota, Nissan, and Honda stocks.

Description

A dataset used by Stata to illustrate MGARCH models containing daily data on returns of Toyota, Nissan, and Honda stocks.

Usage

stocks

Format

Data frame with 2015 rows and 5 variables:

date

Date

t

Sequential time index

toyota

Daily returns for Toyota stock

nissan

Daily returns for Nissan stock

honda

Daily returns for Honda stock

Summary method for bmgarch objects.

Description

Computes posterior summaries for all parameters of interest for bmgarch objects.

Usage

## S3 method for class 'bmgarch'
summary(object, CrI = c(0.025, 0.975), digits = 2, ...)

Arguments

Value

summary.bmgarch object. A named list containing "meta" and "model_summary". model_summary contains summary table for all model parameters.

Author(s)

Stephen R. Martin, Philippe Rast

Models supported by bmgarch

Description

To be used when checking whether a parameterization or object type is a supported type. May facilitate more parameterizations, as we only have to update these, and the switch statements.

Usage

supported_models

Format

An object of class character of length 4.

Author(s)

Philippe Rast and Stephen R. Martin