exdqlmMCMC: exDQLM - MCMC algorithm

In exdqlm: Extended Dynamic Quantile Linear Models

exDQLM - MCMC algorithm

Description

The function applies a Markov chain Monte Carlo (MCMC) algorithm to sample the posterior of an exDQLM.

Arguments

y	A univariate time-series.
p0	The quantile of interest, a value between 0 and 1.
model	List of the state-space model including GG, FF, prior parameters m0 and C0.
df	Discount factors for each block.
dim.df	Dimension of each block of discount factors.
fix.gamma	Logical value indicating whether to fix gamma at gam.init. Default is FALSE.
gam.init	Initial value for gamma (skewness parameter), or value at which gamma will be fixed if fix.gamma = TRUE.
fix.sigma	Logical value indicating whether to fix sigma at sig.init. Default is FALSE.
sig.init	Initial value for sigma (scale parameter), or value at which sigma will be fixed if fix.sigma = TRUE.
dqlm.ind	Logical value indicating whether to fix gamma at 0, reducing the exDQLM to the AL/DQLM special case. Default is FALSE.
Sig.mh	Covariance matrix used in the random walk MH step to jointly sample sigma and gamma.
joint.sample	Logical value indicating whether or not to recompute Sig.mh based off the initial burn-in samples of gamma and sigma. Default is FALSE.
n.burn	Number of MCMC iterations to burn. Default is n.burn = 2000.
n.mcmc	Number of MCMC iterations to sample. Default is n.mcmc = 1500.
init.from.isvb	Logical value indicating whether to use the legacy ISVB warm start when init.from.vb = TRUE. Default is FALSE, which favors LDVB as the default VB warm start. This flag only chooses the warm-start source; it does not change the subsequent MCMC proposal kernel.
init.from.vb	Optional logical. If TRUE, run a VB pre-initialization step (LDVB by default, or ISVB when init.from.isvb = TRUE) and initialize MCMC from converged VB moments. Default is TRUE. If explicitly set to NULL, it falls back to init.from.isvb behavior for backward compatibility.
vb_init_controls	Optional list controlling VB warm start. Supported keys: method ("isvb" or "ldvb"), tol, n.IS, n.samp, max_iter, verbose.
vb_init_fit	Optional precomputed VB fit object. If supplied, warm start uses this object directly and does not rerun VB internally.
mcmc_control	Optional normalized MCMC control list, usually from exal_make_mcmc_control(). When supplied, the core MCMC arguments and warmup blocks are read from mcmc_control first and then merged with the explicit function arguments. When omitted, exAL-style dynamic MCMC uses the package's conservative default ⁠(sigma, gamma)⁠ warmup profile automatically; explicit controls remain the advanced override path.
sigmagam_controls	Optional list controlling warmup/freeze for the exDQLM sigma/gamma block during MCMC.
latent_state_controls	Optional list controlling early latent-state warmup/freeze in dynamic MCMC. Supported keys include freeze_burnin_iters, freeze_only_during_burn, force_after_warmup, and mode ("u_only" or "u_st_pair").
theta_state_controls	Optional list controlling early theta-state warmup/freeze in dynamic MCMC. Supported keys include freeze_burnin_iters, freeze_only_during_burn, and force_after_warmup.
dqlm_sigma_controls	Optional list controlling sigma-only warmup/freeze in the DQLM branch. Supported keys mirror sigmagam_controls.
mh.proposal	Character; proposal kernel for the exDQLM scale/skew block. "slice" (default) uses an exact sigma GIG update plus a bounded univariate slice sampler directly on gamma; "laplace_rw" uses a Laplace-informed covariance then RW; and "rw" uses joint random-walk MH on ⁠(log sigma, logit gamma)⁠. This choice is separate from the VB warm-start method.
mh.adapt	Logical; adapt MH proposal scale during burn-in.
mh.adapt.interval	Integer; adaptation interval (iterations).
mh.target.accept	Numeric length-2 vector with lower/upper target acceptance rates.
mh.scale.bounds	Numeric length-2 vector with min/max global scaling for MH covariance.
mh.max_scale.step	Numeric in (0,1); maximum fractional scale change per adaptation step.
mh.min_burn_adapt	Minimum burn-in iterations required to enable adaptation.
slice.width	Positive numeric width for the bounded slice sampler when mh.proposal = "slice". Default 0.1 for parity with bqrgal.
slice.max.steps	Positive integer or Inf; maximum stepping-out expansions for the slice sampler.
trace.diagnostics	Logical; if TRUE, retain per-iteration sigma/gamma/s/u diagnostics under mh.diagnostics$trace. Set FALSE for lighter-weight runs.
trace.every	Positive integer; when trace.diagnostics = TRUE, record one diagnostics row every trace.every iterations.
verbose.every	Positive integer controlling how often console progress is printed when verbose = TRUE. Default 500, independent of trace.every.
progress_callback	Optional callback invoked with a named list at MCMC start, at each progress checkpoint, and on completion. Intended for workflow-level progress logging.
PriorSigma	List of parameters for inverse gamma prior on sigma; shape a_sig and scale b_sig. Default is an inverse gamma with mean 1, or sig.init when supplied, and variance 10.
PriorGamma	List of parameters for truncated Student-t prior on gamma; center m_gam, scale s_gam, and degrees of freedom df_gam. Default is a standard Student-t with 1 degree of freedom, truncated to the support of gamma.
verbose	Logical value indicating whether progress should be displayed.

