ForceChoice-package: ForceChoice: Forced-Choice Modeling Based on IRT and CDM

In ForceChoice: Forced-Choice Modeling Based on Item Response Theory and Cognitive Diagnostic Models

ForceChoice: Forced-Choice Modeling Based on IRT and CDM

Description

The 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.

Model Families

Traditional (single-stimulus) models:

fit.MIRT

Multidimensional IRT (1PL–4PL). Binary responses with optional Q-matrix structure.

fit.MGPCM

Multidimensional Generalized Partial Credit Model. Polytomous ordered-category responses.

fit.MGGUM

Multidimensional Generalized Graded Unfolding Model. Ideal-point polytomous responses.

Forced-choice (comparative) models:

fit.FCMIRT

Forced-choice MIRT. Item-level dominance model with sequential ranking over item endorsement logits at the block level.

fit.FCGGUM

Forced-choice GGUM. Item-level ideal-point model with sequential ranking over binary GGUM endorsement logits.

fit.TIRT

Thurstonian IRT for forced-choice. Pairwise probit comparison of latent utility differences.

fit.FCDCM

Forced-choice DCM. Higher-order cognitive diagnostic model with exact attribute-profile marginalization.

fit.FCGDINA

Forced-choice GDINA. General CDM item-response structure with forced-choice block likelihood.

Estimation Methods

Model families support a common estimation interface:

Stan (method = "stan"):

Full Bayesian inference via Hamiltonian Monte Carlo (NUTS/HMC). Provides posterior means, standard deviations, and convergence diagnostics (\hat{R}).

iStEM (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.

EM (method = "EM"):

Deterministic posterior-weight EM for FCGDINA. Useful as a reproducible baseline or fast diagnostic estimator.

Core Workflow

A typical analysis follows four steps:

1. Simulate (or load) data with sim.data.*().

2. Fit a model with fit.*().

3. Rotate the solution if needed with the rotate S3 generic.

4. Evaluate fit with get.fit.index() and summary.good.of.fit().

Goodness-of-Fit

The package uses the limited-information M2 framework (Maydeu-Olivares & Joe, 2005, 2006) implemented in good.of.fit. Fit indices include:

• Information criteria: AIC, AICc, BIC, CAIC, SABIC, HQIC

• Absolute fit: M2, RMSEA (with CI), SRMSR, McDonald NCI

• Comparative fit: CFI, TLI, IFI

• Pseudo-R^2: McFadden, Cox–Snell, Nagelkerke, etc.

• Local dependence: Yen's Q3 (raw and adjusted)

• Classification: posterior entropy, mean max posterior

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 logLik and 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.

Author(s)

Maintainer: Haijiang Qin [e-mail] (ORCID) [copyright holder]

Authors:

• Haijiang Qin [e-mail] (ORCID) [copyright holder]

• Lei Guo [e-mail] (ORCID) [copyright holder]

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)

ForceChoice documentation built on Sept. 13, 2026, 1:06 a.m.