exdqlmLDVB: exDQLM - LDVB algorithm (Laplace-Delta)

In exdqlm: Extended Dynamic Quantile Linear Models

exDQLM - LDVB algorithm (Laplace-Delta)

Description

The function applies a Laplace-Delta Variational Bayes (LDVB) algorithm to estimate 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 special case of the DQLM. Default is FALSE.
exps0	Initial value for dynamic quantile. If exps0 is not specified, it is set to the DLM estimate of the p0 quantile.
tol	Tolerance for convergence of dynamic quantile estimates. Default is tol=0.1.
n.samp	Number of samples to draw from the approximated posterior distribution. Default is n.samp=200.
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 if provided) 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.
vb_control	Optional normalized VB control list, usually from exal_make_vb_control(). When supplied, the core VB arguments and warmup blocks are read from vb_control first and then merged with the explicit function arguments. When omitted, exAL-style VB fits use the package's conservative default ⁠(sigma, gamma)⁠ warmup profile automatically; explicit controls remain the advanced override path.
verbose	Logical value indicating whether progress should be displayed.
debug_shapes	Logical; if TRUE, print KF input/output shapes every debug_every iterations.
debug_every	Integer; frequency (in iterations) for shape prints when debug_shapes=TRUE.

Details

Advanced options (set via options()):

• exdqlm.use_cpp_kf: use the C++ Kalman filter bridge (default TRUE).

• exdqlm.compute_elbo: compute ELBO every iteration (default TRUE).

• exdqlm.tol_elbo: ELBO convergence tolerance (default 1e-6).

• exdqlm.tol_sigma: sigma-delta convergence tolerance (default: tol).

• exdqlm.tol_gamma: gamma-delta convergence tolerance (default: tol).

• exdqlm.vb.min_iter: minimum iterations before convergence can trigger (default 10).

• exdqlm.vb.patience: number of consecutive joint-converged iterations required (default 3).

• exdqlm.use_cpp_samplers: use C++ samplers for s_t, u_t, theta (default FALSE). The GIG-based u_t sampler always uses the package C++ Devroye implementation; when FALSE, the remaining samplers fall back to R implementations.

• exdqlm.use_cpp_postpred: use C++ posterior predictive sampler (default FALSE).

• exdqlm.dynamic.ldvb.sts: optional warmup/freeze controls for the exDQLM latent s_t VB block. Supported fields are freeze_warmup_iters, force_after_warmup, and min_postwarmup_updates.

Value

An object of class "exdqlmLDVB" containing the following:

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

• run.time - Algorithm run time in seconds.

• iter - Number of iterations until convergence was reached.

• 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.

• sig.init - Initial value for sigma, or value at which sigma was fixed if fix.sigma=TRUE.

• seq.sigma - Sequence of sigma estimated by the algorithm until convergence.

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

• 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 variational distribution.

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

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

• vts.out - List containing the variational distributions of latent parameters v_t.

• fix.sigma Logical value indicating whether sigma was fixed at sig.init.

• diagnostics - List containing ELBO trace, standardized VB iteration trace diagnostics$vb_trace (iteration-wise ELBO / sigma / gamma / convergence deltas), and convergence diagnostics (joint stopping status, deltas for state/sigma/gamma/ELBO, and criteria used).

If dqlm.ind=FALSE, the list also contains:

• gam.init - Initial value for gamma, or value at which gamma was fixed if fix.gamma=TRUE.

• seq.gamma - Sequence of gamma estimated by the algorithm until convergence.

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

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

• gammasig.out - List containing the LD (Laplace-Delta) approximation for the variational distribution of sigma and gamma (means, transformed Hessian, and ELBO components).

• sts.out - List containing the variational distributions of latent parameters s_t.

• fix.gamma Logical value indicating whether gamma was fixed at gam.init.

Or if dqlm.ind=TRUE, the list also contains:

• sig.out - As above but for the DQLM case (gamma = 0), the LD approximation for sigma.

Examples

data("scIVTmag", package = "exdqlm")
old = options(exdqlm.max_iter = 20L)
y = scIVTmag[1:80]
trend.comp = polytrendMod(1, stats::quantile(y, 0.85), 10)
seas.comp = seasMod(365, c(1,2), C0 = 10*diag(4))
model = trend.comp + seas.comp
M0 = exdqlmLDVB(y, p0 = 0.85, model, df = c(1,1), dim.df = c(1,4),
                 gam.init = -3.5, sig.init = 15, tol = 0.2,
                 n.samp = 20, verbose = FALSE)

M0_al = exdqlmLDVB(y, p0 = 0.85, model, df = c(1,1), dim.df = c(1,4),
                   dqlm.ind = TRUE, sig.init = 15, tol = 0.2,
                   n.samp = 20, verbose = FALSE)
options(old)

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