% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/method-waic.R
\name{waic}
\alias{waic}
\alias{waic.INLAvaan}
\alias{waic.inlavaan_internal}
\title{Widely Applicable Information Criterion for INLAvaan Models}
\usage{
waic(x, ...)

\method{waic}{INLAvaan}(
  x,
  type = c("auto", "loso", "loco"),
  units = NULL,
  nsamp = NULL,
  cores = NULL,
  verbose = FALSE,
  ...
)

\method{waic}{inlavaan_internal}(
  x,
  type = c("auto", "loso", "loco"),
  units = NULL,
  nsamp = NULL,
  cores = NULL,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{x}{A fitted \link{INLAvaan} object (or its \code{inlavaan_internal} list).}

\item{...}{Not used.}

\item{type}{Unit type: \code{"auto"} (default) resolves to per-subject for
single-level models and per-cluster (marginal WAIC) for two-level
models. \code{"loso"} on a two-level model scores the conditional
(leave-one-unit-out) WAIC instead (with a warning; see Details);
\code{"loco"} cannot be forced on a model without clusters.}

\item{units}{Optional integer vector of unit indices to score; defaults
to all units.}

\item{nsamp}{Number of posterior draws. Defaults to the \code{nsamp} used when
fitting the model.}

\item{cores}{Number of cores for evaluating draws. The default \code{NULL}
runs serially; parallelism must be requested explicitly.}

\item{verbose}{Logical; print progress (default \code{FALSE}).}
}
\value{
An object of class \code{inlavaan_waic}: a list with \code{per_unit}
(pointwise \code{lpd}, \code{p_waic}, \code{elpd_waic}, with the same \code{unit}/\code{group}
identification as \code{\link[=loo]{loo()}}), \code{estimates} (matrix with rows
\code{elpd_waic}, \code{p_waic}, \code{waic} and columns \code{Estimate}, \code{SE}), \code{type},
\code{n_units}, \code{n_groups}, and \code{nsamp}.
}
\description{
Computes the WAIC of a fitted \link{INLAvaan} model from unit log-likelihoods
evaluated over posterior draws. Single-level models are scored per
subject; two-level models are scored per cluster by default, matching the
units used by \code{\link[=loo]{loo()}}. For a two-level model \code{type = "loso"} instead
scores the \emph{conditional} (leave-one-unit-out) WAIC; see Details.
}
\details{
For each posterior draw \eqn{\theta_s} (drawn with the same copula
sampler used for the fit's posterior summaries) and unit \eqn{u}, the
log-likelihood \eqn{\log p(y_u \mid \theta_s)} is evaluated; then
\eqn{\mathrm{lpd}_u = \log \tfrac{1}{S}\sum_s p(y_u \mid \theta_s)},
\eqn{p_{\mathrm{waic},u} = \mathrm{var}_s \log p(y_u \mid \theta_s)}, and
\eqn{\mathrm{elpd}_{\mathrm{waic}} = \sum_u (\mathrm{lpd}_u -
p_{\mathrm{waic},u})} with \eqn{\mathrm{WAIC} = -2\,
\mathrm{elpd}_{\mathrm{waic}}}. Unlike \code{\link[=loo]{loo()}}, this is a sampling-based
estimate: results vary with the random draws, and units with
\eqn{p_{\mathrm{waic},u} > 0.4} trigger a reliability warning (also
annotated when printing). The same model restrictions as \code{\link[=loo]{loo()}} apply,
and so does the flavour rule: fits with \code{fixed.x = TRUE} are scored
conditionally on the exogenous covariates, fits with \code{fixed.x = FALSE}
jointly (see \code{\link[=loo]{loo()}}).

\strong{Marginal vs conditional WAIC (two-level models).} The default
per-cluster scoring is the \emph{marginal} WAIC, which corresponds to
leave-one-cluster-out cross-validation -- prediction for a \emph{new} cluster.
Setting \code{type = "loso"} scores the \emph{conditional} WAIC, corresponding to
leave-one-unit-out -- prediction for a new observation within an
\emph{observed} cluster (each row contributes the conditional density of its
observed entries given the rest of its cluster). The two answer different
questions and are easily conflated (Merkle, Furr & Rabe-Hesketh, 2019);
the per-cluster marginal is the usual model-comparison target, so it is
the default, and \code{type = "loso"} warns. This matches \code{loo(type = "loso")}
-- the two compute the same estimand by sampling and by Taylor expansion.

Under the default \code{test = "standard"}, \code{\link[=inlavaan]{inlavaan()}} computes the WAIC at
fit time by reusing the posterior draws the fit already produced (when
the model is supported and \code{nsamp >= 100}), and
stores it with the fit: \code{waic(fit)} then returns the stored result when
called with default arguments, and \code{\link[=fitmeasures]{fitmeasures()}} reports \code{waic},
\code{p_waic}, \code{se_waic} as part of \code{"all"} for free. If the \code{loo} package is
attached it masks this generic, but dispatch on INLAvaan objects
continues to work.
}
\examples{
\donttest{
HS.model <- "
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9
"
utils::data("HolzingerSwineford1939", package = "lavaan")
fit <- acfa(HS.model, HolzingerSwineford1939, meanstructure = TRUE)
waic(fit)
}

}
\seealso{
\code{\link[=loo]{loo()}}, \code{\link[=fitmeasures]{fitmeasures()}}
}
