calibrate_icc: Calibrate random-effect variance for a target ICC

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Calibrate random-effect variance for a target ICC

Description

Calibrate random-effect variance for a target ICC

Usage

calibrate_icc(
  icc,
  distribution = c("normal", "binary", "poisson", "gamma", "negative_binomial"),
  total_variance = NULL,
  within_variance = NULL,
  mean = NULL,
  dispersion = NULL
)

Arguments

icc	Target intraclass correlations.
distribution	Outcome distribution.
total_variance	Total normal-outcome variance.
within_variance	Within-cluster normal-outcome variance.
mean	Poisson or negative-binomial mean.
dispersion	Gamma or negative-binomial dispersion.

Value

A base data.frame with one row per target ICC and columns icc, distribution and random_effect_variance. Except for the normal total_variance case, which returns icc * total_variance, the variance is icc / (1 - icc) times a residual variance on the linear-predictor scale: within_variance for normal, the logistic latent variance pi^2 / 3 for binary, log(1 + 1 / mean) for poisson, trigamma(1 / dispersion) for gamma, and trigamma(1 / (1 / mean + dispersion)) for negative_binomial.

Examples

calibrate_icc(icc = 0.1, distribution = "normal", total_variance = 1)
calibrate_icc(icc = c(0.05, 0.1), distribution = "binary")

simulab documentation built on Oct. 15, 2026, 5:08 p.m.