Skip to contents

Per-trait repeatability with confidence intervals

Source: R/extract-repeatability.R
extract_repeatability.Rd

Returns the per-trait repeatability $$R_t = v_{B,t} / (v_{B,t} + v_{W,t}),$$ where $$v_{B,t} = [\Lambda_B\Lambda_B^\top]_{tt} + \sigma^2_{B,t}$$ and $$v_{W,t} = [\Lambda_W\Lambda_W^\top]_{tt} + \sigma^2_{W,t} + \sigma^2_{d,t}.$$ The first two terms include the shared latent and diagonal companion variance at the unit and observation tiers; \(\sigma^2_{d,t}\) is the family-specific link residual used for non-Gaussian traits. The function is intended for a fit returned by gllvmTMB() with the relevant ordinary unit and observation-level components. Also known as the intraclass correlation coefficient (ICC) at the unit level.

Usage

extract_repeatability(
  fit,
  level = 0.95,
  method = c("wald", "profile", "bootstrap"),
  nsim = 500L,
  seed = NULL
)

Arguments

fit

A fit returned by gllvmTMB. A bootstrap_Sigma object is also accepted when it contains an ICC_site summary; in that case the function reuses the stored point estimates and percentile bounds rather than refitting.

level

Confidence level. Default 0.95.

method

One of "wald" (default), "profile", or "bootstrap". "profile" is accepted only for backwards compatibility and aborts because a defensible profile interval for canonical full-covariance repeatability is not available.

nsim

Number of bootstrap replicates when method = "bootstrap". Default 500.

seed

Optional RNG seed for the bootstrap.

Value

A data frame with columns trait, R (point estimate), lower, upper, method.

Method choice

  • "wald" (default): Gaussian-approximation CI via the delta method on log(v_B) - log(v_W), transformed with plogis().

  • "profile": withdrawn. It aborts rather than silently substituting a different interval method or estimand.

  • "bootstrap": parametric bootstrap via bootstrap_Sigma().

References

Nakagawa, S. & Schielzeth, H. (2010) Repeatability for Gaussian and non-Gaussian data: a practical guide for biologists. Biological Reviews 85, 935-956. doi:10.1111/j.1469-185X.2010.00141.x

See also

extract_communality, extract_correlations, extract_phylo_signal, confint.gllvmTMB_multi.

Examples

if (FALSE) { # \dontrun{
fit <- gllvmTMB(
  value ~ 0 + trait +
          latent(0 + trait | site, d = 1) +
          latent(0 + trait | site_species, d = 1),
  data     = df,
  trait    = "trait",
  unit     = "site",
  unit_obs = "site_species"
)
extract_repeatability(fit)
boot <- bootstrap_Sigma(fit, n_boot = 50, level = c("unit", "unit_obs"),
                        what = "ICC", progress = FALSE)
extract_repeatability(boot)
} # }