updateTVP: One step update version of 'shrinkTVP' with minimal overhead

In shrinkTVP: Efficient Bayesian Inference for Time-Varying Parameter Models with Shrinkage

One step update version of shrinkTVP with minimal overhead

Description

updateTVP draws a single sample from the joint posterior distribution of the parameters of a time-varying parameter model with shrinkage potentially including stochastic volatility (SV). It performs no input checks and must therefore be used with caution. It is designed to be used in a modular fashion within other samplers, where speed is important. As such, no draws are saved and must be stored manually if the user wants to analyze them further.

Usage

updateTVP(
  y,
  x,
  curr_draws,
  mod_type = "double",
  learn_a_xi = TRUE,
  learn_a_tau = TRUE,
  a_xi = 0.1,
  a_tau = 0.1,
  learn_c_xi = TRUE,
  learn_c_tau = TRUE,
  c_xi = 0.1,
  c_tau = 0.1,
  a_eq_c_xi = FALSE,
  a_eq_c_tau = FALSE,
  learn_kappa2_B = TRUE,
  learn_lambda2_B = TRUE,
  kappa2_B = 20,
  lambda2_B = 20,
  hyperprior_param,
  sv = FALSE,
  sv_param,
  MH_tuning
)

Arguments

y	vector of length N containing the response variable.
x	matrix of dimension Nxd containing the covariates.
curr_draws	named list containing all the current draws from the joint posterior of the parameters. Not all values are required for all model setups. The following elements can be supplied: beta_mean_st: vector of length d containing single numbers. theta_sr_st: vector of length d containing single, positive numbers. tau2_st: optional vector of length d containing single, positive numbers. Not required if mod_type is "ridge". xi2_st: optional vector of length d containing single, positive numbers. Not required if mod_type is "ridge". kappa2_st: optional vector of length d containing single, positive numbers. Only required if mod_type is "triple". lambda2_st: optional vector of length d containing single, positive numbers. Only required if mod_type is "triple". kappa2_B_st: optional positive, real number. Not required if mod_type is "ridge" or learn_kappa2_B is FALSE. lambda2_B_st: optional positive, real number. Not required if mod_type is "ridge" or learn_lambda2_B is FALSE. a_xi_st: optional positive, real number. Not required if mod_type is "ridge" or learn_a_xi is FALSE. a_tau_st: optional positive, real number. Not required if mod_type is "ridge" or learn_a_tau is FALSE. c_xi_st: optional positive, real number. Note that the prior for c_xi is restricted to (0, 0.5). Not required if mod_type is not "triple" or learn_c_xi is FALSE. c_tau_st: optional positive, real number. Note that the prior for c_tau is restricted to (0, 0.5). Not required if mod_type is not "triple" or learn_c_tau is FALSE. sv_mu_st: optional real number. Not required if sv is FALSE. sv_phi_st: optional positive, real number between -1 and 1. Not required if sv is FALSE. sv_sigma2_st : optional positive, real number. Not required if sv is FALSE. C0_st: optional positive, real number. Not required if sv is TRUE. sigma2_st: positive, real number if sv is FALSE, otherwise a vector of positive, real numbers of length N. The default value is 1 or a vector thereof. h0_st: optional real number. The default value is 0. Not required if sv is FALSE.
mod_type	character string that reads either "triple", "double" or "ridge". Determines whether the triple gamma, double gamma or ridge prior are used for theta_sr and beta_mean. The default is "double".
learn_a_xi	logical value indicating whether to learn a_xi, the spike parameter of the state variances. Ignored if mod_type is set to "ridge". The default value is TRUE.
learn_a_tau	logical value indicating whether to learn a_tau, the spike parameter of the mean of the initial values of the states. Ignored if mod_type is set to "ridge". The default value is TRUE.
a_xi	positive, real number, indicating the (fixed) value for a_xi. Ignored if learn_a_xi is TRUE or mod_type is set to "ridge". The default value is 0.1.
a_tau	positive, real number, indicating the (fixed) value for a_tau. Ignored if learn_a_tau is TRUE or mod_type is set to "ridge". The default value is 0.1.
learn_c_xi	logical value indicating whether to learn c_xi, the tail parameter of the state variances. Ignored if mod_type is not set to "triple". The default value is TRUE.
learn_c_tau	logical value indicating whether to learn c_tau, the tail parameter of the mean of the initial values of the states. Ignored if mod_type is not set to "triple". The default value is TRUE.
c_xi	positive, real number, indicating the (fixed) value for c_xi. Ignored if learn_c_xi is TRUE or mod_type is not set to "triple". The default value is 0.1.
c_tau	positive, real number, indicating the (fixed) value for c_tau. Ignored if learn_c_xi is TRUE or mod_type is not set to "triple". The default value is 0.1.
a_eq_c_xi	logical value indicating whether to force a_xi and c_xi to be equal. Ignored if mod_type is not set to "triple". The default value is FALSE.
a_eq_c_tau	logical value indicating whether to force a_tau and c_tau to be equal. Ignored if mod_type is not set to "triple". The default value is FALSE.
learn_kappa2_B	logical value indicating whether to learn kappa2_B, the global level of shrinkage for the state variances. The default value is TRUE.
learn_lambda2_B	logical value indicating whether to learn the lambda2_B parameter, the global level of shrinkage for the mean of the initial values of the states. The default value is TRUE.
kappa2_B	positive, real number, indicating the (fixed) value for kappa2_B. Ignored if learn_kappa2_B is TRUE. The default value is 20.
lambda2_B	positive, real number, indicating the (fixed) value for lambda2_B. Ignored if learn_lambda2_B is TRUE. The default value is 20.
hyperprior_param	optional named list containing hyperparameter values. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. All hyperparameter values have to be positive, real numbers. The following hyperparameters can be supplied: c0: The default value is 2.5. g0: The default value is 5. G0: The default value is 5 / (2.5 - 1). e1: The default value is 0.001. e2: The default value is 0.001. d1: The default value is 0.001. d2: The default value is 0.001. beta_a_xi: The default value is 10. beta_a_tau: The default value is 10. alpha_a_xi: The default value is 5. alpha_a_tau: The default value is 5. beta_c_xi: The default value is 2. alpha_c_xi: The default value is 5. beta_c_tau: The default value is 2. alpha_c_tau: The default value is 5.
sv	logical value indicating whether to use stochastic volatility for the error of the observation equation. For details please see stochvol, in particular svsample. The default value is FALSE.
sv_param	optional named list containing hyperparameter values for the stochastic volatility parameters. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. Ignored if sv is FALSE. The following elements can be supplied: Bsigma_sv: positive, real number. The default value is 1. a0_sv: positive, real number. The default value is 5. b0_sv: positive, real number. The default value is 1.5. bmu: real number. The default value is 0. Bmu: real number. larger than 0. The default value is 1.
MH_tuning	optional named list containing values used to tune the MH steps for a_xi, a_tau, c_xi and c_tau. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. The arguments for a_xi(a_tau) are only used if learn_a_xi(learn_a_tau) is set to TRUE and mod_type is not equal to "ridge". The arguments for c_xi(c_tau) are only used if learn_c_xi(learn_c_tau) is set to TRUE and mod_type is equal to "triple". Arguments ending in "adaptive" are logical values indicating whether or not to make the MH step for the respective parameter adaptive. Arguments ending in "tuning_par" serve two different purposes. If the respective MH step is not set to be adaptive, it acts as the standard deviation of the proposal distribution. If the respective MH step is set to be adaptive, it acts as the initial standard deviation. Arguments ending in "target_rate" define the acceptance rate the algorithm aims to achieve. Arguments ending in "max_adapt" set the maximum value by which the logarithm of the standard deviation of the proposal distribution is adjusted. Finally, arguments ending in "batch_size" set the batch size after which the standard deviation of the proposal distribution is adjusted. The following elements can be supplied: a_xi_adaptive: logical value. The default is TRUE. a_xi_tuning_par: positive, real number. The default value is 1. a_xi_target_rate: positive, real number, between 0 and 1. The default value is 0.44. a_xi_max_adapt: positive, real number. The default value is 0.01. a_xi_batch_size: positive integer. The default value is 50. a_tau_adaptive: logical value. The default is TRUE. a_tau_tuning_par: positive, real number. The default value is 1. a_tau_target_rate: positive, real number, between 0 and 1. The default value is 0.44. a_tau_max_adapt: positive, real number. The default value is 0.01. a_tau_batch_size: positive integer. The default value is 50. c_xi_adaptive: logical value. The default is TRUE. c_xi_tuning_par: positive, real number. The default value is 1. c_xi_target_rate: positive, real number, between 0 and 1. The default value is 0.44. c_xi_max_adapt: positive, real number. The default value is 0.01. c_xi_batch_size: positive integer. The default value is 50. c_tau_adaptive: logical value. The default is TRUE. c_tau_tuning_par: positive, real number. The default value is 1. c_tau_target_rate: positive, real number, between 0 and 1. The default value is 0.44. c_tau_max_adapt: positive, real number. The default value is 0.01. c_tau_batch_size: positive integer. The default value is 50.

