% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit_stats.R
\name{fit_stats}
\alias{fit_stats}
\alias{fit_stats.vbfa}
\alias{fit_stats.vbmimic}
\alias{fit_stats.vbpm_fit}
\title{Fit statistics for vbpm models}
\usage{
fit_stats(object, ...)

\method{fit_stats}{vbfa}(
  object,
  Y = NULL,
  Q = object$Q,
  tau = 0.5,
  gamma = 0.5,
  orthogonal = NULL,
  rank_adjust = FALSE,
  rank_max_J = 100,
  ...
)

\method{fit_stats}{vbmimic}(object, Y = NULL, Q = NULL, tau = 0.5, ...)

\method{fit_stats}{vbpm_fit}(object, ...)
}
\arguments{
\item{object}{A fitted \code{vbpm_fit} object.}

\item{...}{Further arguments passed to methods. Unused by the methods
supplied with the package.}

\item{Y}{The \verb{N x J} data matrix the model was fit to.}

\item{Q}{The \verb{J x K} loading design matrix used in the fit.}

\item{tau}{Hard-selection threshold on the posterior inclusion probability
(default \code{0.5}).}

\item{gamma}{Reserved (extended BIC tuning); currently unused in the
returned vector.}

\item{orthogonal}{Logical; whether the fit is an orthogonal (bifactor)
model, in which case factor correlations are not free parameters. The
default \code{NULL} reads the setting from the fit object itself, which is the
recommended use. Supplying a value that contradicts the fit raises an
error rather than silently miscounting parameters.}

\item{rank_adjust}{Logical; if \code{TRUE}, compute the effective parameter count
as the rank of the Jacobian of the model-implied covariance. This explicit
opt-in requires the suggested \code{numDeriv} package. The default \code{FALSE}
uses the nominal parameter count.}

\item{rank_max_J}{Largest number of observed variables for which an explicit
Jacobian-rank calculation is allowed (default \code{100}). If \code{rank_adjust = TRUE} and \code{J} exceeds this value, the method errors rather than silently
substituting the nominal count.}
}
\value{
An object of class \code{vbpm_fit_stats} (a named numeric vector) with
\code{t_nom}, \code{t}, \code{t_S} (parameter counts), \code{RMSEA}, \code{SRMR}, \code{CFI}, \code{TLI},
\code{AIC}, \code{BIC} (hard selection), \code{AIC_S}, \code{BIC_S} (soft selection), \code{ELBO},
and \code{objective}. The last is the model's comparability score: equal to
\code{ELBO} for a diagonal fit, and the terminal VECM objective under local
dependence, where \code{ELBO} is \code{NA}. It is comparable only across fits
sharing the \code{objective_type} attribute, which is also attached.

The \code{vbmimic} method returns the same shape with \code{n_active_coef} in place
of a full soft count and typed \code{NA} elsewhere; see \code{\link[=vbmimic]{vbmimic()}}.
}
\description{
Computes structural-equation-model fit statistics for a fitted \code{\link[=vbfa]{vbfa()}}
object under hard selection (an unspecified loading counts as active when its
posterior inclusion probability is at least \code{tau}). Absolute indices
(RMSEA, SRMR, CFI, TLI) and information criteria (AIC, BIC) are returned,
together with the model's ELBO.
}
\examples{
sim <- sim_fa(N = 300, K = 3, ipf = 6, lam = .7, lac = .3, rseed = 1)
Q <- matrix(-1L, ncol(sim$dat), 3)
for (k in 1:3) { a <- which(rep(1:3, each = 6) == k)[1:2]
                 Q[a, ] <- 0L; Q[a, k] <- 1L }
fit <- vbfa(sim$dat, Q)
round(fit_stats(fit), 3)

\donttest{
## bifactor: orthogonal is read from the fit object, so the same call works
Qb <- cbind(1L, Q)
fb <- vbfa(sim$dat, Qb, orthogonal = TRUE)
round(fit_stats(fb), 3)
}

}
\references{
Chen, J., & Jin, Y. (2026). Recovering latent structures after variational
Bayesian variable selection: Fit assessment and factor-number selection in
partially exploratory factor analysis. \emph{arXiv preprint} arXiv:2607.07159.

Jin, Y., & Chen, J. (2025). Regularized variational approximation for
partially confirmatory factor analysis. \emph{Structural Equation Modeling: A
Multidisciplinary Journal}, 32(3), 437-449.
\doi{10.1080/10705511.2024.2432612}
}
\seealso{
\code{\link[=vbfa]{vbfa()}}, \code{\link[=pefa]{pefa()}}
}
