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,
  psi_rel_thresh = 0.01,
  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,
  loading_runaway_thresh = 25,
  loading_absolute_thresh = 8,
  multinomial_collapse_floor = 1e-10,
  multinomial_collapse_rel_thresh = Inf,
  multinomial_rail_thresh = 0.99,
  multinomial_range_collapse_thresh = 0.02,
  ordinal_loading_runaway_thresh = Inf,
  ordinal_loading_absolute_thresh = Inf,
  phi_nbinom2_ceiling_thresh = 10000
)

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.
psi_rel_thresh: Threshold on the ratio of the smallest to the largest fitted per-trait psi standard deviation, below which the smallest is flagged as collapsed relative to its siblings. This catches boundary-pinned (Heywood) components whose absolute standard deviation still clears psi_thresh: psi is estimated on the log scale, so a component at the boundary is an interior point of the transformed space and pdHess stays positive definite there. Needs at least two components. Default 0.01, raised from 0.001 on measured evidence: across 360 gaussian and Poisson fits with a deliberately over-specified latent rank, 58% drove a unique standard deviation below a tenth of its true value while reporting convergence = 0 (208 of 209) and pdHess = TRUE (190 of 209). At 0.001 the row reported 73.7% of those; at 0.01 it reports 96.2%. The false-positive rate is zero at both, measured on 151 healthy fits and again on 359 healthy fits whose true unique variances differ by up to a factor of 1000 — the case that decides transport, since a small ratio is then correct rather than pathological. Looser thresholds do not transport: 0.1 reaches full sensitivity but flags 19% of those healthy heterogeneous fits.
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. At this level the loading is only reported alongside an extreme prevalence, because a sparse but genuine loading structure reaches it on healthy fits. Default 8.
loading_runaway_thresh: Threshold for the largest trait loading, relative to the typical fitted loading size, at which the loading is reported on its own without requiring an extreme prevalence. This catches an improper solution (Heywood case) from quasi-complete separation, which runs a loading away while the trait's marginal prevalence stays unremarkable. Default 25, calibrated on 6,824 simulated single-family binomial fits: no healthy fit reached it (the largest was 12.1), while it reported 96.3% of fits whose implied covariance was wrong by a factor of five or more. Two limits on that calibration are worth knowing. It has not been measured on mixed-family fits, and it would not transport to another family on its own, because a sparse but genuine loading structure pushes the ratio much higher there. The typical loading size is therefore taken over the binomial traits alone, so that a trait from another family cannot set the scale this threshold is judged against.
loading_absolute_thresh: Threshold on the largest trait loading itself, on the link scale, at which it is reported regardless of the other traits. A ratio cannot see a loading matrix inflated as a whole, because scaling every loading leaves every ratio unchanged; this supplies the absolute reference the ratio lacks. It is meaningful because the latent scores are standard normal by identification, so a binomial loading is the trait's latent standard deviation in link units: a value of this size already implies a fitted probability indistinguishable from 0 or 1 across an ordinary swing of the axis. Default 8, raised from 6 after the earlier calibration pool (3,944 simulated binomial fits, no healthy fit above 3.99) turned out to be unrepresentative: its true loading scale never reached the regime where this arm misfires. A second pool built specifically to cross sigma_lambda in c(0.7, 3.0) (928 healthy / 272 degenerate binomial-probit fits) – 3.0 chosen to probe the aghq_ridge ridge-failure regime, not argued for realism – measured this arm as the SOLE source of every false positive found (232/928 at threshold 6, all attributable to this arm alone). Raising the threshold to 8 lowers the false-positive rate on that pool from 0.2500 to 0.1552 while sensitivity on its degenerate fits falls only from 1.0000 to 0.9963 (one additional missed fit out of 272). This is an interim improvement, not a fix. The arm is regime/effect-size dependent, not response-scale dependent (probit fixes the residual variance at 1, so there is no free response scale here for a tau * sd(y)-style rescale to absorb): false-positive rate 3.85% at a mild true loading scale of sigma_lambda = 0.7 versus 49.08% at sigma_lambda = 3.0, so no fixed constant is correct across loading scales, and this default should not be read as calibrated against that regime. aghq_ridge = 2 reduces but does not remove the problem (46.0% -> 13.5% false positives at sigma_lambda = 3.0). Being a link-scale quantity it does not transport to families whose response scale is arbitrary, which is why this row is binomial-only. This rule applies to every link (family_id == 1L), but the calibration above is probit-only: logit loadings run larger than probit loadings for the same underlying model (the standard logistic/probit variance-matching ratio, commonly cited as ~1.6-1.8), so the same fixed threshold is reached by a smaller true effect on the logit link, and the false-positive rate measured here should be read as a lower bound on logit fits, not a transportable number – no logit evidence exists in the calibration pool.
multinomial_collapse_floor: Absolute floor on a multinomial() contrast's fitted loading energy (rowSums(Lambda^2)), at or below which it is a collapsed contrast. Default 1e-10. Evidence is limited to the tested model designs: 7/20 simulated phylo_indep() fits had loading energy at or below 1e-9, every one reporting convergence = 0 and a positive-definite Hessian. Check whether a flagged component was intentionally fixed at zero or whether its variance has collapsed.
multinomial_collapse_rel_thresh: Threshold on the ratio of the smallest to the largest fitted contrast loading energy within one multinomial() response's K-1 contrasts, below which the smallest is flagged as collapsed relative to the others. Default Inf (disabled). These contrasts share a baseline category and have pi^2/6 error covariance, so the threshold for independent components (psi_rel_thresh) cannot be assumed to apply. A reliable relative cutoff has not been established; inspect the contrast variances before choosing a finite threshold for your model.
multinomial_rail_thresh: Threshold on the largest absolute off-diagonal correlation of the implied contrast-level covariance within one multinomial() response's contrasts, at or above which two contrasts are flagged as nearly perfectly correlated. Only evaluated at tiers with rank d >= 2 – at d = 1 every healthy fit reaches |rho| = 1 exactly by row proportionality. Default 0.99; 8/20 simulated fits in the tested design reached or exceeded it. Performance in other designs may differ. If flagged, compare a lower rank and check the baseline-category coding.
multinomial_range_collapse_thresh: Threshold on the fitted spatial practical range (sqrt(8) / kappa) relative to the coordinate-domain diameter (when the fit's mesh coordinates are reachable), or on the practical range itself in absolute coordinate units (the fallback when they are not), below which a multinomial() response's spatial field is reported as collapsed. Default 0.02; collapsed ratios in the tested design ranged from 7e-5 to 3.4e-4. Performance in other designs may differ. Check mesh resolution and whether the data support estimating a spatial range for this response.
ordinal_loading_runaway_thresh: Threshold on an ordinal_probit() trait's largest loading relative to the typical loading among the other ordinal traits, at or above which the loading is reported on its own. Default Inf (disabled): the tested loading thresholds could not reliably distinguish poorly identified fits from healthy fits. Inspect the reported loadings and category frequencies; a large loading alone is not evidence of a failed fit.
ordinal_loading_absolute_thresh: Threshold on an ordinal_probit() trait's largest loading on the link (liability) scale, unit tiers only, at or above which it is reported regardless of the other traits. Meaningful because the probit-liability residual variance is exactly 1 under the Wright/Falconer/Hadfield threshold convention, so a loading is the trait's latent standard deviation in liability units, mirroring loading_absolute_thresh's binomial justification. Default Inf (disabled): healthy ordinal traits can also have large loadings. Inspect loadings alongside category frequencies and the other fit diagnostics before choosing a finite threshold for your model.
phi_nbinom2_ceiling_thresh: Numeric scalar. A negative-binomial dispersion estimate at or above this value is reported as a boundary_phi_nbinom2_<trait> warning: the trait has run to the Poisson limit (no overdispersion left to estimate), which usually means the data cannot separate dispersion from the zero-inflation or latent structure. Try a plain poisson() / zi_poisson() for that trait, or more sites.

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)
} # }