exdqlmTransferMCMC: Transfer Function exDQLM - MCMC algorithm

In exdqlm: Extended Dynamic Quantile Linear Models

Transfer Function exDQLM - MCMC algorithm

Description

The function applies a Markov chain Monte Carlo (MCMC) algorithm to sample the posterior of an exDQLM with an exponential-decay transfer function component for a fixed transfer rate parameter lam. 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

exdqlmTransferMCMC(
  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,
  Sig.mh,
  joint.sample = FALSE,
  n.burn = 2000,
  n.mcmc = 1500,
  init.from.isvb = FALSE,
  PriorSigma = NULL,
  PriorGamma = NULL,
  verbose = TRUE,
  init.from.vb = TRUE,
  vb_init_controls = NULL,
  vb_init_fit = NULL,
  mh.proposal = c("slice", "laplace_rw", "rw"),
  mh.adapt = TRUE,
  mh.adapt.interval = 50L,
  mh.target.accept = c(0.2, 0.45),
  mh.scale.bounds = c(0.1, 10),
  mh.max_scale.step = 0.35,
  mh.min_burn_adapt = 50L,
  slice.width = 0.1,
  slice.max.steps = Inf,
  trace.diagnostics = TRUE,
  trace.every = 1L,
  verbose.every = 500L,
  progress_callback = NULL,
  tf.m0 = NULL,
  tf.C0 = NULL
)

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 AL/DQLM special case. Default is FALSE.
Sig.mh	Covariance matrix used in the random walk MH step to jointly sample sigma and gamma.
joint.sample	Logical value indicating whether or not to recompute Sig.mh based off the initial burn-in samples of gamma and sigma. Default is FALSE.
n.burn	Number of MCMC iterations to burn. Default is n.burn = 2000.
n.mcmc	Number of MCMC iterations to sample. Default is n.mcmc = 1500.
init.from.isvb	Logical value indicating whether to use the legacy ISVB warm start when init.from.vb = TRUE. Default is FALSE, which favors LDVB as the default VB warm start. This flag only chooses the warm-start source; it does not change the subsequent MCMC proposal kernel.
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 when supplied, 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.
verbose	Logical value indicating whether progress should be displayed.
init.from.vb	Optional logical. If TRUE, run a VB pre-initialization step (LDVB by default, or ISVB when init.from.isvb = TRUE) and initialize MCMC from converged VB moments. Default is TRUE. If explicitly set to NULL, it falls back to init.from.isvb behavior for backward compatibility.
vb_init_controls	Optional list controlling VB warm start. Supported keys: method ("isvb" or "ldvb"), tol, n.IS, n.samp, max_iter, verbose.
vb_init_fit	Optional precomputed VB fit object. If supplied, warm start uses this object directly and does not rerun VB internally.
mh.proposal	Character; proposal kernel for the exDQLM scale/skew block. "slice" (default) uses an exact sigma GIG update plus a bounded univariate slice sampler directly on gamma; "laplace_rw" uses a Laplace-informed covariance then RW; and "rw" uses joint random-walk MH on ⁠(log sigma, logit gamma)⁠. This choice is separate from the VB warm-start method.
mh.adapt	Logical; adapt MH proposal scale during burn-in.
mh.adapt.interval	Integer; adaptation interval (iterations).
mh.target.accept	Numeric length-2 vector with lower/upper target acceptance rates.
mh.scale.bounds	Numeric length-2 vector with min/max global scaling for MH covariance.
mh.max_scale.step	Numeric in (0,1); maximum fractional scale change per adaptation step.
mh.min_burn_adapt	Minimum burn-in iterations required to enable adaptation.
slice.width	Positive numeric width for the bounded slice sampler when mh.proposal = "slice". Default 0.1 for parity with bqrgal.
slice.max.steps	Positive integer or Inf; maximum stepping-out expansions for the slice sampler.
trace.diagnostics	Logical; if TRUE, retain per-iteration sigma/gamma/s/u diagnostics under mh.diagnostics$trace. Set FALSE for lighter-weight runs.
trace.every	Positive integer; when trace.diagnostics = TRUE, record one diagnostics row every trace.every iterations.
verbose.every	Positive integer controlling how often console progress is printed when verbose = TRUE. Default 500, independent of trace.every.
progress_callback	Optional callback invoked with a named list at MCMC start, at each progress checkpoint, and on completion. Intended for workflow-level progress logging.
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.

Value

An object of class "exdqlmMCMC" containing the following:

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

• run.time - Algorithm run time in seconds.

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

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

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

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

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

• n.burn Number of MCMC iterations that were burned.

• n.mcmc Number of MCMC iterations that were sampled.

If dqlm.ind=FALSE, the object also contains the following:

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

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

• init.log.sigma - Burned samples of log sigma from the random walk MH joint sampling of sigma and gamma.

• init.logit.gamma - Burned samples of logit gamma from the random walk MH joint sampling of sigma and gamma.

• accept.rate - Acceptance rate of the MH step.

• accept.rate.burn - MH acceptance rate during burn-in.

• accept.rate.keep - MH acceptance rate in kept MCMC samples.

• Sig.mh - Covariance matrix used in MH step to jointly sample sigma and gamma.

• mh.diagnostics - MH tuning diagnostics (proposal mode, scaling path, adaptation summary).

• diagnostics - ESS and chain-ready summaries for sigma/gamma.

Transfer-function return fields

In addition to the standard exdqlmMCMC() 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

data("scIVTmag", package = "exdqlm")
data("ELIanoms", package = "exdqlm")
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 = exdqlmTransferMCMC(
  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.burn = 40, n.mcmc = 40,
  init.from.vb = FALSE, verbose = FALSE
)
X_multi = cbind(ELIanoms[1:120], scale(scIVTmag[1:120])[, 1])
M2 = exdqlmTransferMCMC(
  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.burn = 40, n.mcmc = 40,
  init.from.vb = FALSE, verbose = FALSE
)

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