compare_models: Compare models by information criteria

In tulpa: Templated Unified Library for Posterior Approximation in Bayesian Hierarchical Models

Compare models by information criteria

Description

Rank fitted models best-first by an information criterion. "waic" and "loo" use the native pointwise log-likelihood layer (tulpa_criteria() / tulpa_psis()) – WAIC and PSIS-LOO respectively, computed from each fit's ⁠[n_draws x n_obs]⁠ pointwise log-likelihood (fit$draws$log_lik), with no loo package dependency. "loglik" returns the (integrated) joint log-likelihood with the parameter count. A fit carrying no pointwise log-likelihood (a deterministic / point approximation) yields NA criterion columns rather than an error, so the table always has one row per model.

"wbic" ranks by wbic(), an estimate of each fit's negative log evidence, and needs every fit to carry its tempered draws (mode = "smc", control = list(wbic = TRUE)); a fit without them gets an NA row.

Usage

compare_models(..., criterion = c("waic", "loo", "wbic", "loglik"))

Arguments

...	Named tulpa_fit objects.
criterion	"waic" (default), "loo", "wbic", or "loglik".

Value

A data frame. For "wbic" (ranked best-first): model, wbic, delta (WBIC gap to the best model, >= 0), and weight (exp(-delta) normalized: the posterior model probability under equal prior model weights, with each log evidence read off its WBIC). For "loglik": model, n_params, logLik, quantity and conditioned_on (which log-scale quantity logLik() reports, and the hyperparameters it holds fixed; fits that disagree on either are refused rather than ranked). For "waic" / "loo" (ranked best-first): model, elpd, se_elpd, p_eff, ic (-2 * elpd), delta (elpd gap to the best model), se_diff (SE of that pointwise elpd difference), and weight (the Akaike-style weight on the criterion).

See Also

model_average() for model-averaged predictions, tulpa_criteria() and tulpa_psis() for the native criteria layer.

Examples

set.seed(1)
df <- data.frame(x = rnorm(120))
df$y <- rpois(120, exp(0.4 + 0.5 * df$x))
f1 <- tulpa(y ~ x, data = df, family = "poisson")
f2 <- tulpa(y ~ 1, data = df, family = "poisson")
compare_models(full = f1, null = f2, criterion = "waic")

tulpa documentation built on Oct. 19, 2026, 5:09 p.m.