Skip to contents

Migration guide

loo package developers

2026-11-11

Source: vignettes/migration-guide.Rmd
migration-guide.Rmd

Introduction

This vignette documents API changes for loo 3.0.0. It lists deprecated functions, their replacements, and what is planned for removal in the major release.

Status Meaning
Deprecated Still works but emits a warning (via .Deprecated()). Use the replacement for new code.
Current Supported API; use for new code.
Planned removal Scheduled to be deleted in loo 3.0.0.

Release notes appear in NEWS.md. Deprecated functions are listed under Deprecated functions on the package website.

Deprecated source files

File Status Replacement / notes
R/elpd.R Deprecated measure_elpd() in R/pred_measure-builtin.R
R/crps.R Deprecated measure_rps(), measure_srps(), loo_pred_measure()
R/loo_predictive_metric.R Deprecated loo_pred_measure(), measure_*()
R/pred_measure.R Current *_pred_measure() entry points
R/pred_measure-compute.R Current Internal orchestration
R/pred_measure-helpers.R Current Validation and helpers
R/pred_measure-builtin.R Current measure_*() implementations
R/compare.R Deprecated (removal in 3.0.0) model_compare() in R/model_compare.R
R/psislw.R Deprecated (removal in 3.0.0) psis() in R/psis.R (since 2.0.0)
R/loo_compare.R Deprecated model_compare() in R/model_compare.R
R/model_compare.R Current Model comparison
R/loo.R, R/psis.R, R/waic.R Current Core LOO / PSIS / WAIC

Function migration tables

Expected log predictive density

Deprecated Replacement Since Planned removal
elpd() measure_elpd() 3.0.0

Return type change: elpd() returns class "elpd_generic" with elpd and ic columns in pointwise. measure_elpd() returns class "measure".

# Deprecated
elpd(log_lik_matrix)

# Current
measure_elpd(log_lik_matrix)

Scoring rules (CRPS / SCRPS)

Deprecated Replacement Since Planned removal
crps(x, x2, y) measure_rps(y, ypred = x) 3.0.0
scrps(x, x2, y) measure_srps(y, ypred = x) 3.0.0
loo_crps(...) loo_pred_measure(..., measures = "rps") 3.0.0
loo_scrps(...) loo_pred_measure(..., measures = "srps") 3.0.0

API change: deprecated functions require two draw matrices (x, x2) and use a permutation-based estimator. The replacement uses one draw matrix (ypred) and a PWM estimator. Results are not identical.

# Deprecated
crps(ypred1, ypred2, y = y)

# Current
measure_rps(y = y, ypred = ypred1)

Leave-one-out predictive metrics

Deprecated Replacement Since Planned removal
loo_predictive_metric() loo_pred_measure() 3.0.0

Argument mapping:

Old (loo_predictive_metric) New (loo_pred_measure)
x (predictions) mupred
log_lik via loo(..., save_psis = TRUE) or ylp + psis_object
metric = "mae" measures = "mae"
metric = "balanced_acc" measures = "bacc" 
# Deprecated
loo_predictive_metric(x = mupred, y = y, log_lik = ll, metric = "mae")

# Current
loo_fit <- loo(ll, save_psis = TRUE)
loo_pred_measure(loo = loo_fit, y = y, mupred = mupred, measures = "mae")

Current predictive performance API (3.0.0)

Workflow entry points

Function Evaluation mode Source file
insample_pred_measure() In-sample pred_measure.R
loo_pred_measure() PSIS-LOO pred_measure.R
kfold_pred_measure() K-fold CV pred_measure.R
test_pred_measure() Holdout test set pred_measure.R
pred_measure() Add measures incrementally pred_measure.R

Built-in measures

Pass short names to the measures argument, or call standalone functions:

measures = Function Source file
"elpd" measure_elpd() pred_measure-builtin.R
"mlpd" measure_mlpd() pred_measure-builtin.R
"ic" measure_ic() pred_measure-builtin.R
"mae" measure_mae() pred_measure-builtin.R
"mse" measure_mse() pred_measure-builtin.R
"rmse" measure_rmse() pred_measure-builtin.R
"r2" measure_r2() pred_measure-builtin.R
"acc" measure_acc() pred_measure-builtin.R
"bacc" measure_bacc() pred_measure-builtin.R
"rps" measure_rps() pred_measure-builtin.R
"srps" measure_srps() pred_measure-builtin.R

List all registered built-in names:

measure_brier() is exported but not yet registered in supported_measures_list(). ## Model comparison

Deprecated Replacement Since Planned removal
compare() model_compare() 2.0.0 3.0.0
loo_compare() model_compare() 3.0.0 TBD

compare() returns a vector or matrix with class "compare.loo". model_compare() returns a data.frame with additional diagnostic columns. See ?model_compare for the current output format.

# Deprecated
compare(loo1, loo2)

# Current
model_compare(loo1, loo2)

loo_compare() is now model_compare()

loo_compare() has been renamed to model_compare(), which better reflects that it compares models evaluated by leave-one-out CV, k-fold CV, a held-out test set, or in-sample scores.

loo_compare() is deprecated but still works, and is still an exported generic, so loo_compare methods registered by other packages (for example loo_compare.brmsfit in brms and loo_compare.stanreg in rstanarm) keep dispatching. It is frozen at its previous behavior: it compares "loo", "waic", and "kfold" objects on ELPD only, and returns exactly what model_compare() returns for those inputs. Everything added in 3.0.0 — the pred_measure sources and custom_measure() — is available only through model_compare().

# Deprecated, but still returns the same table
loo_compare(loo1, loo2)

# Current
model_compare(loo1, loo2)

# Only available via model_compare()
model_compare(kfold_pm1, kfold_pm2)
model_compare(test_pm1, test_pm2)
model_compare(loo_pm1, loo_pm2)

PSIS importance sampling

Deprecated Replacement Since Planned removal
psislw() psis() 2.0.0 3.0.0
options(loo.cores = ...) options(mc.cores = ...) or cores argument 2.0.0 
# Deprecated
psislw(-log_lik_matrix)

# Current
psis(-log_lik_matrix)

Accessing estimates from loo and waic objects

Direct extraction of summary estimates via $, [, or [[ on loo objects has been deprecated since loo 2.x. Use the estimates component instead.

Deprecated Replacement Since Planned removal
x$elpd_loo, x$looic, etc. x$estimates["elpd_loo", "Estimate"] 2.x
x["elpd_loo"], x[["elpd_loo"]] x$estimates[...] 2.x

The same pattern applies to waic objects (elpd_waic, waic, etc.).

Argument renames

Function Deprecated Replacement Since
psis_approximate_posterior() log_q log_g 2.x

Planned removals in 3.0.0

The following are targeted for removal in loo 3.0.0:

The deprecated option options(loo.cores = ...) remains for backward compatibility until a separate removal decision is made.