exalStaticLDVB: Static exAL Regression - LDVB Approximation

In exdqlm: Extended Dynamic Quantile Linear Models

Static exAL Regression - LDVB Approximation

Description

The function applies a mean-field variational approximation to static Extended Asymmetric Laplace (exAL) regression. Closed-form block updates are combined with a Laplace-Delta approximation for the joint (\sigma,\gamma) block, yielding the package's static LDVB routine.

Usage

exalStaticLDVB(
  y,
  X,
  p0,
  max_iter = 1000,
  tol = 1e-04,
  b0 = NULL,
  V0 = NULL,
  beta_prior = c("ridge", "rhs", "rhs_ns"),
  beta_prior_controls = NULL,
  a_sigma = 1,
  b_sigma = 1,
  gamma_bounds = c(L.fn(p0), U.fn(p0)),
  log_prior_gamma = NULL,
  init = NULL,
  dqlm.ind = FALSE,
  al.ind = NULL,
  n.samp = 200,
  n_samp_xi = 200,
  ld_controls = NULL,
  vb_control = NULL,
  verbose = TRUE
)

Arguments

y	Numeric vector (length n).
X	Numeric matrix (n x p).
p0	Target quantile in (0,1).
max_iter	Integer; maximum LDVB iterations (default 1000).
tol	Numeric; convergence tolerance based on relative ELBO changes (default 1e-4).
b0, V0	Prior mean and covariance for \beta \sim \mathcal{N}(b_0,V_0).
beta_prior	Coefficient prior type: "ridge" (default), "rhs" (regularized horseshoe), or "rhs_ns" (Nishimura-Suchard regularized horseshoe with a closed-form inverse-gamma hierarchy for static inference).
beta_prior_controls	Optional list of prior-specific controls. For RHS-family priors (that is, when beta_prior is "rhs" or "rhs_ns"), supported keys include: tau0, nu, s or s2, shrink_intercept, intercept_prec, n_inner, eta_bounds, freeze_tau_iters, freeze_tau_warmup_iters, update_every, update_every_warmup, update_every_warmup_iters, force_tau_after_warmup, collapse_tau_ratio_tol, collapse_beta_max_abs_tol, collapse_invV_med_tol, collapse_beta_l2_tol, collapse_small_beta_frac_tol, small_beta_abs_tol, warn_on_collapse, var_floor, h_curv, verbose, init_lambda, init_log_lambda, init_tau, init_log_tau, init_c2, and init_log_c2. For beta_prior = "rhs_ns", optional slab controls a_zeta, b_zeta, and zeta2_fixed are also supported. In this mode, the local-global-slab block is represented by (\lambda_j^2,\nu_j,\tau^2,\xi,\zeta^2), with closed-form inverse-gamma updates in VB and MCMC. When beta_prior is "rhs" or "rhs_ns", b0 and V0 are retained only for backward-compatible ridge behavior and are ignored for the shrunk coefficients. If both init_log_tau and init_tau are omitted (or NULL), the RHS global scale initializes at tau = 1 (init_log_tau = 0) instead of tau0. By default (shrink_intercept = FALSE), the intercept is excluded from horseshoe shrinkage and uses intercept_prec.
a_sigma, b_sigma	Prior for \sigma \sim IG(a_\sigma,b_\sigma) with density p(\sigma)\propto \sigma^{-(a_\sigma+1)} e^{-b_\sigma/\sigma}.
gamma_bounds	Two-vector (L, U) support for gamma. Defaults to c(L.fn(p0), U.fn(p0)).
log_prior_gamma	Function g -> log pi(gamma=g). Default is a truncated Student-t prior centered at 0 on the admissible gamma support.
init	Optional list with starting values: beta, sigma, gamma; if missing, reasonable defaults are used.
dqlm.ind	Logical; if TRUE, fit the reduced AL model (gamma = 0). In that special case the nonconjugate block drops out and the remaining variational updates are available in closed form. This argument is retained for consistency with the dynamic exDQLM API; in static examples, al.ind = TRUE is the clearer spelling for this AL special case.
al.ind	Optional static-model alias for dqlm.ind. Prefer this argument when requesting the static AL special case. When supplied, this flag maps directly to dqlm.ind. If both are given, they must agree.
n.samp	Number of samples to draw from the approximated posterior distribution after convergence. Default is n.samp = 200.
n_samp_xi	Integer; retained for backward compatibility in the Laplace-Delta block. Under the current delta-only implementation this value is ignored.
ld_controls	Optional list of controls for the Laplace-Delta block. Supported keys include optimizer_method ("lbfgsb" or "bfgs"), direct_commit, damping, xi_damping, optimizer_maxit, eig_floor, eig_cap, step_cap_eta, step_cap_ell, eta_lo, eta_hi, sigma_bounds, sigma_init_mode, gamma_init_mode, sigma_floor_abs, sigma_min_mult, sigma_max_mult, sigma_bound_ratio_min, gamma_init_pad_frac, logit_eps, init_cov_diag, reuse_seed, mode_grad_tol, mode_min_eig, auto_stabilize, cycle_window, cycle_lag1_max, cycle_lag2_min, cycle_gamma_min_amp, cycle_sigma_min_amp, cycle_s_min_amp, cycle_tau2_min_amp, stabilize_damping, stabilize_xi_damping, stabilize_step_cap_eta, stabilize_step_cap_ell, and store_trace.
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, the package applies its conservative default warmup profile for exAL ⁠(sigma, gamma)⁠ updates while retaining the built-in RHS-family tau warmup defaults.
verbose	Logical; print progress.

