exdqlm (version 0.4.0)

exdqlmTransferISVB: 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
)

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.

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

Examples

# \donttest{
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)
# }