Value

The value returned is a named list object which can be immediately used as the curr_draws argument for another draw from the posterior with updateTVP. Note that, depending on the model setup, some elements may be matrices of dimension zero. It contains the following elements:

beta_st	dx(N + 1) matrix containing the current draw from the posterior distribtuion of beta.
beta_mean_st	dx1 matrix containing the current draws from the posterior distribution of beta_mean.
theta_sr_st	dx1 matrix containing the current draws from the posterior distribution of the square root of theta.
tau2_st	dx1 matrix containing the current draws from the posterior distribution of tau2.
xi2_st	dx1 matrix containing the current draws from the posterior distribution of xi2.
lambda2_st	dx1 matrix containing the current draws from the posterior distribution of lambda2.
kappa2_st	dx1 matrix containing the current draws from the posterior distribution of kappa2.
a_xi_st	number representing the current draw from the posterior distribution of a_xi.
a_tau_st	number representing the current draw from the posterior distribution of a_tau.
c_xi_st	number representing the current draw from the posterior distribution of c_xi.
c_tau_st	number representing the current draw from the posterior distribution of c_tau.
lambda2_B_st	number representing the current draw from the posterior distribution of lambda2_B.
kappa2_B_st	mcmc object containing the parameter draws from the posterior distribution of kappa2_B.
sigma2_st	number if sv is FALSE, otherwise a vector of length N containing the current draws from the posterior distribution of sigma2.
C0_st	number representing the current draw from the posterior distribution of C0.
sv_mu_st	number representing the current draw from the posterior distribution of the mu parameter for the stochastic volatility model on the errors.
sv_phi_st	number representing the current draw from the posterior distribution of the phi parameter for the stochastic volatility model on the errors.
sv_sigma2_st	number representing the current draw from the posterior distribution of the sigma2 parameter for the stochastic volatility model on the errors.
h0_st	number representing the current draw from the posterior distribution of the h0 parmater for the stochastic volatility model on the errors.
internals	list object containg two arrays that are required for calculating the LPDS and bookkeeping objects required for the adaptive MH algorithm to work.

