Check convergence, Hessian, gradients, and interval readiness

Run check_gllvmTMB() right after fitting, before interpreting confidence intervals or covariance summaries. It returns a stable table of optimiser, gradient, Hessian, sdreport(), restart, boundary, latent-identifiability, and binomial prevalence/loading diagnostics. It is the machine-readable companion to gllvmTMB_diagnose(): use this in simulations, tests, and reports where parsing printed messages would be brittle.

Usage

check_gllvmTMB(
  object,
  gradient_thresh = 0.01,
  se_thresh = 100,
  weak_axis_thresh = 0.05,
  psi_thresh = 1e-04,
  sigma_eps_thresh = 1e-04,
  cross_loading_thresh = 0.6,
  binary_prevalence_thresh = 0.9,
  binary_saturation_prob_thresh = 0.99,
  binary_saturation_share_thresh = 0.5,
  loading_relative_thresh = 8
)

Arguments

object

A fit returned by gllvmTMB().

gradient_thresh

Maximum allowed absolute gradient component. Default 0.01.

se_thresh

Threshold above which a fixed-effect standard error is flagged as weakly identified. Default 100.

weak_axis_thresh

Minimum acceptable share of shared loading energy for a fitted latent axis. Default 0.05.

psi_thresh

Threshold below which a fitted per-trait psi standard deviation is flagged as near zero. Default 0.0001.

sigma_eps_thresh

Threshold below which an estimated residual sigma_eps is flagged as near boundary. Default 0.0001.

cross_loading_thresh

Minimum median trait dominance on a single latent axis before a multi-axis loading matrix is treated as block-structured enough for direct interpretation. Default 0.6.

binary_prevalence_thresh

Prevalence at or beyond which a binomial trait is treated as near-constant. Default 0.9.

binary_saturation_prob_thresh

Response-scale fitted probability threshold for saturation in binomial traits. Default 0.99.

binary_saturation_share_thresh

Minimum share of saturated fitted probabilities before a binomial trait is flagged. Default 0.5.

loading_relative_thresh

Threshold for the largest trait loading relative to the typical fitted loading size. Default 8.

Value

A data frame with columns component, status, value, threshold, message, and action. Status values are "PASS", "WARN", or "FAIL".

Details

Scope: optimisation and inference-risk signals for fitted models, including latent-axis rotation, weak-axis, near-zero psi, residual-scale boundary flags, a binomial near-constant/loading/saturation screen, and the intentional gllvmTMBcontrol(se = FALSE) point-estimate path. The table does not calibrate interval coverage, prove formal separation, or prove the selected latent rank by itself. Target-explicit known-DGP simulations will decide when broader interval or rank-selection claims can move beyond diagnostic status.

A WARN row, including pdHess = FALSE, means that Wald standard errors or curvature-based inference need more care; it is not by itself proof that the fitted mean, likelihood, or rotation-invariant covariance summaries are unusable.

Examples

if (FALSE) { # \dontrun{
fit <- gllvmTMB(value ~ 0 + trait + latent(0 + trait | site, d = 2),
                data = dat, trait = "trait", unit = "site")
check_gllvmTMB(fit)
} # }