Inspect profile confidence-interval shape for a fitted model

Use confint_inspect() when a profile confidence interval is missing, one-sided, very wide, or hard to trust. Most users should start with confint.gllvmTMB_multi() or the matching extract_*() interval helper; this function is the advanced visual check for a direct profile target.

Usage

confint_inspect(
  fit,
  parm,
  level = 0.95,
  ystep = 0.5,
  ytol = 2,
  parm.range = c(-Inf, Inf)
)

Arguments

fit: A fit returned by gllvmTMB().
parm: Character. A single profile-target label from profile_targets(). Examples: "sigma_eps", "sd_B[1]", "phi_nbinom2[2]", "b_fix[1]". Derived targets are not accepted by this direct-parameter diagnostic.
level: Confidence level. Default 0.95.
ystep: Profile grid spacing on the deviance scale, passed to TMB::tmbprofile(). Default 0.5.
ytol: Profile maximum-deviance budget, passed to TMB::tmbprofile(). Default 2.
parm.range: Two-element numeric range (in the TMB-link scale) for the profile walk, passed to TMB::tmbprofile(). Default c(-Inf, Inf).

Value

An object of class gllvmTMB_confint_inspect with components:

$curve: Data frame with one row per profile-grid point. Columns: parm (user-facing label), parm_value_natural (parameter value on the natural scale after the registered transformation), parm_value_link (parameter value on the TMB optimisation scale), nll (negative log-likelihood), deviance_drop (2 * (nll - mle_nll), the chi-squared statistic), excess_over_threshold (deviance_drop - chi2_threshold; negative is inside CI, positive is outside), in_ci (logical).
$bounds: Data frame, 1 row: parm, estimate_natural, lower_natural, upper_natural, wald_lower_natural, wald_upper_natural, wald_profile_disagree_lower, wald_profile_disagree_upper. Wald bounds come from fit$sd_report$cov.fixed via the delta method; disagreement flags are TRUE when the absolute difference exceeds 25% of the Wald half-width (a heuristic for "look at the plot").
$plot: A ggplot object visualising the curve, MLE, chi-squared threshold, profile bounds (vertical lines), and Wald bounds (dashed vertical lines for comparison). NULL if ggplot2 is not installed.
$diagnostics: Named character vector flagging any of: "no_heuristic_warning" (none of this helper's shape warnings fired; this does not prove a quadratic profile), "asymmetric" (skewed, Wald-vs-profile disagrees), "flat_at_mle", "hits_lower_bound", "hits_upper_bound", "no_lower_crossing", "no_upper_crossing", "profile_failed".
$call: The match.call() of the invocation.

Details

It returns the full profile-likelihood curve, the deviance bounds, and (when ggplot2 is available) a ggplot visualisation showing the curve, the MLE, the chi-squared threshold, and the resulting confidence-interval bounds. It surfaces a small set of numerical shape warnings before the user interprets the bound; the returned label is not a goodness or calibration certificate.

This helper inspects direct profile-ready targets from profile_targets(). Nonlinear derived targets such as communality, repeatability, and trait correlation do not currently have a public profile-inspection route. A working direct curve does not establish empirical interval coverage for every model class.

Common patterns to look for in the returned plot (see the profile-likelihood article):

Quadratic and approximately symmetric near the MLE: Wald and profile may agree closely for this target.
Asymmetric or skewed: inspect the endpoint status and constrained-fit stability before preferring either interval.
Flat near the MLE: the target may be weakly informed, or the numerical profile may need closer inspection.
Hits a parameter-range bound: interpret the endpoint on the target's transformed scale and distinguish a natural boundary from a truncated search.
No usable crossing: treat the endpoint as unavailable; do not replace it automatically with bootstrap output unless simulation, refits, failed replicate counts, and Monte Carlo resolution are credible for that target.

Examples

if (FALSE) { # \dontrun{
fit <- gllvmTMB(value ~ 0 + trait +
                latent(0 + trait | site, d = 1),
                data  = sim$data,
                trait = "trait",
                unit  = "site")
inspect <- confint_inspect(fit, parm = "sigma_eps")
inspect$bounds       # the CI + Wald comparison
inspect$diagnostics  # any shape flags
inspect$plot         # ggplot of the profile curve
} # }