Author(s)

Peter Knaus [e-mail]

References

Bitto, A., & Frühwirth-Schnatter, S. (2019). "Achieving shrinkage in a time-varying parameter model framework." Journal of Econometrics, 210(1), 75-97. <doi:10.1016/j.jeconom.2018.11.006>

Cadonna, A., Frühwirth-Schnatter, S., & Knaus, P. (2020). "Triple the Gamma—A Unifying Shrinkage Prior for Variance and Variable Selection in Sparse State Space and TVP Models." Econometrics, 8(2), 20. <doi:10.3390/econometrics8020020>

Knaus, P., Bitto-Nemling, A., Cadonna, A., & Frühwirth-Schnatter, S. (2021) "Shrinkage in the Time-Varying Parameter Model Framework Using the R Package shrinkTVP." Journal of Statistical Software 100(13), 1–32.<doi:10.18637/jss.v100.i13>

Examples

# Simulate data
sim <- simTVP()
y <- sim$data$y
x <- as.matrix(sim$data[,2:4])

# Create starting values
d <- ncol(x)
curr_draws <- list(beta_mean_st = rep(0, d),
                   theta_sr_st = rep(1, d),
                   tau2_st = rep(1, d),
                   xi2_st = rep(1, d),
                   lambda2_st = rep(1, d),
                   kappa2_B_st = 20,
                   lambda2_B_st = 20,
                   a_xi_st = 0.1,
                   a_tau_st = 0.1,
                   c_tau_st = 0.1,
                   sv_mu_st = -10,
                   sv_phi_st = 0.5,
                   sv_sigma2_st = 1,
                   C0_st = 1,
                   sigma2_st = 1,
                   h0_st = 0)

# Run the algorithm for 1000 iterations
# Note that curr_draws is always re-written and immediately re-used
for (i in 1:1000){
  curr_draws <- updateTVP(y, x, curr_draws)
}

shrinkTVP documentation built on Nov. 23, 2023, 1:12 a.m.