% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ForceChoice-package.R
\docType{package}
\name{ForceChoice-package}
\alias{ForceChoice}
\alias{ForceChoice-package}
\title{ForceChoice: Forced-Choice Modeling Based on IRT and CDM}
\description{
The \pkg{ForceChoice} package provides a unified framework for fitting,
simulating, and evaluating forced-choice and traditional item response
models. It supports eight model families spanning dominance (MIRT),
ideal-point/unfolding (MGGUM), polytomous (MGPCM), and forced-choice
(FCMIRT, FCGGUM, TIRT, FCDCM, FCGDINA) paradigms, with full Bayesian
estimation via Stan, fast improved stochastic EM (iStEM), and a
deterministic EM backend for FCGDINA.
}
\section{Model Families}{


\strong{Traditional (single-stimulus) models:}
\describe{
\item{\code{\link{fit.MIRT}}}{Multidimensional IRT (1PL--4PL).
Binary responses with optional Q-matrix structure.}
\item{\code{\link{fit.MGPCM}}}{Multidimensional Generalized Partial
Credit Model. Polytomous ordered-category responses.}
\item{\code{\link{fit.MGGUM}}}{Multidimensional Generalized Graded
Unfolding Model. Ideal-point polytomous responses.}
}

\strong{Forced-choice (comparative) models:}
\describe{
\item{\code{\link{fit.FCMIRT}}}{Forced-choice MIRT. Item-level
dominance model with sequential ranking over item endorsement
logits at the block level.}
\item{\code{\link{fit.FCGGUM}}}{Forced-choice GGUM. Item-level
ideal-point model with sequential ranking over binary GGUM
endorsement logits.}
\item{\code{\link{fit.TIRT}}}{Thurstonian IRT for forced-choice.
Pairwise probit comparison of latent utility differences.}
\item{\code{\link{fit.FCDCM}}}{Forced-choice DCM. Higher-order
cognitive diagnostic model with exact attribute-profile
marginalization.}
\item{\code{\link{fit.FCGDINA}}}{Forced-choice GDINA. General CDM
item-response structure with forced-choice block likelihood.}
}
}

\section{Estimation Methods}{


Model families support a common estimation interface:
\describe{
\item{\strong{Stan} (\code{method = "stan"}):}{
Full Bayesian inference via Hamiltonian Monte Carlo
(NUTS/HMC). Provides posterior means, standard deviations,
and convergence diagnostics (\eqn{\hat{R}}).}
\item{\strong{iStEM} (\code{method = "iStEM"}):}{
Improved Stochastic EM (iStEM) algorithm
combining finite-grid block Gibbs person sampling with
L-BFGS-B item-parameter optimization. Scales well to moderate
data sets.}
\item{\strong{EM} (\code{method = "EM"}):}{
Deterministic posterior-weight EM for FCGDINA. Useful as a
reproducible baseline or fast diagnostic estimator.}
}
}

\section{Core Workflow}{


A typical analysis follows four steps:
\enumerate{
\item \strong{Simulate} (or load) data with \code{sim.data.*()}.
\item \strong{Fit} a model with \code{fit.*()}.
\item \strong{Rotate} the solution if needed with
the \code{\link{rotate}} S3 generic.
\item \strong{Evaluate} fit with \code{\link{get.fit.index}()}
and \code{\link{summary.good.of.fit}()}.
}
}

\section{Goodness-of-Fit}{


The package uses the limited-information M2 framework
(Maydeu-Olivares & Joe, 2005, 2006) implemented in
\code{\link{good.of.fit}}. Fit indices include:
\itemize{
\item Information criteria: AIC, AICc, BIC, CAIC, SABIC, HQIC
\item Absolute fit: M2, RMSEA (with CI), SRMSR, McDonald NCI
\item Comparative fit: CFI, TLI, IFI
\item Pseudo-\eqn{R^2}: McFadden, Cox--Snell, Nagelkerke, etc.
\item Local dependence: Yen's Q3 (raw and adjusted)
\item Classification: posterior entropy, mean max posterior
}
}

\section{Reproducibility}{


The package is designed so that simulation, estimation, extraction, and
model checking can be scripted end to end. Simulation functions return the
true parameters and the effective call arguments; fitted objects retain the
original input arguments, estimates, convergence diagnostics, and
likelihood-related quantities used by \code{\link{logLik}} and
\code{\link{get.fit.index}}. For computationally expensive Stan or iStEM
workflows, manuscript replication code should set seeds explicitly and use
a small demonstration configuration in addition to any full-scale analysis.
}

\examples{
set.seed(123)
sim <- sim.data.FCGDINA(N.person = 12, N.block = 2, I.block = 2,
                        D = 2, model = "DINA")
str(sim$response)
head(sim$Q.matrix)

}
\author{
\strong{Maintainer}: Haijiang Qin \email{haijiang133@outlook.com} (\href{https://orcid.org/0009-0000-6721-5653}{ORCID}) [copyright holder]

Authors:
\itemize{
  \item Lei Guo \email{happygl1229@swu.edu.cn} (\href{https://orcid.org/0000-0002-8273-3587}{ORCID}) [copyright holder]
}

}
