exdqlmDiagnostics: exDQLM Diagnostics

In exdqlm: Extended Dynamic Quantile Linear Models

exDQLM Diagnostics

Description

The function computes the following for the model(s) provided: the posterior predictive loss criterion based off the check loss, the CRPS approximated as a finite integrated quantile score over posterior predictive empirical quantiles, the one-step-ahead distribution sequence, and deterministic semiclosed KL normality diagnostics for the MAP standardized forecast errors. The returned diagnostic object can be printed, summarized, or plotted with standard methods. Calling plot() on the object produces the QQ plot and ACF plot corresponding to the one-step-ahead distribution sequence, together with a time series plot of the MAP standard forecast errors.

Usage

exdqlmDiagnostics(
  m1,
  m2 = NULL,
  plot = FALSE,
  cols = c("red", "blue"),
  ref = NULL,
  crps_probs = seq(0.01, 0.99, by = 0.01),
  crps_weights = NULL,
  kl_k = NULL
)

Arguments

m1	A fitted dynamic exdqlmFit object, such as an object returned by exdqlmLDVB, exdqlmMCMC, or legacy exdqlmISVB.
m2	An optional second fitted dynamic exdqlmFit object to compare with m1.
plot	Logical value indicating whether to immediately plot the returned diagnostic object as a convenience shortcut. Default is FALSE; the preferred workflow is to save the object and then call plot() on it.
cols	Character vector of length 1 or 2 giving color(s) used to plot diagnostics. Default c("red","blue").
ref	Optional finite reference sample of size length(m1$y) from a standard normal distribution. Used for the reversed KL diagnostic. When NULL, a deterministic standard-normal quantile grid is used.
crps_probs	Numeric vector of quantile levels used to approximate CRPS through the integrated quantile-score identity. Values must be strictly between 0 and 1. Default is seq(0.01, 0.99, by = 0.01).
crps_weights	Optional non-negative numeric weights for crps_probs. When NULL, equal weights are used. When provided, weights are normalized to sum to 1.
kl_k	Optional positive integer vector of nearest-neighbor values used for the KL entropy and cross-entropy estimates. When NULL, the default grid c(3, 5, 10, 20, 30) is filtered to values supported by the finite standardized-error sample size, falling back to 1 for very small samples.

Details

The primary KL summary is computed from the MAP standardized one-step-ahead forecast errors map.standard.forecast.errors. The reported KL value is the user-facing calibration diagnostic and estimates KL(P_e || N(0,1)), where P_e is the continuous diagnostic-error law represented by the standardized errors. It uses the semiclosed identity KL(P_e || N(0,1)) = CE(P_e, N(0,1)) - H(P_e), with the normal cross-entropy term evaluated analytically and the entropy estimated by a one-dimensional k-nearest-neighbor estimator. The reported KL.flip estimates the reversed diagnostic KL(N(0,1) || P_e) using kNN cross-entropy. The reversed direction is more sensitive and should be read as a secondary sensitivity diagnostic, not as a replacement for KL. Advanced by-k sensitivity tables and Gaussian plug-in checks are stored under kl.details so the top-level diagnostic object exposes a single primary KL value. Negative finite-sample estimates are not clamped; they indicate estimator bias or instability for the current sample.

Value

An object of class "exdqlmDiagnostic" containing the following:

• m1.uts - The one-step-ahead distribution sequence of m1.

• m1.KL - The forward KL normality diagnostic KL(P_error || N(0,1)) for the MAP standardized forecast errors.

• m1.KL.flip - The reversed ("flipped") KL diagnostic KL(N(0,1) || P_error) for the MAP standardized forecast errors; this is a secondary sensitivity diagnostic.

• m1.CRPS - The mean CRPS approximated by a finite integrated quantile score over posterior predictive empirical quantiles.

• m1.pplc - The posterior predictive loss criterion of m1 based off the check loss function.

• m1.qq - The ordered pairs of the qq-plot comparing m1.uts with a standard normal distribution.

• m1.acf - The autocorrelations of m1.uts by lag.

• m1.rt - Run-time of the original model m1 in seconds.

• m1.msfe - MAP standardized one-step-ahead forecast errors from the original model m1.

• y - The original time-series used to fit m1.

• crps.method - The CRPS approximation method.

• crps.probs - The quantile levels used for the CRPS approximation.

• crps.weights - The normalized weights used for the CRPS approximation.

• kl.method, kl.k, kl.aggregate, and kl.reference - KL estimator metadata.

• kl.n_finite, kl.n_ref, and kl.zero_distance_count - KL diagnostic sample-size and distance-floor metadata.

• kl.details - Advanced KL estimator details by model. For each model this includes primary/flipped definitions, by-k sensitivity tables, a Gaussian plug-in check, and estimator metadata.

If m2 is provided, analogous results for m2 are also included in the list.

Examples

data("scIVTmag", package = "exdqlm")
old = options(exdqlm.max_iter = 15L)
y = scIVTmag[1:60]
model = polytrendMod(1, stats::quantile(y, 0.85), 10)
M0 = exdqlmLDVB(y, p0 = 0.85, model, df = c(0.95), dim.df = c(1),
                  gam.init = -3.5, sig.init = 15,
                  n.samp = 20, tol = 0.2, verbose = FALSE)
M0.diags = exdqlmDiagnostics(M0)
M0.diags
plot(M0.diags)
options(old)

exdqlm documentation built on July 10, 2026, 1:08 a.m.