% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compare.R, R/method-anova.R
\name{compare}
\alias{compare}
\alias{compare,INLAvaan-method}
\alias{anova}
\alias{anova,INLAvaan-method}
\title{Compare Bayesian Models Fitted with INLAvaan}
\usage{
compare(x, y, ..., fit.measures = NULL, loo = FALSE)

\S4method{compare}{INLAvaan}(x, y, ..., fit.measures = NULL, loo = FALSE)

\S4method{anova}{INLAvaan}(object, ...)
}
\arguments{
\item{x}{An \link{INLAvaan} (or \code{inlavaan_internal}) object used as the
\strong{baseline} (null) model. It is included in the comparison table and
passed to \link[lavaan:fitMeasures]{fitMeasures()} for incremental indices.}

\item{y, ...}{One or more \link{INLAvaan} (or \code{inlavaan_internal}) objects to
compare against the baseline.}

\item{fit.measures}{Character vector of additional fit-measure names to
include (e.g. \code{"BRMSEA"}, \code{"BCFI"}). Use \code{"all"} to include every
measure returned by \link[lavaan:fitMeasures]{fitMeasures()}. The default
(\code{NULL}) shows only the core comparison statistics.}

\item{loo}{Logical; if \code{TRUE}, compare models by leave-one-out
cross-validation with paired standard errors (see Details). Defaults to
\code{FALSE}.}

\item{object}{An \link{INLAvaan} object (the \code{anova()} method, which is disabled
and redirects to \code{compare()}).}
}
\value{
A data frame of class \code{compare.inlavaan_internal} containing model
fit statistics, sorted by descending marginal log-likelihood (or by
descending ELPD when \code{loo = TRUE}).
}
\description{
Compare two or more Bayesian SEM fitted with INLAvaan, reporting model-fit
statistics and (optionally) fit indices side by side.
}
\details{
The first argument \code{x} serves as the \strong{baseline} (null) model.
All models (including the baseline) appear in the comparison table. The
baseline is also passed to \link[lavaan:fitMeasures]{fitMeasures()} when
incremental fit indices (BCFI, BTLI, BNFI) are requested via
\code{fit.measures}.

The default table always includes:
\itemize{
\item \strong{npar}: Number of free parameters.
\item \strong{Marg.Loglik}: Approximated marginal log-likelihood.
\item \strong{logBF}: Natural-log Bayes factor relative to the best model.
\item \strong{DIC} / \strong{pD}: Deviance Information Criterion and effective number
of parameters (when \code{test != "none"} was used during fitting).
}

Set \code{fit.measures} to a character vector of measure names (anything
returned by \link[lavaan:fitMeasures]{fitMeasures()}) to append extra columns.
Use \code{fit.measures = "all"} to include every available measure.

Set \code{loo = TRUE} to compare models by leave-one-out cross-validation
(see \code{\link[=loo]{loo()}}). This appends \strong{ELPD} / \strong{SE} (the second-order Taylor
expected log predictive density and its standard error), \strong{p_loo}, and,
against the best-ELPD model, the difference \strong{elpd_diff} with its
\emph{paired} standard error \strong{se_diff} computed from the pointwise
contributions (the appropriate uncertainty for nested or same-data
comparisons). The table is then sorted by descending ELPD. All models
must be fitted to the same data with matching units; units are paired
by id rather than by row order, so fits that stack groups differently
-- a pooled fit against a multigroup fit, or multigroup fits with
different group orderings -- still pair up unit by unit. For
missing-data (FIML) fits, "the same data" also means the same observed
entries: each unit is scored on the entries it has, so comparisons
require identical missingness patterns across models. All models
must also share the
score flavour (see \code{\link[=loo]{loo()}}): mixing fits with modelled covariates
(\code{fixed.x = FALSE}, joint scores) and fixed covariates
(\code{fixed.x = TRUE}, conditional scores) is refused. Joint scores
additionally require identical variable sets across models, while
conditional scores require only matching outcome variables -- covariate
sets may differ, which is the covariate-selection setting. Stored LOO
results (\code{test = "loo"} or \code{\link[=add_loo]{add_loo()}}) are reused.

\code{anova()} is disabled for \code{INLAvaan} fits -- there is no direct Bayesian
analogue of the classical likelihood-ratio test -- and points here instead.
}
\examples{
\donttest{
# Model comparison on multigroup analysis (measurement invariance)
HS.model <- "
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9
"
utils::data("HolzingerSwineford1939", package = "lavaan")

# Configural invariance
fit1 <- acfa(HS.model, data = HolzingerSwineford1939, group = "school")

# Weak invariance
fit2 <- acfa(
  HS.model,
  data = HolzingerSwineford1939,
  group = "school",
  group.equal = "loadings"
)

# Strong invariance
fit3 <- acfa(
  HS.model,
  data = HolzingerSwineford1939,
  group = "school",
  group.equal = c("intercepts", "loadings")
)

# Compare models (fit1 = configural = baseline, always first argument)
compare(fit1, fit2, fit3)

# With extra fit measures
compare(fit1, fit2, fit.measures = c("BRMSEA", "BMc"))

# With incremental indices (baseline = fit1, passed to fitMeasures())
compare(fit1, fit2, fit3, fit.measures = c("BCFI", "BTLI"))
}
}
\references{
\url{https://lavaan.ugent.be/tutorial/groups.html}
}
\seealso{
\code{\link[=fitmeasures]{fitmeasures()}}, \code{\link[=bfit_indices]{bfit_indices()}}
}
