exdqlmTransferLDVB: Transfer Function exDQLM - LDVB algorithm

Description

The function applies a Laplace-Delta Variational Bayes (LDVB) algorithm to estimate the posterior of an exDQLM with an exponential-decay transfer function component. For multivariate transfer inputs, each column of X has its own instantaneous coefficient state in $\psi_t$, while a single scalar decay rate lam controls persistence of the accumulated transfer effect $\zeta_t$.

Usage

exdqlmTransferLDVB(
  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.samp = 200,
  PriorSigma = NULL,
  PriorGamma = NULL,
  tf.m0 = NULL,
  tf.C0 = NULL,
  verbose = TRUE,
  debug_shapes = FALSE,
  debug_every = 5
)

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.

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: Single transfer-function decay-rate parameter $\lambda$, a value between 0 and 1. This scalar is shared across all transfer inputs and controls propagation of the accumulated transfer effect $\zeta_t$.
tf.df: Discount factor specification for the transfer function component. These discount factors control the evolution variances of the transfer states, separately from the deterministic decay rate lam. 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.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.
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.

Transfer-function return fields

In addition to the standard exdqlmLDVB() return values, the returned model, df, and dim.df entries correspond to the transfer-function-augmented state-space model, with appended $\zeta_t$ and $\psi_t$ states. The object also contains:

lam - Single transfer-function decay-rate parameter $\lambda$.
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.
transfer_input_names - Column names of the transfer inputs after normalization of X.

Examples

Run this code

# \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
M1 = exdqlmTransferLDVB(
  y, p0 = 0.85, model = model, X = 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.samp = 20, tol = 0.2, verbose = FALSE
)
X_multi = cbind(ELIanoms[1:120], scale(scIVTmag[1:120])[, 1])
M2 = exdqlmTransferLDVB(
  y, p0 = 0.85, model = model, X = 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.samp = 20, tol = 0.2, verbose = FALSE
)
options(old)
# }

Run the code above in your browser using DataLab