Value

An object of class "exdqlmMCMC" containing the following:

• y - Time-series data used to fit the model.

• run.time - Algorithm run time in seconds.

• dqlm.ind - Logical value indicating whether gamma was fixed at 0, reducing the exDQLM to the special case of the DQLM.

• model - List of the state-space model including GG, FF, prior parameters m0 and C0.

• p0 - The quantile which was estimated.

• df - Discount factors used for each block.

• dim.df - Dimension used for each block of discount factors.

• samp.theta - Posterior sample of the state vector.

• samp.post.pred - Sample of the posterior predictive distributions.

• map.standard.forecast.errors - MAP standardized one-step-ahead forecast errors.

• samp.sigma - Posterior sample of scale parameter sigma.

• samp.vts - Posterior sample of latent parameters, v_t.

• theta.out - List containing the distributions of the state vector including filtered distribution parameters (fm and fC) and smoothed distribution parameters (sm and sC).

• n.burn Number of MCMC iterations that were burned.

• n.mcmc Number of MCMC iterations that were sampled.

If dqlm.ind=FALSE, the object also contains the following:

• samp.gamma - Posterior sample of skewness parameter gamma.

• samp.sts - Posterior sample of latent parameters, s_t.

• init.log.sigma - Burned samples of log sigma from the random walk MH joint sampling of sigma and gamma.

• init.logit.gamma - Burned samples of logit gamma from the random walk MH joint sampling of sigma and gamma.

• accept.rate - Acceptance rate of the MH step.

• accept.rate.burn - MH acceptance rate during burn-in.

• accept.rate.keep - MH acceptance rate in kept MCMC samples.

• Sig.mh - Covariance matrix used in MH step to jointly sample sigma and gamma.

• mh.diagnostics - MH tuning diagnostics (proposal mode, scaling path, adaptation summary).

• diagnostics - ESS and chain-ready summaries for sigma/gamma.

Examples

data("scIVTmag", package = "exdqlm")
y = scIVTmag[1:80]
trend.comp = polytrendMod(order = 1, m0 = stats::quantile(y, 0.85), C0 = 10)
seas.comp = seasMod(p = 365, h = c(1,2), C0 = 10*diag(4))
model = trend.comp + seas.comp
M2 = exdqlmMCMC(y, p0=0.85, model, df = c(1,1), dim.df = c(1,4),
                gam.init = -3.5, sig.init = 15,
                n.burn = 40, n.mcmc = 40,
                init.from.vb = FALSE, verbose = FALSE)

M2_al = exdqlmMCMC(y, p0=0.85, model, df = c(1,1), dim.df = c(1,4),
                   dqlm.ind = TRUE, sig.init = 15,
                   n.burn = 30, n.mcmc = 30,
                   init.from.vb = FALSE, verbose = FALSE)

exdqlm documentation built on June 5, 2026, 1:06 a.m.