Confidence intervals on fixed effects of a gllvmTMB_multi fit

Returns 95% (or other-level) confidence intervals for fixed effects, variance components, and trait covariance matrices, with three method choices:

Usage

# S3 method for class 'gllvmTMB_multi'
confint(
  object,
  parm,
  level = 0.95,
  method = c("profile", "wald", "bootstrap"),
  nsim = 500L,
  seed = NULL,
  ...
)

# S3 method for class 'gllvmTMB_multi'
confint(
  object,
  parm,
  level = 0.95,
  method = c("profile", "wald", "bootstrap"),
  nsim = 500L,
  seed = NULL,
  ...
)

Arguments

object

A gllvmTMB_multi fit returned by gllvmTMB().

parm

One of:

"Sigma_B" – between-unit trait covariance matrix.
"Sigma_W" – within-unit trait covariance matrix.
"sigma_phy" – per-trait phylogenetic standard deviations.
An integer index vector or character vector of fixed-effect term names (same as the standard confint() interface).
Missing (default) – all fixed-effect parameters.

level

Confidence level in (0, 1). Default 0.95.

method

One of "profile" (default), "wald", "bootstrap".

nsim

Number of bootstrap replicates passed to bootstrap_Sigma() when method = "bootstrap". Default 500. Use a small value (e.g. 50) during development or testing.

seed

Optional integer RNG seed forwarded to bootstrap_Sigma() (only meaningful when method = "bootstrap").

...

Additional arguments currently unused.

Value

A matrix with rows = parameters and columns = the lower and upper bounds of the Wald CI.

Sigma path – a data.frame with columns parameter (character, e.g. "Sigma_B[t1,t1]"), estimate (point estimate), lower, upper, and method (the method used for that row).
Fixed-effects / variance-component path – a numeric matrix with rownames = parameter names and two columns named "2.5 %" / "97.5 %" (or the analogous quantiles for the requested level).

Details

method = "profile" (new default in Phase K): profile-likelihood CIs via TMB::tmbprofile() + stats::uniroot(). Accurate, respects skewness, fast for individual parameters.
method = "wald": Gaussian-approximation CIs from sd_report. Fastest; poor near boundaries.
method = "bootstrap": parametric bootstrap via bootstrap_Sigma(). Slowest; most flexible (full sampling distribution).

Two parm-class dispatch paths:

Sigma matrices – when parm is one of "Sigma_B", "Sigma_W", or "sigma_phy", returns a tidy data.frame with columns parameter, estimate, lower, upper, method. Profile is computed element-wise via TMB::tmbprofile() for the diagonal entries; off- diagonals fall back to bootstrap (full Σ sampling) since they mix two parameters in a non-linear way.
Fixed effects / variance components – when parm is missing, an integer index, or a character vector of fixed-effect term names, returns a numeric matrix with rows = parameters and columns = lower / upper bounds (same shape as stats::confint()). Method choice applies.

References

Pawitan, Y. (2001). In All Likelihood: Statistical Modelling and Inference Using Likelihood, Oxford University Press, ch. 9.

Venzon, D. J. & Moolgavkar, S. H. (1988). A method for computing profile-likelihood-based confidence intervals. Applied Statistics 37, 87-94. doi:10.2307/2347496

McCune, K. B., et al. (2024) coxme_icc_ci() – the Nakagawa-authored coxme-based profile-CI helper that inspired this work, in https://github.com/kelseybmccune/Time-to-Event_Repeatability/blob/main/R/rptRsurv.R.

Examples

if (FALSE) { # \dontrun{
## Fit a tiny example
set.seed(1)
s <- simulate_site_trait(
  n_sites = 30, n_species = 4, n_traits = 3,
  mean_species_per_site = 4,
  Lambda_B = matrix(c(0.9, 0.4, -0.3), 3, 1),
  S_B = c(0.20, 0.15, 0.10),
  beta = matrix(0, 3, 2), seed = 1
)
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 1) +
          unique(0 + trait | site),
  data = s$data
)

## Profile-likelihood CIs for the between-site covariance matrix (default)
ci_B <- confint(fit, parm = "Sigma_B")
ci_B

## Bootstrap CIs (slow, more accurate for non-monotone cases)
ci_B_boot <- confint(fit, parm = "Sigma_B", method = "bootstrap",
                     nsim = 200, seed = 42)

## Wald CIs for fixed effects
confint(fit)
} # }

Confidence intervals on fixed effects of a `gllvmTMB_multi` fit