% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/good.of.fit.R
\name{good.of.fit}
\alias{good.of.fit}
\title{Goodness-of-Fit Indices for Latent Probability Models}
\usage{
good.of.fit(
  par.vec,
  loglik.fun,
  prob.fun,
  response,
  npar,
  pi,
  pi.fun = NULL,
  alpha = 0.05,
  response.type = c("auto", "binary", "polytomous", "nominal", "ordinary"),
  response.K = NULL,
  bivariate.groups = NULL,
  nominal.groups = NULL,
  exclusive.groups = NULL,
  n.boot = 1000L,
  ...
)
}
\arguments{
\item{par.vec}{Numeric vector of free model parameters.}

\item{loglik.fun}{Function returning the fitted model log-likelihood.}

\item{prob.fun}{Function returning conditional response probabilities at
the latent support points.}

\item{response}{An \eqn{N \times I} response matrix (binary, polytomous,
or nominal coding depending on \code{response.type}).}

\item{npar}{Integer; number of free parameters in the model.}

\item{pi}{Numeric vector of latent support weights (summing to 1).}

\item{pi.fun}{Optional function returning latent support weights given
\code{par.vec} and \code{...}. If \code{NULL}, \code{pi} is used as-is.}

\item{alpha}{Tail probability for the RMSEA confidence interval.
Default \code{0.05} yields a 90\% CI (two-sided \eqn{2\alpha}).
Use \code{0.025} for 95\% or \code{0.005} for 99\%.}

\item{response.type}{Character string specifying the response coding:
\code{"auto"} (default; detects from probability dimensions),
\code{"binary"} (each column is a binary indicator),
\code{"polytomous"} (stacked category probabilities, requires
\code{response.K}), or \code{"nominal"} (expanded binary indicators
with mutually exclusive categories within groups, requires
\code{nominal.groups}).}

\item{response.K}{Integer vector of length \eqn{I} giving the number of
categories for each response column. Required when
\code{response.type = "polytomous"}.}

\item{bivariate.groups}{Optional integer vector of length \eqn{I};
response column pairs within the same group are excluded from bivariate
limited-information moments. Useful for forced-choice or testlet
designs where within-block comparisons are structural zeros.}

\item{nominal.groups}{Integer vector of length matching the number of
expanded binary indicators for \code{response.type = "nominal"}.
Indicators sharing the same group value belong to the same original
nominal item/block.}

\item{exclusive.groups}{Deprecated alias for \code{nominal.groups}.}

\item{n.boot}{Integer; number of bootstrap replicates for bootstrapped
diagnostics. Default \code{1000}; set to \code{0} to skip.}

\item{...}{Additional arguments passed to \code{loglik.fun},
\code{prob.fun}, and \code{pi.fun}.}
}
\value{
An object of class \code{"good.of.fit"} (a list). Key components:
\describe{
\item{\code{LogLik}, \code{deviance}}{Log-likelihood and deviance.}
\item{\code{npar}, \code{N}, \code{nitems}}{Parameter count, sample
size, number of items/indicators.}
\item{\code{AIC}, \code{AICc}, \code{BIC}, \code{CAIC}, \code{SABIC},
\code{HQIC}}{Information criteria.}
\item{\code{M2.value}, \code{df}, \code{p.value}}{M2 statistic, degrees
of freedom, asymptotic p-value.}
\item{\code{RMSEA2}, \code{RMSEA.lower}, \code{RMSEA.upper},
\code{RMSEA.CI.level}, \code{RMSEA.p.close}}{RMSEA estimate,
confidence interval, interval level, close-fit test p-value.}
\item{\code{SRMSR}, \code{RMSR}}{Standardized and raw root mean
square residuals.}
\item{\code{CFI}, \code{TLI}, \code{IFI}}{Incremental fit indices.}
\item{\code{McFadden.R2}, \code{Nagelkerke.R2}, \code{CoxSnell.R2},
\code{AldrichNelson.R2}, \code{VeallZimmermann.R2}}{Pseudo-\eqn{R^2}
measures.}
\item{\code{residuals}, \code{residuals.standardized},
\code{correlation.residuals}}{Residual vectors.}
\item{\code{moments.observed}, \code{moments.predicted}}{First- and
second-order marginal moments.}
\item{\code{q3.mean}, \code{q3.abs.max}, \code{q3.adjusted.abs.max},
\code{q3.p95}}{Yen's Q3 local dependence statistics.}
\item{\code{mean.max.posterior}, \code{median.max.posterior},
\code{min.max.posterior}}{Posterior classification diagnostics.}
\item{\code{null.LogLik}, \code{null.M2.value}, \code{null.df}}{Null
(independence) model diagnostics.}
\item{\code{LRT}, \code{LRT.df}, \code{LRT.p}}{Likelihood ratio test
against the null model.}
}
}
\description{
Computes a comprehensive suite of model-fit diagnostics for probability
models used in IRT, CDM, latent class, and forced-choice applications.
Indices include likelihood-based information criteria, limited-information
goodness-of-fit statistics (M2, RMSEA, SRMSR), incremental/comparative fit
indices (CFI, TLI), pseudo-\eqn{R^2} measures, residual diagnostics,
local-dependence statistics (Yen's Q3), and posterior classification
diagnostics.
}
\section{Likelihood and Information Criteria}{


Let \eqn{\ell = \log L(\hat{\boldsymbol{\psi}})} be the maximized
log-likelihood, \eqn{N} the sample size, and \eqn{p} the number of free
parameters (\code{npar}).

\strong{Deviance:}
\deqn{D = -2\ell}

\strong{AIC} (Akaike, 1974):
\deqn{\text{AIC} = D + 2p}

\strong{AICc} (Hurvich & Tsai, 1989), small-sample correction:
\deqn{\text{AICc} = \text{AIC} + \frac{2p(p+1)}{N - p - 1},
      \quad N > p + 1}

\strong{BIC} (Schwarz, 1978):
\deqn{\text{BIC} = D + p \log N}

\strong{CAIC} (Bozdogan, 1987), consistent AIC:
\deqn{\text{CAIC} = D + p(\log N + 1)}

\strong{SABIC} (Sclove, 1987), sample-size adjusted BIC:
\deqn{\text{SABIC} = D + p \log\bigl(\frac{N + 2}{24}\bigr)}

\strong{HQIC} (Hannan & Quinn, 1979):
\deqn{\text{HQIC} = D + 2p \log(\log N), \quad N > e}
}

\section{Limited-Information M2 Family}{


The limited-information framework (Maydeu-Olivares & Joe, 2005, 2006) uses
first- and second-order marginal moments rather than the full
\eqn{I}-way contingency table. This is essential for sparse high-dimensional
categorical responses where full-information tests break down.

Let \eqn{\mathbf{m}(\boldsymbol{\psi})} be the vector of model-implied
univariate and bivariate moments (dimension \eqn{M}), and let
\eqn{\hat{\boldsymbol{\Xi}}_2} be their asymptotic covariance matrix
under the model.

\strong{M2 statistic:}
\deqn{
  M_2 = N\,
  \mathbf{e}'\hat{\mathbf{C}}_2\mathbf{e},
}
where \eqn{\mathbf{e} = \mathbf{p} - \boldsymbol{\pi}(\hat{\boldsymbol{\psi}})}
is the vector of marginal residuals, and
\eqn{\hat{\mathbf{C}}_2 = \boldsymbol{\Delta}_c(\boldsymbol{\Delta}_c'
\hat{\boldsymbol{\Xi}}_2 \boldsymbol{\Delta}_c)^{-1}\boldsymbol{\Delta}_c'}
with \eqn{\boldsymbol{\Delta}_c} the orthogonal complement of the Jacobian
matrix \eqn{\boldsymbol{\Delta} = \partial\boldsymbol{\pi}/\partial\boldsymbol{\psi}'}.

Under correct model specification, \eqn{M_2 \sim \chi^2_{M - p}}
asymptotically.

\strong{RMSEA (Root Mean Square Error of Approximation):}
\deqn{
  \text{RMSEA} = \sqrt{\max\!\left(0,\; \frac{M_2 - df}{N \cdot df}\right)},
  \qquad df = M - p
}
Confidence intervals are obtained via non-central \eqn{\chi^2} inversion.
The close-fit test evaluates \eqn{H_0: \text{RMSEA} \le 0.05}.

\strong{SRMSR (Standardized Root Mean Square Residual):}
\deqn{
  \text{SRMSR} = \sqrt{
    \frac{1}{J} \sum_{i < j} (r_{ij}^{\text{obs}} - r_{ij}^{\text{model}})^2
  },
}
where \eqn{r_{ij}} are the observed and model-implied correlation residuals,
summed over \eqn{J} unique off-diagonal pairs.

\strong{McDonald's NCI (Non-Centrality Index):}
\deqn{
  \text{NCI} = \exp\!\left(-\frac{\max(M_2 - df, 0)}{2N}\right)
}
}

\section{Incremental / Comparative Fit Indices}{


\strong{CFI (Comparative Fit Index):}
\deqn{
  \text{CFI} = 1 - \frac{\max(M_2 - df, 0)}
                          {\max(M_2^{\text{null}} - df^{\text{null}}, M_2 - df, 0)},
}
where the null (independence) model has \eqn{M_2^{\text{null}}} with
\eqn{df^{\text{null}}} degrees of freedom.

\strong{TLI (Tucker--Lewis Index, a.k.a. NNFI):}
\deqn{
  \text{TLI} = \frac{M_2^{\text{null}} / df^{\text{null}} - M_2 / df}
                    {M_2^{\text{null}} / df^{\text{null}} - 1}
}

\strong{IFI (Incremental Fit Index, a.k.a. BFI):}
\deqn{
  \text{IFI} = \frac{M_2^{\text{null}} - M_2}{M_2^{\text{null}} - df}
}
}

\section{Pseudo-\eqn{R^2} Measures}{


\strong{McFadden's \eqn{R^2}:}
\deqn{R^2_{\text{McF}} = 1 - \frac{\ell}{\ell_0}}

\strong{McFadden's adjusted \eqn{R^2}:}
\deqn{R^2_{\text{McF,adj}} = 1 - \frac{\ell - p}{\ell_0}}

\strong{Cox--Snell \eqn{R^2}:}
\deqn{R^2_{\text{CS}} = 1 - \exp\!\left(\frac{2}{N}(\ell_0 - \ell)\right)}

\strong{Nagelkerke \eqn{R^2}:}
\deqn{R^2_{\text{N}} = \frac{R^2_{\text{CS}}}
                                {1 - \exp(2\ell_0 / N)}}

\strong{Aldrich--Nelson \eqn{R^2}:}
\deqn{R^2_{\text{AN}} = \frac{G^2}{G^2 + N},
      \quad G^2 = D_0 - D}

\strong{Veall--Zimmermann \eqn{R^2}:}
\deqn{R^2_{\text{VZ}} = R^2_{\text{AN}} \times
      \frac{-2\ell_0 + N}{-2\ell_0}}

where \eqn{\ell_0} is the null-model (independence) log-likelihood and
\eqn{D_0} the corresponding deviance.
}

\section{Yen's Q3 Local Dependence}{


For each pair of items \eqn{(i, k)}, the residual correlation is
\deqn{
  Q_{3,ik} = \text{Corr}(r_{ji}, r_{jk}),
  \qquad r_{ji} = Y_{ji} - E[Y_{ji} \mid \hat{\boldsymbol{\theta}}_j],
}
where residuals are computed from posterior expected scores. Adjusted
Q3 values subtract the mean Q3 across all pairs to center the
distribution (Christensen, Makransky, & Horton, 2017).
}

\section{Heuristic Guidelines}{


The \code{print.summary.good.of.fit()} method reports descriptive
recommended ranges based on common conventions. These are heuristics,
not decision rules; fit cutoffs depend on model family, dimensionality,
category sparsity, local dependence, and sample size.
\itemize{
\item \strong{RMSEA}: \eqn{\le 0.05} close fit; \eqn{\le 0.08} reasonable;
\eqn{\le 0.10} mediocre (Browne & Cudeck, 1993)
\item \strong{SRMSR}: \eqn{\le 0.08} acceptable (Hu & Bentler, 1999)
\item \strong{CFI / TLI}: \eqn{\ge 0.95} good; \eqn{\ge 0.90} acceptable
}
}

\references{
Akaike, H. (1974). A new look at the statistical model identification.
\emph{IEEE Transactions on Automatic Control}, 19, 716--723.

Bozdogan, H. (1987). Model selection and Akaike's Information Criterion
(AIC): The general theory and its analytical extensions.
\emph{Psychometrika}, 52, 345--370. \doi{10.1007/BF02294361}

Browne, M. W., & Cudeck, R. (1993). Alternative ways of assessing model
fit. In K. A. Bollen & J. S. Long (Eds.), \emph{Testing structural
equation models} (pp. 136--162). Sage.

Christensen, K. B., Makransky, G., & Horton, M. C. (2017). Critical
values for Yen's Q3. \emph{Applied Psychological Measurement}, 41,
178--194. \doi{10.1177/0146621616677520}

Hannan, E. J., & Quinn, B. G. (1979). The determination of the order of
an autoregression. \emph{Journal of the Royal Statistical Society:
Series B}, 41, 190--195.

Hu, L. T., & Bentler, P. M. (1999). Cutoff criteria for fit indexes in
covariance structure analysis. \emph{Structural Equation Modeling}, 6,
1--55. \doi{10.1080/10705519909540118}

Hurvich, C. M., & Tsai, C. L. (1989). Regression and time series model
selection in small samples. \emph{Biometrika}, 76, 297--307.
\doi{10.1093/biomet/76.2.297}

MacCallum, R. C., Browne, M. W., & Sugawara, H. M. (1996). Power
analysis and determination of sample size for covariance structure
modeling. \emph{Psychological Methods}, 1, 130--149.

Maydeu-Olivares, A., & Joe, H. (2005). Limited- and full-information
estimation and goodness-of-fit testing in 2^n contingency tables: A
unified framework. \emph{Journal of the American Statistical
Association}, 100, 1009--1020.

Maydeu-Olivares, A., & Joe, H. (2006). Limited information
goodness-of-fit testing in multidimensional contingency tables.
\emph{Psychometrika}, 71, 713--732. \doi{10.1007/s11336-005-1295-9}

McFadden, D. (1974). Conditional logit analysis of qualitative choice
behavior. In P. Zarembka (Ed.), \emph{Frontiers in econometrics}
(pp. 105--142). Academic Press.

Schwarz, G. (1978). Estimating the dimension of a model. \emph{The Annals
of Statistics}, 6, 461--464. \doi{10.1214/aos/1176344136}

Sclove, S. L. (1987). Application of model-selection criteria to some
problems in multivariate analysis. \emph{Psychometrika}, 52, 333--343.

Yen, W. M. (1984). Effects of local item dependence on the fit and
equating performance of the three-parameter logistic model. \emph{Applied
Psychological Measurement}, 8, 125--145. \doi{10.1177/014662168400800201}
}
\seealso{
\code{\link{get.fit.index}} for model-specific wrappers,
\code{\link{summary.good.of.fit}} for formatted fit tables,
\code{\link{print.good.of.fit}} for the print method.
}
