% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/loo.R
\name{add_loo.brma}
\alias{add_loo.brma}
\alias{add_loo}
\title{Add LOO-PSIS to brma Objects}
\usage{
\method{add_loo}{brma}(object, unit = "estimate", r_eff = NULL, parallel = FALSE, ...)
}
\arguments{
\item{object}{a brma model object.}

\item{unit}{output/deletion unit. \code{"estimate"} computes one contribution
per effect-size estimate. \code{"cluster"} computes one contribution per
cluster and is available only for multilevel models.}

\item{r_eff}{optional vector of relative effective sample sizes. If not
provided, it is computed from the log-likelihood values.}

\item{parallel}{Logical. If \code{TRUE}, \code{loo::relative_eff()} and
\code{loo::loo()} use \code{RoBMA.get_option("max_cores")}. Log-likelihood
construction is unchanged. If \code{FALSE}, those computations use one core.}

\item{...}{additional arguments (currently ignored).}
}
\value{
The brma object with the LOO result stored in
\code{object[["loo"]][[unit]]}.
}
\description{
Compute approximate leave-one-out cross-validation (LOO-CV)
using Pareto smoothed importance sampling (PSIS) for brma model objects
and store the result in the object.
}
\details{
With \code{unit = "estimate"}, LOO-CV is computed with one contribution per
effect-size estimate. For binomial and Poisson models, each pair of counts
(ai/ci or x1i/x2i) that defines a single effect size estimate is treated as
one contribution.

With \code{unit = "cluster"}, LOO-CV is computed with one joint contribution
per cluster. For unweighted normal models without selection this uses the
analytic cluster block covariance. Selection, data-weighted normal, and
GLMM models integrate the held-out cluster effect with Gauss-Hermite
quadrature.

For selection models, the LOO evaluates the weighted likelihood, conditioning
on the posterior omega samples.

The PSIS object is essential for model comparison via
\code{\link[loo]{loo_compare}} and is automatically saved in the loo result.
RoBMA stores target metadata so comparisons can reject mismatched data,
unit, or conditioning-depth targets.

\strong{Important for model comparison:} When comparing models via
\code{\link[loo]{loo_compare}}, the selection is based on expected
out-of-sample predictive performance. This evaluates how well models predict
\emph{new} observations, not how well they fit the observed data.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")
  fit <- bPET(yi = yi, vi = vi, data = dat.lehmann2018, measure = "SMD")

  fit <- add_loo(fit)
  loo_fit <- loo(fit)
  print(loo_fit)
  plot(loo_fit)
}
}

}
\references{
\insertCite{vehtari2017practical}{RoBMA}
\insertCite{vehtari2024pareto}{RoBMA}
}
\seealso{
\code{\link{loo.brma}}, \code{\link[loo]{loo}},
\code{\link[loo]{loo_compare}}, \code{\link[loo]{pareto_k_ids}}
}
