diagnostics: Convergence and Approximation Diagnostics for INLAvaan Models
In INLAvaan: Approximate Bayesian Latent Variable Analysis

diagnostics

R Documentation

Convergence and Approximation Diagnostics for INLAvaan Models

Description

Extract convergence and approximation-quality diagnostics from a fitted INLAvaan model.

Usage

diagnostics(object, ...)

## S4 method for signature 'INLAvaan'
diagnostics(object, type = c("global", "param"), ...)

Arguments

`object`	An object of class INLAvaan.
`...`	Currently unused.
`type`	Character. `"global"` (default) returns a named numeric vector of scalar diagnostics. `"param"` returns a data frame with one row per free parameter containing per-parameter diagnostics.

Details

Global diagnostics (type = "global"):

npar: Number of free parameters.
nsamp: Number of posterior samples drawn.
converged: 1 if the optimiser converged, 0 otherwise.
iterations: Number of optimiser iterations.
grad_inf: L-infinity norm of the analytic gradient at the mode (max |grad|). Should be ~0 at convergence.
grad_inf_rel: Relative L-infinity norm of the analytic gradient (max |grad| / (|par| + 1e-6)).
grad_l2: L2 (Euclidean) norm of the analytic gradient at the mode.
mode_shift_max: Maximum, across parameters, of the Newton step at the reported mode in posterior-SD units (max |\Sigma_\theta grad| / se). Unlike the raw gradient norms this is scale-free: it estimates how far the reported mode sits from the true posterior mode relative to the posterior uncertainty. Should be ~0 at convergence.
hess_cond: Condition number of the Hessian (precision matrix) computed from \Sigma_\theta. Large values indicate near-singularity.
vb_kld_global: Global KL divergence from the VB mean correction (NA if VB correction was not applied).
vb_applied: 1 if VB correction was applied, 0 otherwise.
vb_shift_max: Maximum, across parameters, of the absolute VB correction in posterior-SD units (max |vb_shift_sigma|). This is the quantity the fit-time check tests. NA if the VB correction was not applied.
kld_max: Maximum per-parameter KL divergence from the VB correction.
kld_mean: Mean per-parameter KL divergence.
vb_mcse_max: Maximum, across parameters, of the estimated quadrature error of the VB shift, in posterior-SD units. See vb_mcse_sigma below. NA under vb_method = "gauss_hermite".
vb_mcse_mean: Mean estimated quadrature error of the VB shift, in posterior-SD units.
nmad_max: Maximum normalised max-absolute-deviation across marginals (skew-normal method only; NA otherwise).
nmad_mean: Mean NMAD across marginals.
scan_end_mass_max: Maximum, across parameters, of scan_end_mass (see below). NA unless the skew-normal marginal method was used.

Per-parameter diagnostics (type = "param"): A data frame with columns:

names: Parameter name.
grad: Analytic gradient of the negative log-posterior at the mode. Should be ~0 at convergence.
grad_num: Numerical (finite-difference) gradient at the mode. Should agree with grad; large discrepancies indicate a bug in the analytic gradient.
grad_diff: Difference grad_num - grad: should be ~0.
grad_abs: Absolute analytic gradient.
grad_rel: Relative analytic gradient |grad| / (|par| + 1e-6).
mode_shift_sigma: Newton step at the reported mode in posterior-SD units. Should be ~0 at convergence.
kld: Per-parameter KL divergence from the VB correction.
vb_shift: VB correction shift (in original scale).
vb_shift_sigma: VB shift in units of posterior SD.
vb_mcse_sigma: Estimated quadrature error of the VB shift, in posterior-SD units. The shift is the solution of an integral evaluated by quasi-Monte Carlo over a finite node set, so it carries an integration error of its own. This estimates that error by splitting the node set in half and taking half the disagreement between the two half-set solutions. Read it as an error bar on vb_shift_sigma: a value of 0.05 means the reported posterior mean of that parameter could move by roughly that much, in SD units, purely from the choice of node set. It runs conservative, because the two halves are negatively correlated and quasi-Monte Carlo error falls faster than root-n. It is exactly zero for parameters whose shift is pinned by the saturated-means fast path, since no quadrature is used there. It is NA for every parameter under vb_method = "gauss_hermite", whose rule is deterministic.
nmad: Normalised max-absolute-deviation of the skew-normal fit (NA when not using the skewnorm method).
alpha: Shape parameter of the fitted skew-normal marginal, on the unconstrained scale. Zero is a Gaussian marginal, and the sign gives the direction of the skew (NA when not using the skewnorm method).
scan_end_mass: Mass the fitted marginal puts outside the window that was scanned to fit it, F(\hat\theta_j - 4 s_j) + 1 - F(\hat\theta_j + 4 s_j), where F is the fitted skew-normal distribution function, \hat\theta_j the posterior mode and s_j the Laplace posterior SD. The marginal is fitted inside that window only, so mass outside it is extrapolation, and when this is large the 2.5\ 97.5\ gives 2\Phi(-4) = 6.3e-05, and healthy fits sit between 1e-03 and 1e-02 (NA when not using the skewnorm method).

Fit-time warnings: inlavaan() runs these checks once at the end of every fit and emits a single consolidated warning (condition class "inlavaan_diagnostics_warning") when any of them looks off:

the optimiser did not converge;
mode_shift_max above 0.1 posterior SDs;
any marginal with nmad above 0.1;
any marginal with scan_end_mass above 0.05;
vb_shift_max above 1 posterior SD;
hess_cond above 1e8.

Three of these checks have calibration behind them. Over 1,046 simulated fits with MCMC references, the Spearman correlation with the worst-case posterior-mean discrepancy was 0.64 for the VB shift in SD units, 0.59 for the scan-endpoint mass and 0.48 for the NMAD. The convergence, mode-shift and condition-number checks are rules of thumb. Every number above is a package default, chosen so that a healthy fit stays silent, and not a calibrated cut-off: a tripped check is a prompt to look again, and silence is not a certificate of accuracy. Silence the check with suppressWarnings(), or selectively by handling the condition class.

Value

For type = "global", a named numeric vector (class "diagnostics.INLAvaan"). For type = "param", a data frame (class c("diagnostics.INLAvaan.param", "data.frame")).

Examples


HS.model <- "
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9
"
utils::data("HolzingerSwineford1939", package = "lavaan")
fit <- acfa(HS.model, HolzingerSwineford1939, std.lv = TRUE, nsamp = 100,
            test = "none", verbose = FALSE)

# Global convergence summary
diagnostics(fit)

# Per-parameter table
diagnostics(fit, type = "param")

INLAvaan documentation built on Oct. 2, 2026, 1:07 a.m.