Skip to contents

Confidence intervals for a fitted gllvmTMB model

Source: R/z-confint-gllvmTMB.R
confint.gllvmTMB_multi.Rd

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,
  ...
)

Arguments

object

A fit returned by gllvmTMB().

parm

One of:

  • "Sigma_unit" – between-unit trait covariance matrix.

  • "Sigma_unit_obs" – within-unit trait covariance matrix.

  • "Sigma_cluster" and "Sigma_cluster2" – diagonal covariance matrices for the first and second extra grouping tiers. "profile" and "wald" return diagonal variance intervals; "bootstrap" is intentionally blocked until a simulate-refit calibration gate is added for these tiers.

  • "sigma_phy" – per-trait phylogenetic standard deviations.

  • Legacy aliases "Sigma_B" and "Sigma_W", retained for existing scripts.

  • "Lambda" (all free entries of Lambda_unit), "Lambda:i,j" (single entry), or "Lambda:i,j;k,l" (multiple entries, semicolon-separated). Routes to loading_ci() / loading_profile(). For these tokens the method choices are c("wald", "wald_asym", "profile") with default "wald".

  • "icc" (all traits), "icc:<trait_name>" (one trait by name), "icc:<t1>;<t2>" (multiple by name), or "icc:[1,3]" (1-based trait indices). Routes to extract_repeatability() with "wald" (default) or "bootstrap". The former profile token is withdrawn because it estimated a diagonal-only ratio rather than canonical full-covariance repeatability.

  • "phylo_signal" / "phylo_signal:<trait>" etc. – same grammar as "icc". Routes to profile_ci_phylo_signal() for "profile" and the companion Wald/bootstrap helpers for "wald" / "bootstrap". For multi-component fits, "profile" falls back to numerical Wald bounds with an explicit method label until the full fix-and-refit profile is implemented.

  • "communality:<tier>" (one tier, all traits) or "communality:<tier>:<trait>" (one tier, one trait). Tier is one of "unit" / "unit_obs" / "phy" (legacy "B" / "W"). Defaults to Wald; bootstrap is available explicitly. The nonlinear profile prototype is withheld.

  • "rho:<tier>:i,j" (one pair) or "rho:<tier>:i,j;k,l" (multiple pairs). Tier is one of "unit" / "unit_slope" / "unit_obs" / "phy" / "spatial" (legacy "B" / "W" / "spde"). "unit_slope" indexes the augmented 2T coefficient vector by numeric position and is currently a not currently an interval target. Other tiers route to extract_correlations() ("fisher-z" / "wald" / "bootstrap"); Fisher-z is the default for this confint() token. The nonlinear profile prototype is withheld.

  • "proportion" (all components, all traits), "proportion:<component>" (one component, all traits), "proportion:<component>:<trait>" (one (component, trait)), "proportion:<component>:<t1>;<t2>" (one component, multiple traits), or "proportion:<c1>;<c2>" (multiple components). Components are by name ("shared_unit", "unique_unit", "shared_unit_obs", "unique_unit_obs", "unique_cluster", "unique_cluster2", "shared_phy", "unique_phy", "link_residual"). Defaults to Wald; bootstrap is available explicitly. The nonlinear profile prototype is withheld.

  • 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". For parm = "Lambda..." the accepted methods are c("wald", "wald_asym", "profile") with default "wald" (matching the base R confint() convention).

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

  • Sigma path – a data.frame with columns parameter (character, e.g. "Sigma_unit[t1,t1]"), estimate (point estimate), lower, upper, and method (the method used for that row, or "structural_zero" for off-diagonal entries that are fixed at zero by a diagonal-only tier). The parameter prefix follows the requested parm, so legacy calls still return legacy "Sigma_B[...]" or "Sigma_W[...]" labels.

  • Lambda path – a data.frame with columns parameter (e.g. "Lambda[trait_1,LV1]"), estimate, lower, upper, method, pd_hessian, and ci_status. When pdHess = FALSE on a Wald path, lower/upper are NA and ci_status flags the reason).

  • Derived-quantity path ("icc" / "phylo_signal" / "communality" / "rho" / "proportion") – a numeric matrix with two columns named after the requested level (e.g. "2.5 %" / "97.5 %") and rownames identifying the entry, e.g. "icc:trait_1", "communality:unit:trait_1", "rho:unit:1,2", or "proportion:shared_unit:trait_1".

  • 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" (default): profile-likelihood bounds via TMB::tmbprofile() + stats::uniroot(). A successful numerical route can represent asymmetric likelihood shape, but its reference distribution and coverage remain target-specific.

  • method = "wald": Gaussian-approximation CIs from sd_report. Fastest; poor near boundaries.

  • method = "bootstrap": fitted-model parametric bootstrap via bootstrap_Sigma(). Slowest; inspect failed refits, Monte Carlo resolution, and whether simulation covers every active model component.

Fixed-effect and direct-parameter intervals use the requested method where supported, and Sigma-matrix intervals accept canonical parm = "Sigma_unit" / "Sigma_unit_obs" names, diagonal extra-grouping "Sigma_cluster" / "Sigma_cluster2" names, plus legacy "Sigma_B" / "Sigma_W" aliases. Profile intervals for full decomposed Sigma entries fall back to bootstrap because those entries are nonlinear functions of rotation-equivalent loadings and diagonal \(\Psi\). Non-Gaussian bootstrap and broader derived-target coverage are not universally calibrated; inspect the returned method and the target-specific article before reporting bounds.

Main parm-class dispatch paths:

  • Sigma matrices – when parm is one of "Sigma_unit", "Sigma_unit_obs", "Sigma_cluster", "Sigma_cluster2", or "sigma_phy" (legacy aliases "Sigma_B" and "Sigma_W" still work), returns a tidy data.frame with columns parameter, estimate, lower, upper, method. Profile is computed element-wise via TMB::tmbprofile() for the diagonal entries; structural-zero off-diagonal entries in pure-diagonal tiers are labelled "structural_zero"; off-diagonals for reduced-rank tiers fall back to bootstrap (full Sigma 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.

  • Lambda and derived summaries – "Lambda...", "icc...", "phylo_signal...", "communality...", "rho...", and "proportion..." tokens dispatch to their corresponding direct-profile, Wald, or bootstrap helper where that route is implemented. Nonlinear penalty-profile prototypes are withheld.

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.

See also

bootstrap_Sigma(), extract_Sigma(), extract_correlations(), extract_repeatability(), extract_communality(), tmbprofile_wrapper(), loading_ci(), loading_profile(), gllvmTMB().

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),
  psi_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),
  data  = s$data,
  trait = "trait",
  unit  = "site"
)

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

## Bootstrap route (slow; inspect failed refits and target calibration)
ci_unit_boot <- confint(fit, parm = "Sigma_unit", method = "bootstrap",
                        nsim = 200, seed = 42)

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