% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/loo_compare.R,
%   R/loo_compare.psis_loo_ss_list.R
\name{loo_compare}
\alias{loo_compare}
\alias{loo_compare.default}
\alias{print.compare.loo}
\alias{print.compare.loo_ss}
\title{Model comparison}
\usage{
loo_compare(x, ...)

\method{loo_compare}{default}(x, ...)

\method{print}{compare.loo}(x, ..., digits = 1, p_worse = TRUE)

\method{print}{compare.loo_ss}(x, ..., digits = 1)
}
\arguments{
\item{x}{An object of class \code{"loo"} or a list of such objects. If a list is
used then the list names will be used as the model names in the output. See
\strong{Examples}.}

\item{...}{Additional objects of class \code{"loo"}, if not passed in as a single
list.}

\item{digits}{For the print method only, the number of digits to use when
printing.}

\item{p_worse}{For the print method only, should we include the normal
approximation based probability of each model having worse performance than
the best model? The default is \code{TRUE}.}
}
\value{
A data frame with class \code{"compare.loo"} that has its own
print method. See the \strong{Details} and \strong{Examples} sections.
}
\description{
Compare fitted models based on \link[=loo-glossary]{ELPD}.
}
\details{
When comparing two fitted models, we can estimate the difference in their
expected predictive accuracy by the difference in
\code{\link[=loo-glossary]{elpd_loo}} or \code{elpd_waic} (or multiplied by \eqn{-2}, if
desired, to be on the deviance scale).
\subsection{\code{elpd_diff} and \code{se_diff}}{

When using \code{loo_compare()}, the returned data frame will have one row per
model and several columns of estimates. The values of
\code{\link[=loo-glossary]{elpd_diff}} and \code{\link[=loo-glossary]{se_diff}} are computed by
making pairwise comparisons between each model and the model with the
largest ELPD (the model listed first). Therefore, the first \code{elpd_diff}
value will always be \code{0} (i.e., the difference between the preferred model
and itself) and the rest of the values will be negative.

To compute the standard error of the difference in \link[=loo-glossary]{ELPD} ---
which should not be expected to equal the difference of the standard errors
--- we use a paired estimate to take advantage of the fact that the same
set of \eqn{N} data points was used to fit both models. These calculations
should be most useful when \eqn{N} is large, because then non-normality of
the distribution is not such an issue when estimating the uncertainty in
these sums. These standard errors, for all their flaws, should give a
better sense of uncertainty than what is obtained using the current
standard approach of comparing differences of deviances to a Chi-squared
distribution, a practice derived for Gaussian linear models or
asymptotically, and which only applies to nested models in any case.
}

\subsection{\code{p_worse}, \code{diag_diff}, and \code{diag_elpd}}{

The values in the \code{p_worse} column show the probability of each model
having worse ELPD than the best model. These probabilities are computed
with a normal approximation using the values from \code{elpd_diff} and
\code{se_diff}. Sivula et al. (2025) present the conditions when the normal
approximation used for SE and \code{se_diff} is good, and the column
\code{diag_diff} contains possible diagnostic messages:
\itemize{
\item \code{N < 100} (small data)
\item \verb{|elpd_diff| < 4} (models make similar predictions)
}

If either of these diagnostic messages is shown, the error distribution is
skewed or thick tailed and the normal approximation based on \code{elpd_diff}
and \code{se_diff} is not well calibrated. In that case, the probabilities
\code{p_worse} are likely to be too large. However, \code{elpd_diff} and \code{se_diff}
will still be indicative of the differences and uncertainties (for example,
if \verb{|elpd_diff|} is many times larger than \code{se_diff} the difference is quite
certain). In addition, if the model is not well specificed and there are
outliers, the error distribution can also be skewed or thick tailed and the
normal approximation is not well calibrated. Possible model misspecification
and outliers can be diagnosed with usual predictive checking methods.

The column \code{diag_elpd} shows the PSIS-LOO Pareto k diagnostic for the
pointwise ELPD computations for each model. If \verb{K k_psis > 0.7} is shown,
where \code{K} is the number of high Pareto k values in the PSIS
computation, then there may be significant bias in \code{elpd_diff} favoring
models with a large number of high Pareto k values.
}

\subsection{Warnings for many model comparisons}{

If more than \eqn{11} models are compared, we internally recompute the model
differences using the median model by ELPD as the baseline model. We then
estimate whether the differences in predictive performance are potentially
due to chance as described by McLatchie and Vehtari (2023). This will flag
a warning if it is deemed that there is a risk of over-fitting due to the
selection process. In that case users are recommended to avoid model
selection based on LOO-CV, and instead to favor model averaging/stacking or
projection predictive inference.
}
}
\examples{
# very artificial example, just for demonstration!
LL <- example_loglik_array()
loo1 <- loo(LL)     # should be worst model when compared
loo2 <- loo(LL + 1) # should be second best model when compared
loo3 <- loo(LL + 2) # should be best model when compared

comp <- loo_compare(loo1, loo2, loo3)
print(comp, digits = 2)

# can use a list of objects with custom names
# the names will be used in the output
loo_compare(list("apple" = loo1, "banana" = loo2, "cherry" = loo3))

\dontrun{
# works for waic (and kfold) too
loo_compare(waic(LL), waic(LL - 10))
}

}
\references{
Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical Bayesian model
evaluation using leave-one-out cross-validation and WAIC.
\emph{Statistics and Computing}. 27(5), 1413--1432. doi:10.1007/s11222-016-9696-4
(\href{https://link.springer.com/article/10.1007/s11222-016-9696-4}{journal version},
\href{https://arxiv.org/abs/1507.04544}{preprint arXiv:1507.04544}).

Vehtari, A., Simpson, D., Gelman, A., Yao, Y., and Gabry, J. (2024).
Pareto smoothed importance sampling. \emph{Journal of Machine Learning Research},
25(72):1-58.
\href{https://jmlr.org/papers/v25/19-556.html}{PDF}

Sivula, T, Magnusson, M., Matamoros A. A., and Vehtari, A. (2025).
Uncertainty in Bayesian leave-one-out cross-validation based model
comparison. \emph{Bayesian Analysis}. \doi{10.1214/25-BA1569}

McLatchie, Y., and Vehtari, A. (2024).  Efficient estimation and
correction of selection-induced bias with order statistics.
\emph{Statistics and Computing}. 34(132). \doi{10.1007/s11222-024-10442-4}
}
\seealso{
\itemize{
\item The \href{https://mc-stan.org/loo/articles/online-only/faq.html}{FAQ page} on
the \strong{loo} website for answers to frequently asked questions.
}
}
