| shrinkDTVP {shrinkTVP} | R Documentation |
Markov Chain Monte Carlo (MCMC) for time-varying parameter models with dynamic shrinkage
Description
shrinkTVP samples from the joint posterior distribution of the parameters of a time-varying
parameter model with dynamic triple gamma shrinkage, potentially including stochastic volatility (SV),
and returns the MCMC draws.
Usage
shrinkDTVP(
formula,
data,
mod_type = "double",
niter = 10000,
nburn = round(niter/2),
nthin = 1,
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,
a_psi = 0.5,
c_psi = 0.5,
iid = FALSE,
shrink_inter = TRUE,
hyperprior_param,
display_progress = TRUE,
sv = FALSE,
sv_param,
MH_tuning,
starting_vals
)
Arguments
formula |
object of class "formula": a symbolic representation of the model, as in the
function lm. For details, see formula.
|
data |
optional data frame containing the response variable and the covariates. If not found in data,
the variables are taken from environment(formula), typically the environment from which shrinkTVP
is called. No NAs are allowed in the response variable and the covariates.
|
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".
|
niter |
positive integer, indicating the number of MCMC iterations
to perform, including the burn-in. Has to be larger than or equal to nburn + 2. The default value is 10000.
|
nburn |
non-negative integer, indicating the number of iterations discarded
as burn-in. Has to be smaller than or equal to niter - 2. The default value is round(niter / 2).
|
nthin |
positive integer, indicating the degree of thinning to be performed. Every nthin draw is kept and returned.
The default value is 1, implying that every draw is kept.
|
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" or a_eq_c_xi is set to TRUE.
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" or a_eq_c_tau is set to TRUE.
The default value is TRUE.
|
c_xi |
positive, real number, indicating the (fixed) value for c_xi. Ignored if
learn_c_xi is TRUE, mod_type is not set to "triple" or a_eq_c_xi is set to TRUE.
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, mod_type is not set to "triple" or a_eq_c_tau is set to TRUE.
The default value is 0.1.
|
a_eq_c_xi |
logical value indicating whether to force a_xi and c_xi to be equal.
If set to TRUE, beta_a_xi and alpha_a_xi are used as the hyperparameters and beta_c_xi and alpha_c_xi are ignored.
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.
If set to TRUE, beta_a_tau and alpha_a_tau are used as the hyperparameters and beta_c_tau and alpha_c_tau are ignored.
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.
|
a_psi |
positive, real number, or a vector of length equal to the number of covariates containing
positive, real numbers. Indicates the value for a_psi, which is the pole parameter of the dynamic triple gamma.
The default value is 0.5.
|
c_psi |
positive, real number, or a vector of length equal to the number of covariates containing
positive, real numbers. Indicates the value for c_psi, which is the tail parameter of the dynamic triple gamma.
The default value is 0.5.
|
iid |
logical value indicating whether the innovations are assumed to be independent and identically distributed.
If set to TRUE, the innovations are assumed to be a priori iid triple gamma. If set to FALSE,
the prior on the innovations is the dynamic triple gamma specification of Knaus and Frühwirth-Schnatter (2023).
The default value is FALSE.
|
shrink_inter |
logical value indicating whether to dynamically shrink the intercept. Note that shrinkage is still applied
to the theta_sr and beta_mean associated with the intercept. The intercept column is automatically determined
by the function and does not have to be included in the formula. This is done by finding the column that contains only 1s.
The default value is TRUE.
|
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.
-
alpha_a_xi: The default value is 5.
-
alpha_a_tau: The default value is 5.
-
beta_a_xi: The default value is 10.
-
beta_a_tau: The default value is 10.
-
alpha_c_xi: The default value is 5.
-
alpha_c_tau: The default value is 5.
-
beta_c_xi: The default value is 2.
-
beta_c_tau: The default value is 2.
-
a_rho: The default value is 2.
-
b_rho: The default value is 0.95.
-
alpha_rho: The default value is 0.5.
-
beta_rho: The default value is 3.
|
display_progress |
logical value indicating whether the progress bar and other informative output should be
displayed. The default value is TRUE.
|
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.
-
rho_adaptive: logical value. The default is TRUE.
-
rho_tuning_par: positive, real number. The default value is 1.
-
rho_target_rate: positive, real number, between 0 and 1. The default value is 0.44.
-
rho_max_adapt: positive, real number. The default value is 0.01.
-
rho_batch_size: positive integer. The default value is 50.
|
starting_vals |
optional named list containing the values at which the MCMC algorithm will be initialized. In the
following d refers to the number of covariates, including the intercept and expanded factors.
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 following elements can be supplied:
-
beta_mean_st: vector of length d containing single numbers. The default is rep(0, d).
-
theta_sr_st: vector of length d containing single, positive numbers. The default is rep(1, d).
-
tau2_st: vector of length d containing single, positive numbers. The default is rep(1, d).
-
xi2_st: vector of length d containing single, positive numbers. The default is rep(1, d).
-
kappa2_st: vector of length d containing single, positive numbers. The default is rep(1, d).
-
lambda2_st: vector of length d containing single, positive numbers. The default is rep(1, d).
-
kappa2_B_st: positive, real number. The default value is 20.
-
lambda2_B_st: positive, real number. The default value is 20.
-
a_xi_st: positive, real number. The default value is 0.1.
-
a_tau_st: positive, real number. The default value is 0.1.
-
c_xi_st: positive, real number. The default value is 0.1. Note that the prior for c_xi is restricted to (0, 0.5).
-
c_tau_st: positive, real number. The default value is 0.1. Note that the prior for c_tau is restricted to (0, 0.5).
-
sv_mu_st: real number. The default value is -10.
-
sv_phi_st: positive, real number between -1 and 1. The default value is 0.5.
-
sv_sigma2_st : positive, real number. The default value is 1.
-
C0_st: positive, real number. The default value is 1.
-
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: real number. The default value is 0.
-
lambda_0_st vector of length d containing positive, real numbers. The default value is rep(1, d).
-
rho_st: vector of length d containing real numbers between 0 and b_rho. The default value is rep(max(0.1, hyperprior_param$b_rho - 0.1), d).
|
Details
For details concerning the algorithms please refer to the papers by Bitto and Frühwirth-Schnatter (2019),
Cadonna et al. (2020) and Knaus and Frühwirth-Schnatter (2023).
For more details on the package and the usage of the functions, see Knaus et al. (2021).
Value
The value returned is a list object of class shrinkTVP containing
beta |
list object containing an mcmc.tvp object for the parameter draws from the posterior distribution of the centered
states, one for each covariate. In the case that there is only one covariate, this becomes just a single mcmc.tvp object.
|
beta_mean |
mcmc object containing the parameter draws from the posterior distribution of beta_mean.
|
theta_sr |
mcmc object containing the parameter draws from the posterior distribution of the square root of theta.
|
tau2 |
mcmc object containing the parameter draws from the posterior distribution of tau2.
|
xi2 |
mcmc object containing the parameter draws from the posterior distribution of xi2.
|
psi |
list object containing an mcmc.tvp object for the parameter draws from the posterior distribution of psi,
one for each covariate. In the case that there is only one covariate, this becomes just a single mcmc.tvp object.
|
lambda_p |
list object containing an mcmc.tvp object for the parameter draws from the posterior distribution of lambda_p,
one for each covariate. In the case that there is only one covariate, this becomes just a single mcmc.tvp object.
|
kappa_p |
(optional) list object containing an mcmc.tvp object for the parameter draws from the posterior
distribution of kappa_p, one for each covariate. In the case that there is only one covariate, this becomes just a single mcmc.tvp object.
Not returned if iid is not TRUE.
|
lambda2 |
(optional) mcmc object containing the parameter draws from the posterior distribution of lambda2.
Not returned if mod_type is not "triple".
|
kappa2 |
(optional) mcmc object containing the parameter draws from the posterior distribution of kappa2.
Not returned if mod_type is not "triple".
|
a_xi |
(optional) mcmc object containing the parameter draws from the posterior distribution of a_xi.
Not returned if learn_a_xi is FALSE or mod_type is "ridge".
|
a_tau |
(optional) mcmc object containing the parameter draws from the posterior distribution of a_tau.
Not returned if learn_a_tau is FALSE or mod_type is "ridge".
|
c_xi |
(optional) mcmc object containing the parameter draws from the posterior distribution of c_xi.
Not returned if learn_c_xi is FALSE or mod_type is not "triple".
|
c_tau |
(optional) mcmc object containing the parameter draws from the posterior distribution of c_tau.
Not returned if learn_c_tau is FALSE or mod_type is not "triple".
|
lambda2_B |
(optional) mcmc object containing the parameter draws from the posterior distribution of lambda2_B.
Not returned if learn_lambda2_B is FALSE or mod_type is "ridge".
|
kappa2_B |
(optional) mcmc object containing the parameter draws from the posterior distribution of kappa2_B.
Not returned if learn_kappa2_B is FALSE or mod_type is "ridge".
|
rho |
(optional) mcmc object containing the parameter draws from the posterior distribution of rho.
Not returned if iid is not TRUE.
|
sigma2 |
mcmc object containing the parameter draws from the posterior distribution of sigma2.
If sv is TRUE, sigma2 is additionally an mcmc.tvp object.
|
C0 |
(optional) mcmc object containing the parameter draws from the posterior distribution of C0.
Not returned if sv is TRUE.
|
sv_mu |
(optional) mcmc object containing the parameter draws from the posterior distribution of the mu
parameter for the stochastic volatility model on the errors. Not returned if sv is FALSE.
|
sv_phi |
(optional) mcmc object containing the parameter draws from the posterior distribution of the phi
parameter for the stochastic volatility model on the errors. Not returned if sv is FALSE.
|
sv_sigma2 |
(optional) mcmc object containing the parameter draws from the posterior distribution of the sigma2
parameter for the stochastic volatility model on the errors. Not returned if sv is FALSE.
|
MH_diag |
(optional) named list containing statistics for assessing MH performance. Not returned if no MH steps are required
or none of them are specified to be adaptive.
|
internals |
list object containing two arrays that are required for calculating the LPDS.
|
priorvals |
list object containing hyperparameter values of the prior distributions, as specified by the user.
|
model |
list object containing the model matrix, model response and formula used.
|
summaries |
list object containing a collection of summary statistics of the posterior draws.
|
To display the output, use plot and summary. The summary method displays the specified prior values stored in
priorvals and the posterior summaries stored in summaries, while the plot method calls coda's plot.mcmc
or the plot.mcmc.tvp method. Furthermore, all functions that can be applied to coda::mcmc objects
(e.g. coda::acfplot) can be applied to all output elements that are coda compatible.
Author(s)
Peter Knaus peter.knaus@wu.ac.at
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>
Knaus, P., & Frühwirth-Schnatter, S. (2023). "The Dynamic Triple Gamma Prior as a Shrinkage Process Prior for Time-Varying Parameter Models." arXiv preprint arXiv:2312.10487. <doi:10.48550/arXiv.2312.10487>
See Also
plot.shrinkTVP, plot.mcmc.tvp
Examples
set.seed(123)
sim <- simTVP(DTG = TRUE, theta = c(0, 1, 0), beta_mean = c(1, 1, 0), rho = 0.95, c_psi = 2)
data <- sim$data
## Example 1, match the true underlying process
res <- shrinkDTVP(y ~ x1 + x2, data = data, c_psi = 2)
# summarize output
summary(res)
## Example 2, dynamic horseshoe
res <- shrinkDTVP(y ~ x1 + x2, data = data)
## Example 3, modify hyperparameters
res <- shrinkDTVP(y ~ x1 + x2, data = data,
hyperprior_param = list(a_rho = 1,
alpha_rho = 0.5,
beta_rho = 0.5))
[Package
shrinkTVP version 3.0.1
Index]