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\).
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
)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.
A univariate time-series.
The quantile of interest, a value between 0 and 1.
List of the state-space model including GG, FF,
prior parameters m0 and C0.
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.
Discount factors for each block.
Dimension of each block of discount factors.
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\).
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})\).
Logical value indicating whether to fix gamma at
gam.init. Default is FALSE.
Initial value for gamma (skewness parameter), or value at
which gamma will be fixed if fix.gamma = TRUE.
Logical value indicating whether to fix sigma at sig.init.
Default is FALSE.
Initial value for sigma (scale parameter), or value at which
sigma will be fixed if fix.sigma = TRUE.
Logical value indicating whether to fix gamma at 0,
reducing the exDQLM to the AL/DQLM special case. Default is FALSE.
Covariance matrix used in the random walk MH step to jointly sample sigma and gamma.
Logical value indicating whether or not to recompute Sig.mh based off the initial burn-in samples of gamma and sigma. Default is FALSE.
Number of MCMC iterations to burn. Default is n.burn = 2000.
Number of MCMC iterations to sample. Default is n.mcmc = 1500.
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.
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.
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.
Logical value indicating whether progress should be displayed.
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.
Optional list controlling VB warm start. Supported keys:
method ("isvb" or "ldvb"), tol, n.IS, n.samp, max_iter, verbose.
Optional precomputed VB fit object. If supplied, warm start uses this object directly and does not rerun VB internally.
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.
Logical; adapt MH proposal scale during burn-in.
Integer; adaptation interval (iterations).
Numeric length-2 vector with lower/upper target acceptance rates.
Numeric length-2 vector with min/max global scaling for MH covariance.
Numeric in (0,1); maximum fractional scale change per adaptation step.
Minimum burn-in iterations required to enable adaptation.
Positive numeric width for the bounded slice sampler when
mh.proposal = "slice". Default 0.1 for parity with bqrgal.
Positive integer or Inf; maximum stepping-out
expansions for the slice sampler.
Logical; if TRUE, retain per-iteration
sigma/gamma/s/u diagnostics under mh.diagnostics$trace. Set FALSE for
lighter-weight runs.
Positive integer; when trace.diagnostics = TRUE, record
one diagnostics row every trace.every iterations.
Positive integer controlling how often console progress
is printed when verbose = TRUE. Default 500, independent of
trace.every.
Optional callback invoked with a named list at MCMC start, at each progress checkpoint, and on completion. Intended for workflow-level progress logging.
Prior mean of the transfer function component. Defaults to a zero vector of length \(k+1\), where \(k = ncol(X)\).
Prior covariance of the transfer function component. Defaults to the \((k+1)\times(k+1)\) identity matrix.
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.
# \donttest{
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
)
# }
Run the code above in your browser using DataLab