Fit standard longitudinal comparator models for adoption benchmarks — benchmark_standard

benchmark_standard_models() is an opt-in scaffold for comparing gamlss.longitudinal with models users already know. It is intentionally narrow: optionally score an already-fitted primary model, fit common mean-model baselines, record whether they ran, and return timing, response-scale prediction metrics, and distributional diagnostics when the fitted model family supports them.

Usage

benchmark_standard_models(
  data,
  formula,
  subject_var,
  family = "gaussian",
  comparators = c("glm", "gee", "glmm", "gam", "gamm"),
  correlation = "exchangeable",
  add_subject_re_to_gamm = TRUE,
  add_subject_re_to_gam = NULL,
  fit = NULL,
  fit_name = "gamlss.longitudinal",
  distributional_metrics = TRUE,
  truth_family = NULL,
  quantile_prob = 0.9,
  interval_level = 0.95,
  ...
)

Arguments

data: Long-format data frame.
formula: Mean-model formula used by the comparator models.
subject_var: Subject identifier column.
family: A base R family object or one of "gaussian", "poisson", "binomial", or "gamma".
comparators: Character vector containing any of "glm", "gee", "glmm", "gam", "gamm", and "glmmTMB".
correlation: Working correlation passed to geepack::geeglm().
add_subject_re_to_gamm: Logical; add s(subject, bs = "re") to the GAMM comparator.
add_subject_re_to_gam: Deprecated alias for add_subject_re_to_gamm.
fit: Optional already-fitted primary model to score beside the standard comparators. For a gamlss.longitudinal fit, response-mean predictions are obtained with predict(fit, newdata = data, type = "mean"); quantile, probability, PIT, density, and interval metrics still use the fitted distribution.
fit_name: Label used for the supplied fit row.
distributional_metrics: Logical; compute interval coverage, PIT calibration, tail-frequency diagnostics, and truth-aware quantile/tail metrics when enough information is available.
truth_family: Optional gamlss.dist family name used to derive true quantiles from true_* columns. Defaults are inferred from family.
quantile_prob: Probability used for the benchmark quantile and upper tail metrics.
interval_level: Prediction interval level used for empirical coverage.
...: Additional arguments passed to each comparator fit.

Value

An object of class gamlss_longitudinal_benchmark with results, model_status, fits, coefficients, and interpretation components. The coefficients component contains mu coefficient estimates and uncertainty comparisons for fixed/parametric terms available across the fitted models.