Details

Mean-field factorization:

q(\beta)\ \prod_{i=1}^n q(v_i)\ q(s_i)\ q(\sigma,\gamma).

This factorization induces a blockwise coordinate-ascent variational inference scheme. The (\sigma,\gamma) block is the only nonconjugate component, so LDVB approximates it in transformed coordinates \eta=\mathrm{logit}((\gamma-L)/(U-L)) and \ell=\log\sigma. The xi expectations needed by the remaining block updates are then computed with a second-order Delta approximation. The xi expectations used in the updates can be computed either from a deterministic second-order Delta approximation in (\eta,\ell) or from a Gaussian Monte Carlo sample. The Laplace-Delta controls also allow bounded optimization in the transformed (\eta,\ell) block to better mimic the stabilized RHS-family readout implementation. For RHS-family priors, the prior block uses tau warmup/freeze scheduling to avoid the early-collapse regime where global shrinkage drives all slope coefficients toward zero before the likelihood-side variational factors stabilize.

Value

An object of class "exalStaticLDVB" containing:

• qbeta: list with m, V.

• samp.beta: posterior sample from q(\beta) with n.samp rows.

• qv: list with chi (length n), psi (scalar), E_v and E_inv_v (moments).

• qs: list with mu (length n), tau2 (length n), E_s, E_s2.

• qsiggam: list with eta_hat, ell_hat, Sigma (2x2), approximate means gamma_mean, sigma_mean, and the xi expectations.

• samp.sigma, samp.gamma: posterior samples from the variational approximation for the scale and skewness parameters. In the AL special case (dqlm.ind = TRUE), samp.gamma is a vector of zeros.

• converged, iter, run.time, and misc (including p0, bounds L,U, dimensions, and ELBO trace).

• beta_prior: prior metadata and, for RHS-family priors, posterior summaries of the shrinkage hyperparameters, including warmup/freeze-aware tau summaries and collapse diagnostics (collapse_flag, tau_near_zero, beta_collapse, and warning when triggered). For "rhs_ns", the state also tracks lambda2, nu, tau2, xi, and zeta2 with the corresponding inverse moments.

• diagnostics: ELBO and joint-convergence diagnostics including a standardized VB iteration trace at diagnostics$vb_trace (iteration-wise ELBO / sigma / gamma / convergence deltas), state/sigma/gamma/ELBO deltas, stopping reason, and Laplace-Delta block trace diagnostics, including replicated-xi controls, automatic stabilization / cycle-detection fields, and final local-mode quality checks. For RHS fits this also includes diagnostics$rhs with the resolved preflight configuration and collapse diagnostics.

Examples

set.seed(123)
n <- 60
X <- cbind(1, seq(-1, 1, length.out = n))
y <- as.numeric(X %*% c(0.2, -0.1) + rnorm(n, sd = 0.15))
fit <- exalStaticLDVB(y = y, X = X, p0 = 0.5, max_iter = 60, tol = 1e-3, verbose = FALSE)
fit$converged
head(fit$diagnostics$vb_trace)

fit_rhs <- exalStaticLDVB(
  y = y, X = X, p0 = 0.5,
  beta_prior = "rhs",
  beta_prior_controls = list(tau0 = 0.5, nu = 3, s2 = 1, shrink_intercept = FALSE),
  max_iter = 50, tol = 5e-3, verbose = FALSE
)
fit_rhs$beta_prior$type

fit_rhs_ns <- exalStaticLDVB(
  y = y, X = X, p0 = 0.5,
  beta_prior = "rhs_ns",
  beta_prior_controls = list(tau0 = 0.5, a_zeta = 1.5, b_zeta = 1, zeta2_fixed = 1),
  max_iter = 50, tol = 5e-3, verbose = FALSE
)
fit_rhs_ns$beta_prior$type

fit_al <- exalStaticLDVB(
  y = y, X = X, p0 = 0.5,
  al.ind = TRUE,
  max_iter = 50, tol = 5e-3, verbose = FALSE
)
fit_al$dqlm.ind

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