exdqlmTransferISVB: Transfer Function exDQLM - legacy ISVB algorithm
In exdqlm: Extended Dynamic Quantile Linear Models

exdqlmTransferISVB

R Documentation

Transfer Function exDQLM - legacy ISVB algorithm

Description

The function applies an Importance Sampling Variational Bayes (ISVB) algorithm to estimate the posterior of an exDQLM with exponential-decay transfer function component. This transfer wrapper is retained as a legacy path; exdqlmTransferLDVB() is the main VB transfer entry point.

Usage

exdqlmTransferISVB(
  y,
  p0,
  model,
  X,
  df,
  dim.df,
  lam,
  tf.df,
  fix.gamma = FALSE,
  gam.init = NA,
  fix.sigma = FALSE,
  sig.init = NA,
  dqlm.ind = FALSE,
  exps0,
  tol = 0.1,
  n.IS = 500,
  n.samp = 200,
  PriorSigma = NULL,
  PriorGamma = NULL,
  tf.m0 = NULL,
  tf.C0 = NULL,
  verbose = TRUE
)

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`.
`X`	A numeric vector or matrix of transfer-function inputs. Vectors are treated as a univariate input series. Matrices should have one row per time point and one column per covariate.
`df`	Discount factors for each block.
`dim.df`	Dimension of each block of discount factors.
`lam`	Transfer function rate parameter lambda, a value between 0 and 1.
`tf.df`	Discount factor specification for the transfer function component. If `length(tf.df) = 1`, the value is shared by the `\zeta_t` state and the whole `\psi_t` block. If `length(tf.df) = 2`, it is interpreted as `c(df_zeta, df_psi_shared)`. If `length(tf.df) = k + 1`, where `k = ncol(X)`, the values are applied componentwise to `(\zeta_t, \psi_{1,t}, \dots, \psi_{k,t})`.
`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.IS`	Number of particles for the importance sampling of joint variational distribution of sigma and gamma. Default is `n.IS=500`.
`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.
`tf.m0`	Prior mean of the transfer function component. Defaults to a zero vector of length `k+1`, where `k = ncol(X)`.
`tf.C0`	Prior covariance of the transfer function component. Defaults to the `(k+1)\times(k+1)` identity matrix.
`verbose`	Logical value indicating whether progress should be displayed.

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

Value

An object of class "exdqlmISVB" containing the following:

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 augmented state-space model including GG, FF, prior parameters m0 and C0.
p0 - The quantile which was estimated.
df - Discount factors used for each block, including transfer function component.
dim.df - Dimension used for each block of discount factors, including transfer function component.
lam - Transfer function rate parameter lambda.
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.
median.kt - Median number of time steps until the aggregated transfer effect |x_t^\top \psi_{t-1}| is less than or equal to 1e-3.

If dqlm.ind=FALSE, the object 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 IS estimate of the variational distribution of sigma and gamma.
sts.out - List containing the variational distributions of latent parameters s_t.

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

sig.out - As above but for the DQLM case (gamma = 0); list containing the IS estimate of the variational distribution of sigma.

Examples


data("scIVTmag", package = "exdqlm")
data("ELIanoms", package = "exdqlm")
old = options(exdqlm.max_iter = 20L)
y = scIVTmag[1:120]
X = ELIanoms[1:120]
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
# Legacy ISVB transfer fit retained for backward-compatible comparisons
M1 = exdqlmTransferISVB(y, p0 = 0.85, model = model,
                          X, df = c(1,1), dim.df = c(1,4),
                          gam.init = -3.5, sig.init = 15,
                          lam = 0.38, tf.df = c(0.97,0.97),
                          n.IS = 20, n.samp = 20, tol = 0.2,
                          verbose = FALSE)
X_multi = cbind(ELIanoms[1:120], scale(scIVTmag[1:120])[, 1])
M2 = exdqlmTransferISVB(y, p0 = 0.85, model = model,
                          X_multi, df = c(1,1), dim.df = c(1,4),
                          gam.init = -3.5, sig.init = 15,
                          lam = 0.38, tf.df = c(0.97, 0.99),
                          n.IS = 20, n.samp = 20, tol = 0.2,
                          verbose = FALSE)
options(old)

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