Package {ForceChoice}

Title:	Forced-Choice Modeling Based on Item Response Theory and Cognitive Diagnostic Models
Version:	1.0.0
Description:	Fits, simulates, and evaluates forced-choice and traditional item response theory (IRT) models for noncognitive assessment. Eight model families are supported, spanning dominance (multidimensional IRT (MIRT) 1PL–4PL; multidimensional generalized partial credit model (MGPCM)), ideal-point unfolding (multidimensional generalized graded unfolding model (MGGUM)), and forced-choice designs (forced-choice multidimensional IRT (FCMIRT), forced-choice generalized graded unfolding model (FCGGUM), Thurstonian IRT (TIRT), forced-choice diagnostic classification model (FCDCM), forced-choice generalized deterministic inputs, noisy "and" gate model (FCGDINA)) that mitigate response biases such as acquiescence and social desirability. Core estimation backends include full Bayesian inference via Hamiltonian Monte Carlo (Stan) and a fast improved stochastic expectation-maximization (iStEM) algorithm suitable for large-scale data; FCGDINA also provides a deterministic expectation-maximization (EM) estimator. Comprehensive model evaluation uses the limited-information M2 family of goodness-of-fit statistics (Maydeu-Olivares and Joe, 2005 <doi:10.1198/016214504000002069>; 2006 <doi:10.1007/s11336-005-1295-9>) together with root mean square error of approximation (RMSEA), comparative fit index (CFI), Tucker-Lewis index (TLI), and standardized root mean square residual (SRMSR).
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
NeedsCompilation:	yes
Config/ForceChoice/skip-rstantools-config:	true
Biarch:	true
Depends:	R (≥ 4.1.0)
Imports:	coda, GPArotation, MASS, methods, numDeriv, parallel, Rcpp (≥ 0.12.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), rstantools (≥ 2.6.0)
LinkingTo:	BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppArmadillo, RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), StanHeaders (≥ 2.18.0)
SystemRequirements:	GNU make
Suggests:	knitr, loo, rmarkdown
VignetteBuilder:	knitr
Config/testthat/edition:	3
Packaged:	2026-07-22 03:06:49 UTC; Haijiang
Author:	Haijiang Qin [aut, cre, cph], Lei Guo [aut, cph]
Maintainer:	Haijiang Qin <haijiang133@outlook.com>
Repository:	CRAN
Date/Publication:	2026-07-30 17:20:30 UTC

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 haijiang133@outlook.com (ORCID) [copyright holder]

Authors:

• Lei Guo happygl1229@swu.edu.cn (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)

Apply factor rotation to discrimination matrix and latent traits

Description

Supports "promax" (via stats::promax) and GPArotation methods ("varimax", "oblimin", etc.). Transforms the discrimination matrix a, the latent trait matrix theta, and the correlation matrix Corr accordingly.

Usage

apply_rotation_promax(a, theta, Corr, rotate, D, promax_m = 4)

Arguments

Value

A named list with components a, theta, Corr.

Build Stan sampling-control list from user-provided control.method

Description

This helper extracts Stan sampler tuning knobs (e.g. adapt_delta, max_treedepth) from method-specific controls so they can be passed safely to rstan::sampling().

Usage

build_stan_control(algorithm, control.method)

Arguments

Value

A named list of Stan sampling-control parameters (possibly empty).

Validate a scalar integer parameter

Description

Checks that x is a single finite value coercible to integer and at least min.val. Used by forced-choice sim.data.* functions to validate N.person, N.block, I.block, and D.

Usage

check_integer_scalar(x, name, min.val = 1L)

Arguments

Value

as.integer(x) on success; raises an error otherwise.

Clamp probabilities away from 0 and 1

Description

Ensures all values lie in [eps, 1-eps] to avoid log(0) or division-by-zero issues in downstream computations.

Usage

clip_prob(p, eps = 1e-12)

Arguments

Value

Numeric vector or matrix with the same dimensions as p.

S3 Methods: coef

Description

Extract estimated model coefficients (item, statement, or block parameters) from fitted ForceChoice model objects. This provides a standard R interface for retrieving parameter estimates, standard errors, and convergence diagnostics in a consistent format across all eight model families.

Usage

## S3 method for class 'MIRT'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'MGPCM'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'MGGUM'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'FCMIRT'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'FCDCM'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'FCGDINA'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'FCGGUM'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

## S3 method for class 'TIRT'
coef(object, type = c("par", "theta", "Corr", "all"), ...)

Arguments

Details

For FCDCM objects, type = "par" returns a list with components delta (higher-order parameters, D \times 2) and par (block \eta parameters, B \times 2), reflecting the hierarchical structure of the model.

Value

type = "par"

A matrix of item/statement/block parameter estimates. Rows index items/statements/blocks and columns index parameter types. Column names indicate the parameter (e.g., "a1", "b", "d0", "tau1", "eta0").

type = "theta"

An N \times D matrix of person parameter (latent trait) estimates.

type = "Corr"

A D \times D inter-trait correlation matrix.

type = "all"

A named list with components par, theta, and Corr.

Methods (by class)

• coef(MIRT): Extract coefficients from MIRT objects. Returns I \times (D+3) matrix with columns a1..aD, b, c, d.

• coef(MGPCM): Extract coefficients from MGPCM objects. Returns I \times (D+K_{\max}) matrix with columns a1..aD, d0..d(K-1).

• coef(MGGUM): Extract coefficients from MGGUM objects. Returns matrix with columns a1..aD, delta1..deltaD, tau0..tau(K-1).

• coef(FCMIRT): Extract coefficients from FCMIRT objects. Returns statement parameter matrix with columns a1..aD, b, c, d.

• coef(FCDCM): Extract coefficients from FCDCM objects. Returns a list with delta (D \times 2 higher-order parameters) and par (B \times 2 block \eta parameters). type = "theta" returns the higher-order trait, and type = "Corr" returns a scalar 1.

• coef(FCGDINA): Extract coefficients from FCGDINA objects. type = "par" returns CDM delta parameters, type = "theta" returns posterior attribute mastery probabilities, type = "Corr" returns NA (no continuous latent trait).

• coef(FCGGUM): Extract coefficients from FCGGUM objects. Returns matrix with columns a1..aD, delta1..deltaD, tau0..tau(K-1).

• coef(TIRT): Extract coefficients from TIRT objects. Returns I \times (D+1) matrix with columns lambda1..lambdaD, psi2.

Examples

sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)

coef(fit)                  # item parameter estimates
coef(fit, type = "theta")  # person trait estimates
coef(fit, type = "Corr")   # factor correlation matrix
coef(fit, type = "all")    # everything in a list

Compute FCGDINA item-level endorsement probabilities

Description

Computes statement endorsement probabilities for supplied attribute profiles under an FCGDINA item-level CDM parameterization.

Usage

compute_fcgdina_item_prob(
  alpha,
  delta.list,
  design.matrix.list,
  Q.matrix,
  gs = NULL,
  eps = 1e-12,
  link = c("identity", "logit")
)

Arguments

Details

The function maps each full attribute pattern in alpha to the reduced pattern required by each item-specific Q-vector, evaluates the corresponding design row, and multiplies by that item's delta vector. This function does not sample responses.

Value

An N \times I matrix of item endorsement probabilities.

See Also

model.FCGDINA, sim.data.FCGDINA

S3 Methods: confint

Description

Computes Wald-type confidence intervals for the model parameters of a fitted ForceChoice model object. Intervals are constructed as \hat{\psi}_k \pm z_{1-\alpha/2}\,\mathrm{SE}_k, where \hat{\psi}_k is the point estimate and \mathrm{SE}_k is the standard error of the k-th free parameter.

Usage

## S3 method for class 'MIRT'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'MGPCM'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'MGGUM'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'FCMIRT'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'FCDCM'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'FCGDINA'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'FCGGUM'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'TIRT'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

Value

A numeric matrix with two columns, 2.5% and 97.5% (column names adjust automatically for non-default level). Each row corresponds to one free parameter.

Methods (by class)

• confint(MIRT): Confidence intervals for MIRT parameters.

• confint(MGPCM): Confidence intervals for MGPCM parameters.

• confint(MGGUM): Confidence intervals for MGGUM parameters.

• confint(FCMIRT): Confidence intervals for FCMIRT parameters.

• confint(FCDCM): Confidence intervals for FCDCM parameters.

• confint(FCGDINA): Confidence intervals for FCGDINA parameters.

• confint(FCGGUM): Confidence intervals for FCGGUM parameters.

• confint(TIRT): Confidence intervals for TIRT parameters.

S3 Methods: deviance

Description

Returns the model deviance, defined as -2 \ell where \ell is the marginal log-likelihood evaluated at the parameter estimates.

Usage

## S3 method for class 'MIRT'
deviance(object, ...)

## S3 method for class 'MGPCM'
deviance(object, ...)

## S3 method for class 'MGGUM'
deviance(object, ...)

## S3 method for class 'FCMIRT'
deviance(object, ...)

## S3 method for class 'FCDCM'
deviance(object, ...)

## S3 method for class 'FCGDINA'
deviance(object, ...)

## S3 method for class 'FCGGUM'
deviance(object, ...)

## S3 method for class 'TIRT'
deviance(object, ...)

Arguments

Value

A numeric scalar: -2 \log L.

Methods (by class)

• deviance(MIRT): Model deviance (-2 \ell) for MIRT objects.

• deviance(MGPCM): Model deviance for MGPCM objects.

• deviance(MGGUM): Model deviance for MGGUM objects.

• deviance(FCMIRT): Model deviance for FCMIRT objects.

• deviance(FCDCM): Model deviance for FCDCM objects.

• deviance(FCGDINA): Model deviance for FCGDINA objects.

• deviance(FCGGUM): Model deviance for FCGGUM objects.

• deviance(TIRT): Model deviance for TIRT objects.

S3 Methods: extract

Description

A generic S3 extractor function designed to retrieve internal components from fitted model objects produced by the ForceChoice package. This function provides a consistent interface across all eight model classes, allowing users to access estimated parameters, fit statistics, latent trait estimates, convergence diagnostics, and model configuration data without directly manipulating the internal list structure.

Usage

## S3 method for class 'MIRT'
extract(object, what, ...)

## S3 method for class 'MGPCM'
extract(object, what, ...)

## S3 method for class 'MGGUM'
extract(object, what, ...)

## S3 method for class 'FCMIRT'
extract(object, what, ...)

## S3 method for class 'FCDCM'
extract(object, what, ...)

## S3 method for class 'FCGDINA'
extract(object, what, ...)

## S3 method for class 'FCGGUM'
extract(object, what, ...)

## S3 method for class 'TIRT'
extract(object, what, ...)

Arguments

Details

This function supports extraction from the eight ForceChoice model classes. Below are the available components for each:

MIRT, MGPCM, MGGUM

Traditional (single-stimulus) models. Available components:

par

List (est, se, Rhat, free) of item parameter arrays.

theta

List (est, se, Rhat) of N \times D person parameter matrices.

Corr

List (est, se, Rhat) of D \times D inter-trait correlation matrices.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method ("stan" or "iStEM").

Q.matrix

The I \times D Q-matrix.

length.poly

Vector of category counts per item (MGPCM, MGGUM only).

stan.obj

The stanfit object (Stan only).

MCMC.obj

The MCMC extract list (Stan only).

iStEM

List of iStEM diagnostics (iStEM only).

call

The matched call.

arguments

List of arguments used for fitting.

FCMIRT, FCGGUM

Forced-choice models. In addition to the traditional-model components listed above, the following are available:

block.items

List of item indices in each block.

response

The N \times B forced-choice response matrix.

patterns

List of permissible ranking patterns per block.

patterns.total

List of all possible ranking patterns per block.

fc.type

Character vector of forced-choice formats ("RANK", "MOLE", "PICK").

FCDCM

Forced-Choice DCM. Available components:

par

List (est, se, Rhat, free) of block \eta parameter matrices (B \times 2).

delta

List (est, se, Rhat) of higher-order \delta parameters (D \times 2).

theta

List (est, se, Rhat) of N \times 1 higher-order trait estimates.

alpha

Posterior mean attribute profile (N \times D).

alpha.patterns

Full enumeration of 2^D attribute mastery patterns.

zeta.patterns

Condensation outputs for each pattern.

dcm.type

DCM condensation rule ("DINA" or "DINO").

response

The N \times B binary block response matrix.

block.items

List of two-statement blocks.

patterns

List of binary response patterns per block.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method.

Q.matrix

The I \times D Q-matrix.

stan.obj, MCMC.obj, iStEM, EM

Estimation backend objects.

call

The matched call.

arguments

List of arguments used for fitting.

FCGDINA

Forced-Choice GDINA. Available components:

delta

List (est, se, Rhat) of item-level CDM delta parameters.

alpha

Posterior attribute summaries, including posterior class probabilities when available.

alpha.patterns

Full enumeration of 2^D attribute mastery patterns.

design.matrix.list

Per-item CDM design matrices.

response, block.items, patterns, patterns.total, fc.type

Forced-choice data structures.

TIRT

Thurstonian IRT. Available components:

par

List (est, se, Rhat, free) of statement-level parameter matrices (I \times (D+1)).

theta

List (est, se, Rhat) of N \times D person parameter matrices.

gamma

List (est, se, Rhat, free) of pairwise \gamma parameters.

gamma.matrix

List (est, se, Rhat) of I \times I skew-symmetric \gamma matrices.

Corr

List (est, se, Rhat) of D \times D inter-trait correlation matrices.

pairs.matrix

Matrix of pairwise comparison indices.

pairs.value

Person-specific pair data (MOLE/PICK).

response

The N \times I_{pairs} pairwise response matrix.

block.items

List of item indices in each block.

fc.type

Character vector of forced-choice formats.

Q.matrix

The statement-level Q-matrix.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method.

stan.obj, MCMC.obj, iStEM

Estimation backend objects.

call

The matched call.

arguments

List of arguments used for fitting.

Value

The requested component. Return type varies depending on what and the class of object. If an invalid what is provided, an informative error is thrown listing valid options.

Methods (by class)

• extract(MIRT): Extract components from MIRT objects.

• extract(MGPCM): Extract components from MGPCM objects.

• extract(MGGUM): Extract components from MGGUM objects.

• extract(FCMIRT): Extract components from FCMIRT objects.

• extract(FCDCM): Extract components from FCDCM objects.

• extract(FCGDINA): Extract components from FCGDINA objects.

• extract(FCGGUM): Extract components from FCGGUM objects.

• extract(TIRT): Extract components from TIRT objects.

Examples

sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)

extract(fit, "par")       # item parameter estimates
extract(fit, "theta")     # person trait estimates
extract(fit, "Corr")      # factor correlation matrix
extract(fit, "npar")      # number of free parameters
extract(fit, "logLik")    # marginal log-likelihood
extract(fit, "iStEM")     # iStEM convergence diagnostics

Extract correlation posterior summary from Stan MCMC output

Description

Extract correlation posterior summary from Stan MCMC output

Usage

extract_corr_stan(MCMC.obj, stan.sum, D)

Arguments

Value

A list with components est, se, and Rhat.

Extract R-hat values for a matrix parameter from a Stan summary

Description

Extract R-hat values for a matrix parameter from a Stan summary

Usage

extract_rhat_matrix(stan.sum, param_name, nrow, ncol)

Arguments

Value

A numeric matrix of R-hat values.

Extract R-hat values for a vector parameter from a Stan summary

Description

Extract R-hat values for a vector parameter from a Stan summary

Usage

extract_rhat_vector(stan.sum, param_name, n)

Arguments

Value

A numeric vector of R-hat values (NA where not found).

Extract theta posterior summary from Stan MCMC output

Description

Extract theta posterior summary from Stan MCMC output

Usage

extract_theta_stan(MCMC.obj, stan.sum, N, D, row_names = NULL)

Arguments

Value

A list with components est, se, and Rhat.

Fit the Forced-Choice Diagnostic Classification Model (FCDCM)

Description

Fits a higher-order cognitive diagnostic model for forced-choice (paired- comparison) data. Each block presents two statements, and the respondent selects the one they agree with more. The discrete attribute mastery profile \boldsymbol{\alpha}_j for each person is marginalized over all 2^D possible patterns, linking a continuous higher-order latent trait \theta_j to the DCM condensation rule at the statement level.

Usage

fit.FCDCM(
  data,
  Q.matrix,
  block.items = NULL,
  dcm.type = "DINA",
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "FCDCM" containing:

npar

Number of free parameters (2D + 2B).

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times 1); higher-order trait estimates.

delta

List with est, se, Rhat (D \times 2); higher-order \delta_1, \delta_0 parameters.

par

List with est, se, Rhat (B \times 2); block response parameters eta0 and etaAB.

alpha

List with est, se, Rhat, and prob; est is the binary classified attribute profile (N \times D) and prob contains posterior mastery probabilities.

class.post

Posterior probabilities for all 2^D attribute profiles.

alpha.patterns, zeta.patterns

Full enumeration of attribute mastery patterns and their condensation outputs.

logLik

Marginal log-likelihood (class "logLik").

Model Specification

Higher-order latent structure. A unidimensional continuous trait \theta_j \sim N(0, 1) governs the probability of mastering each attribute d = 1, \dots, D:

P(\alpha_{jd} = 1 \mid \theta_j) = \frac{1}{1 + \exp\bigl[-\bigl(\delta_{1d}\,\theta_j - \delta_{1d}\,\delta_{0d}\bigr)\bigr]},

where \delta_{1d} > 0 is the discrimination and \delta_{0d} is the difficulty (threshold) for attribute d. Attributes are conditionally independent given \theta_j.

Statement-level condensation. For each statement i = 1, \dots, I with Q-vector \mathbf{q}_i = (q_{i1}, \dots, q_{iD})', the latent mastery status \zeta_{ij} \in \{0, 1\} is determined by one of two condensation rules:

DINA (conjunctive):

\zeta_{ij} = \prod_{d: q_{id} = 1} \alpha_{jd}.

All required attributes must be mastered.

DINO (disjunctive):

\zeta_{ij} = 1 - \prod_{d: q_{id} = 1} (1 - \alpha_{jd}).

At least one required attribute must be mastered.

Forced-choice block response. Block b consists of two statements (A_b, B_b). The probability that the respondent selects statement A_b over B_b follows the original FC-DCM specification and fixes equal-condensation probabilities to chance:

P(\text{choose } A_b \mid \zeta_{A_b}, \zeta_{B_b}) = \begin{cases} \eta_{0b}, & \text{if } \zeta_{A_b} < \zeta_{B_b}, \\ 0.5, & \text{if } \zeta_{A_b} = \zeta_{B_b}, \\ 0.5+\eta_{ABb}, & \text{if } \zeta_{A_b} > \zeta_{B_b}. \end{cases}

with 0 < \eta_{0b} < 0.5 and 0 < \eta_{ABb} < 0.5. Thus equal statement-level mastery produces chance choice, choosing the lower mastery statement has probability \eta_{0b}, and choosing the higher mastery statement has probability 0.5+\eta_{ABb}. The probability of choosing B_b is the complement.

The marginal likelihood integrates over all 2^D attribute patterns:

P(\mathbf{Y}_j \mid \theta_j) = \sum_{\boldsymbol{\alpha} \in \{0,1\}^D} P(\boldsymbol{\alpha} \mid \theta_j) \times \prod_{b=1}^{B} P(Y_{jb} \mid \zeta_{A_b}, \zeta_{B_b}).

Design and Identifiability

A block with \zeta_{A_b}=\zeta_{B_b} contributes no direct information for distinguishing the two equal condensation states (both are fixed at 0.5). For single-attribute statements and D=2, if all blocks compare the same ordered attribute pair, the response distribution distinguishes 10 from 01 but leaves 00 and 11 to be separated only by the higher-order structural model. Good global fit can therefore coexist with weak profile classification.

A forced-choice Q/block design should provide repeated cross-attribute comparisons, avoid pairing statements with identical Q-vectors, and keep each attribute represented in both statement positions. A practical numerical target, consistent with the original FC-DCM simulation logic, is that each attribute appears multiple times as the first/predominant statement and multiple times as the second/inferior statement, with comparisons distributed across different attribute pairs. The automatic simulator uses this balanced assembly rule when block.items is not supplied.

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. The discrete attribute profile is exactly marginalized in the Stan likelihood.

iStEM (method = "iStEM"):

Improved Stochastic EM. Person sampling considers the joint space of \theta_j and \boldsymbol{\alpha}_j. Parameter updates use closed-form or numerical optimization steps.

References

de la Torre, J., & Douglas, J. A. (2004). Higher-order latent trait models for cognitive diagnosis. Psychometrika, 69(3), 333–353. doi:10.1007/BF02295640

Junker, B. W., & Sijtsma, K. (2001). Cognitive assessment models with few assumptions, and connections with nonparametric item response theory. Applied Psychological Measurement, 25(3), 258–272.

See Also

sim.data.FCDCM, get.fit.index.FCDCM, logLik.FCDCM

Examples

sim <- sim.data.FCDCM(N.person = 20, N.block = 3, D = 2,
                      dcm.type = "DINA")
fit <- fit.FCDCM(sim$data, Q.matrix = sim$Q.matrix,
                 block.items = sim$block.items,
                 dcm.type = "DINA", method = "iStEM",
                 control.method = list(
                   seed = 123, vis = FALSE,
                   M = 2, B = 2, burnin.maxitr = 2,
                   maxitr = 3, eps1 = 10, eps2 = 10,
                   estimate.se = FALSE))
head(fit$alpha$est)                # binary attribute profiles (0/1)
head(fit$alpha$prob)               # marginal mastery probabilities
gof <- get.fit.index(fit)
summary(gof)

Fit the Forced-Choice GDINA Model

Description

Fits a forced-choice cognitive diagnostic model (FCGDINA) to comparative response data. The statement-level cognitive diagnosis component can be DINA, DINO, ACDM, or GDINA, and the block-level response model transforms statement endorsement probabilities into forced-choice probabilities for full rankings ("RANK"), most-least choices ("MOLE"), or best-only choices ("PICK").

Usage

fit.FCGDINA(
  data,
  Q.matrix,
  model = c("GDINA", "DINA", "DINO", "ACDM"),
  block.items = NULL,
  fc.type = NULL,
  method = c("EM", "stan", "iStEM"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "FCGDINA", a list containing:

npar

Number of free CDM delta parameters.

method

Estimation method actually used: "stan", "iStEM", or "EM".

alpha

List with est, se, Rhat, and prob. est is an N \times D matrix of posterior attribute mastery probabilities; prob contains posterior probabilities for all 2^D attribute profiles.

delta

List with est, se, and Rhat. For Stan fits, each element is the probability-scale transform of the identified minimum-norm logit coefficient vector. Absolute statement endorsement probabilities are not identified by forced-choice data alone.

delta.identification

Stan-only rank, nullity, blockwise rank diagnostics, and the identifying convention.

delta.store

Stored posterior, iStEM, or bootstrap delta draws when available.

Q.matrix, block.items, patterns, patterns.total, design.matrix.list, alpha.patterns, fc.type, response

Processed model and data structures used by prediction, fit indices, and S3 methods.

stan.obj, MCMC.obj

Stan fit and extracted posterior draws for method = "stan"; otherwise NULL.

iStEM

iStEM convergence diagnostics and chains for method = "iStEM"; otherwise NULL.

EM

EM convergence diagnostics, log-likelihood trace, and bootstrap summary for method = "EM"; otherwise NULL.

logLik

Marginal log-likelihood with class "logLik".

call, arguments

Matched call and effective fitting arguments.

Model Specification

Let \boldsymbol{\alpha}_n \in \{0, 1\}^D denote the latent attribute profile for person n. For statement i, the binary Q-vector \mathbf{q}_i selects the required attributes and the reduced attribute pattern is mapped to a CDM design row \mathbf{x}_{ic}. For Stan estimation, \boldsymbol{\delta}_i is represented directly as the item-specific CDM effect vector on the logit scale: intercept, attribute main effects, and interaction effects. The item-level endorsement probability for attribute class c is

p_{ic} = \mathrm{logit}^{-1}(\mathbf{x}_{ic}' \boldsymbol{\delta}_i),

so main effects and interactions may be negative while probabilities remain in (0, 1). Forced-choice observations identify only within-block utility contrasts, not the absolute endorsement logits of individual statements. The Stan implementation therefore removes the exact null space of those contrasts and reports the unique minimum-norm coefficient representative. The design matrix is generated according to model: "DINA", "DINO", "ACDM", or "GDINA". EM and iStEM retain the existing probability-scale CDM parameterisation.

For each forced-choice block, the statement endorsement probabilities are converted to ranking-pattern probabilities by the same sequential Luce–Plackett transformation used by fit.FCMIRT and fit.FCGGUM. The likelihood marginalizes over all 2^D attribute profiles using a uniform latent-class prior:

P(\mathbf{Y}_n) = \sum_{c=1}^{2^D} \pi_c \prod_{b=1}^{B} P(Y_{nb} \mid \boldsymbol{\alpha}_c, \boldsymbol{\delta}, \mathrm{block}_b).

Data Coding

data must be an N \times B matrix, with one column per forced-choice block. Entries may be character rankings such as "2>1>3" or 1-based integer pattern indices. If integer pattern indices are supplied, block.items must be provided because item identities cannot be recovered from indices alone. For "MOLE" and "PICK" character data, supplying block.items is recommended and required whenever partial rankings do not identify all items in a block.

Estimation Controls

Common control.method entries are:

seed

Integer random seed.

cores

Number of cores used by Stan chains; ignored by the deterministic EM updates.

vis

Logical progress flag.

delta.lower, delta.upper

Lower and upper bounds for delta optimization in EM and iStEM. Defaults are -4 and 4.

Stan-specific entries include chains, iter, warmup, thin, init, algorithm, and the usual Stan control entries such as adapt_delta, max_treedepth, stepsize, and metric. Defaults are inherited from the common ForceChoice Stan helper: 4 chains, 2000 iterations, and half the iterations used as warmup. The default init = 0 is valid for Stan FCGDINA because it implies p_{ic} = 0.5 under the logit link.

iStEM-specific entries include M, B, burnin.maxitr, maxitr, eps1, eps2, frac1, frac2, optim.maxit, and estimate.se. Each iStEM update samples discrete attribute classes from the current posterior and optimises \delta parameters given the sampled class memberships.

EM-specific entries are:

maxitr

Maximum EM iterations; default 500.

minitr

Minimum EM iterations before convergence checks; default 2.

tol

Absolute log-likelihood change tolerance; default 1e-6.

par.tol

Maximum absolute delta-parameter change tolerance; default 1e-4.

optim.maxit

Maximum L-BFGS-B iterations for blockwise delta updates; default 200.

estimate.se

Logical; whether to estimate standard errors by nonparametric bootstrap. Default FALSE.

bootstrap

Number of bootstrap samples when estimate.se = TRUE. Default 100; must be at least 2.

References

de la Torre, J. (2011). The generalized DINA model framework. Psychometrika, 76(2), 179–199. doi:10.1007/s11336-011-9207-7

Templin, J., & Henson, R. A. (2006). Measurement of psychological disorders using cognitive diagnosis models. Psychological Methods, 11(3), 287–305. doi:10.1037/1082-989X.11.3.287

See Also

sim.data.FCGDINA, model.FCGDINA, get.fit.index.FCGDINA, fit.FCDCM, fit.FCMIRT, fit.FCGGUM

Examples

sim <- sim.data.FCGDINA(N.person = 20, N.block = 2, I.block = 2,
                        D = 2, model = "DINA", fc.type = "RANK")

fit <- fit.FCGDINA(
  sim$data,
  Q.matrix = sim$Q.matrix,
  block.items = sim$block.items,
  model = "DINA",
  fc.type = sim$fc.type,
  method = "EM",
  control.method = list(seed = 123, vis = FALSE,
                        maxitr = 2, estimate.se = FALSE)
)

coef(fit, type = "par")
head(fit$alpha$est)
logLik(fit)


# stan code, long time
fit.stan <- fit.FCGDINA(
  sim$data,
  Q.matrix = sim$Q.matrix,
  block.items = sim$block.items,
  model = "GDINA",
  method = "stan",
  control.method = list(seed = 123, cores = 2,
                        chains = 1, iter = 200, warmup = 100)
)

Fit the Forced-Choice Generalized Graded Unfolding Model (FCGGUM)

Description

Fits a forced-choice variant of the multidimensional generalized graded unfolding model (GGUM) to comparative ranking data. Unlike dominance-based FC models, the FCGGUM uses an ideal-point (unfolding) item response process: endorsement probability peaks when the person and item locations coincide, and the block-level ranking follows the Luce–Plackett model.

Usage

fit.FCGGUM(
  data,
  Q.matrix = NULL,
  block.items = NULL,
  D = NULL,
  fc.type = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "FCGGUM" containing:

npar

Number of free parameters.

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times D).

par

List with est, se, Rhat, free (I \times (2D + 2)).

Corr

List with est, se, Rhat (D \times D).

block.items, patterns, patterns.total, response

Block structure.

logLik

Marginal log-likelihood (class "logLik").

Model Specification

Item-level unfolding process. For statement i with Q-vector \mathbf{q}_i \in \{-1, 0, 1\}^D, the category response function is the GGUM (see fit.MGGUM for the full polytomous specification). For the forced-choice context, each item is binary (K_i=2). Define

r_{ij} = \left[ \sum_{d=1}^{D} a_{id}^2 \left(\theta_{jd} - \delta_{id}\right)^2 \right]^{1/2}, \qquad S_i = \sum_{d=1}^{D} a_{id}, \qquad \psi_{i1} = \tau_{i1}S_i .

The binary GGUM endorsement probability used by the code is:

P_i(\boldsymbol{\theta}_j) = \frac{ \exp\{r_{ij}-\psi_{i1}\} + \exp\{2r_{ij}-\psi_{i1}\} }{ 1 + \exp\{3r_{ij}\} + \exp\{r_{ij}-\psi_{i1}\} + \exp\{2r_{ij}-\psi_{i1}\} },

where \tau_{i1} < 0 is the first (and only free) threshold.

Block-level forced-choice ranking. Within each block b, the probability of the observed ranking is computed by applying the sequential Luce/Plackett rule to u_i(\boldsymbol{\theta}_j)=\mathrm{logit} \{P_i(\boldsymbol{\theta}_j)\}:

P(\text{ranking} \mid \boldsymbol{\theta}_j) = \prod_{m=1}^{K_b-1} \frac{\exp\{u_{i_{(m)}}(\boldsymbol{\theta}_j)\}} {\sum_{r=m}^{K_b}\exp\{u_{i_{(r)}}(\boldsymbol{\theta}_j)\}}.

MOLE and PICK probabilities are sums over compatible full rankings, normalized over the observed block patterns by the C++ probability helper.

Q-matrix for unfolding. The Q-matrix serves a dual role: entries of \pm 1 activate both the slope a_{id} and the location \delta_{id}; the sign of q_{id} determines the sign of \delta_{id} (positive vs. negative side of dimension d).

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. The GGUM likelihood involves summation terms that are handled in the Stan model block.

iStEM (method = "iStEM"):

Improved Stochastic EM. Person sampling uses finite-grid block Gibbs; GGUM item parameters updated via constrained L-BFGS-B with monotonicity constraints on \tau and sign constraints on \delta.

References

Roberts, J. S., Donoghue, J. R., & Laughlin, J. E. (2000). A general item response theory model for unfolding unidimensional polytomous responses. Applied Psychological Measurement, 24(1), 3–32.

See Also

sim.data.FCGGUM, get.fit.index.FCGGUM, logLik.FCGGUM, fit.MGGUM

Examples

sim <- sim.data.FCGGUM(N.person = 20, N.block = 3, I.block = 2,
                       D = 2, fc.type = "RANK")
fit <- fit.FCGGUM(sim$data, Q.matrix = sim$Q.matrix,
                  block.items = sim$block.items,
                  D = 2, fc.type = "RANK", method = "iStEM",
                  control.method = list(
                    vis = FALSE, seed = 123,
                    M = 2, B = 2, burnin.maxitr = 2,
                    maxitr = 3, eps1 = 10, eps2 = 10,
                    estimate.se = FALSE))
head(fit$theta$est)
gof <- get.fit.index(fit)
summary(gof)

Fit the Forced-Choice Multidimensional IRT (FCMIRT) Model

Description

Fits a forced-choice variant of the multidimensional item response theory model to comparative ranking data. In forced-choice (FC) formats, respondents compare items within blocks rather than rating each item in isolation. The FCMIRT model couples an item-level MIRT endorsement model with a block-level ranking mechanism to recover latent trait estimates from comparative responses.

Usage

fit.FCMIRT(
  data,
  model = "2PL",
  Q.matrix = NULL,
  block.items = NULL,
  D = NULL,
  fc.type = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "FCMIRT" containing:

npar

Number of free parameters.

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times D); person trait estimates.

par

List with est, se, Rhat, free (I \times (D+3)); item parameters a1..aD, b, c, d.

Corr

List with est, se, Rhat (D \times D).

block.items, patterns, patterns.total, response

Block structure and response data.

logLik

Marginal log-likelihood (class "logLik").

Model Specification

Item-level endorsement. Each statement i = 1, \dots, I is governed by a MIRT model (1PL through 4PL). For a person with trait \boldsymbol{\theta}_j, the probability of endorsing statement i in isolation is:

P_i(\boldsymbol{\theta}_j) = c_i + (d_i - c_i) \times \frac{1}{1 + \exp\bigl[-\bigl(\sum_{d=1}^{D} a_{id}\,\theta_{jd} - b_i\bigr)\bigr]}.

Block-level ranking. Let block b = 1, \dots, B consist of items \{i_1, i_2, \dots, i_{K_b}\} and define the implemented statement utility as the logit of the item-level endorsement probability,

u_i(\boldsymbol{\theta}_j) = \log\left[ \frac{P_i(\boldsymbol{\theta}_j)} {1-P_i(\boldsymbol{\theta}_j)} \right].

The probability that an examinee produces the ranking i_{(1)} \succ i_{(2)} \succ \dots \succ i_{(K_b)} (read as "i_{(1)} is preferred over i_{(2)} over ...") is:

P\bigl(i_{(1)} \succ \dots \succ i_{(K_b)} \mid \boldsymbol{\theta}_j\bigr) = \prod_{m=1}^{K_b-1} \frac{ \exp\{u_{i_{(m)}}(\boldsymbol{\theta}_j)\} }{ \sum_{r=m}^{K_b} \exp\{u_{i_{(r)}}(\boldsymbol{\theta}_j)\} }.

The Stan code evaluates the same choice kernel as \log P_i + \sum_{h \ne i}\log(1-P_h) within each remaining set, which is algebraically equivalent to a softmax over \mathrm{logit}(P_i).

Partial rankings (MOLE / PICK). For MOLE (most-least) data, only the best and worst items in each block are identified; for PICK data, only the best item. The probability of a partial ranking is obtained by marginalizing (summing) the full-ranking probabilities over all completions consistent with the partial constraint; the C++ probability helper returns probabilities normalized over the observed RANK/MOLE/PICK patterns for each block.

Identification constraint (2PLM-RANK). Block intercepts b_i are constrained to sum to zero within each block:

\sum_{i \in \text{block } b} b_i = 0, \qquad b = 1, \dots, B,

so that only K_b - 1 difficulties are freely estimated per block.

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. The forced-choice likelihood is evaluated over the ranking pattern probabilities. By default, a.sigma is set to 1.0 (wider prior) to avoid spurious shrinkage of within-block slopes toward equality.

iStEM (method = "iStEM"):

Improved Stochastic EM with finite-grid block Gibbs person-sampling and item optimization (L-BFGS-B). Block-level identification constraints are enforced during each item-parameter update.

References

Brown, A., & Maydeu-Olivares, A. (2011). Item response modeling of forced-choice questionnaires. Educational and Psychological Measurement, 71(3), 460–502. doi:10.1177/0013164410375112

Luce, R. D. (1959). Individual choice behavior: A theoretical analysis. Wiley.

Plackett, R. L. (1975). The analysis of permutations. Journal of the Royal Statistical Society: Series C, 24(2), 193–202.

See Also

sim.data.FCMIRT, get.fit.index.FCMIRT, logLik.FCMIRT, fit.MIRT

Examples

# Simulate forced-choice data
sim <- sim.data.FCMIRT(N.person = 20, N.block = 3, I.block = 2,
                       D = 2, model = "m2pl", fc.type = "RANK")

# Fit via iStEM
fit <- fit.FCMIRT(sim$data, model = "m2pl",
                  Q.matrix = sim$Q.matrix,
                  block.items = sim$block.items,
                  D = 2, fc.type = "RANK",
                  method = "iStEM",
                  control.method = list(
                    vis = FALSE, seed = 123,
                    M = 2, B = 2, burnin.maxitr = 2,
                    maxitr = 3, eps1 = 10, eps2 = 10,
                    estimate.se = FALSE))

# Examine trait recovery
cor(fit$theta$est, sim$theta)

# Fit indices (nominal binary expansion)
gof <- get.fit.index(fit)
summary(gof)

Fit the Multidimensional Generalized Graded Unfolding Model (MGGUM)

Description

Fits a multidimensional generalization of the generalized graded unfolding model (GGUM) to polytomous response data. Unlike dominance (cumulative) IRT models, the MGGUM belongs to the ideal-point (unfolding) model family where the probability of endorsement is highest when the person and item locations match, decreasing as the person moves away in either direction. Two estimation backends are provided: Bayesian MCMC (Stan) and iStEM.

Usage

fit.MGGUM(
  data,
  D = NULL,
  Q.matrix = NULL,
  length.poly = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "MGGUM" containing:

npar

Number of free parameters.

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times D).

par

List with est, se, Rhat, free (I \times (2D + K_{max})). Columns: a1..aD, delta1..deltaD, tau0..tau_{K_{max}-1}.

Corr

List with est, se, Rhat (D \times D).

length.poly

Per-item category counts.

logLik

Marginal log-likelihood (class "logLik").

Model Specification

Let Y_{ij} \in \{0, 1, \dots, K_i - 1\} be the categorical response of person j to item i, with K_i \ge 2 categories. Let \boldsymbol{\theta}_j denote the D-dimensional latent trait vector.

The category response probability implemented by model.MGGUM, iStEM, and Stan is the distance-based MGGUM form. Define

r_{ij} = \left[ \sum_{d=1}^{D} a_{id}^2 \left(\theta_{jd} - \delta_{id}\right)^2 \right]^{1/2}, \qquad S_i = \sum_{d=1}^{D} a_{id}.

Let \tau_{i0}=0 and \psi_{ik}=S_i\sum_{v=0}^{k}\tau_{iv}. With M_i=2K_i-1, the probability of category k = 0,\dots,K_i-1 is

P(Y_{ij} = k \mid \boldsymbol{\theta}_j) = \frac{ \exp\{k r_{ij}-\psi_{ik}\} + \exp\{(M_i-k)r_{ij}-\psi_{ik}\} }{ \sum_{r=0}^{K_i-1} \bigl[ \exp\{r r_{ij}-\psi_{ir}\} + \exp\{(M_i-r)r_{ij}-\psi_{ir}\} \bigr] }.

Here a_{id} \ge 0 are discrimination parameters, \delta_{id} are item-location parameters (signed positive when q_{id} = 1, negative when q_{id} = -1), and threshold parameters \tau_{ik} satisfying \tau_{i0} = 0 and \tau_{i1} < \tau_{i2} < \dots < \tau_{i,K_i-1} < 0.

Q-matrix sign convention:

q_{id} = 1

Active dimension; \delta_{id} > 0 (item located on the positive side of dimension d).

q_{id} = -1

Active dimension; \delta_{id} < 0 (item located on the negative side of dimension d).

q_{id} = 0

Inactive dimension; a_{id} = \delta_{id} = 0.

The sign of q_{id} controls the item-location side, not the sign of the slope. Both a_{id} and |\delta_{id}| reflect the item's relevance to dimension d.

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. All parameters are jointly sampled from the posterior distribution.

iStEM (method = "iStEM"):

Improved Stochastic EM with finite-grid block Gibbs person-sampling and item optimization via L-BFGS-B. The threshold parameters \tau_{ik} are constrained to maintain monotonicity during optimization.

References

Roberts, J. S., Donoghue, J. R., & Laughlin, J. E. (2000). A general item response theory model for unfolding unidimensional polytomous responses. Applied Psychological Measurement, 24(1), 3–32. doi:10.1177/01466216000241001

Usami, S. (2011). Generalized graded unfolding model with structural equation for subject parameters. Japanese Psychological Research, 53(3), 221–232.

See Also

sim.data.MGGUM, get.fit.index.MGGUM, logLik.MGGUM

Examples

sim <- sim.data.MGGUM(N = 20, I = 6, D = 2, length.poly = 4)
fit <- fit.MGGUM(sim$response, D = 2, method = "iStEM",
                 control.method = list(
                   vis = FALSE, seed = 123,
                   M = 2, B = 2, burnin.maxitr = 2,
                   maxitr = 3, eps1 = 10, eps2 = 10,
                   estimate.se = FALSE))
head(fit$theta$est)
gof <- get.fit.index(fit)
summary(gof)

Fit the Multidimensional Generalized Partial Credit Model (MGPCM)

Description

Fits a multidimensional generalization of the partial credit model to polytomous (multi-category) response data. Two estimation backends are provided: full Bayesian inference via Hamiltonian Monte Carlo (Stan) and a fast stochastic-EM algorithm (iStEM).

Usage

fit.MGPCM(
  data,
  D = NULL,
  Q.matrix = NULL,
  length.poly = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "MGPCM" with components:

npar

Number of free parameters.

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times D).

par

List with est, se, Rhat, free (I \times (D + K_{max})). Columns are a1..aD, d0, d1, ..., d_{K_{max}-1}.

Corr

List with est, se, Rhat (D \times D).

length.poly

Integer vector of per-item category counts.

logLik

Marginal log-likelihood (class "logLik").

call, arguments

Call and argument records.

Model Specification

Let Y_{ij} \in \{0, 1, \dots, K_i - 1\} denote the categorical response of person j = 1, \dots, N to item i = 1, \dots, I, where K_i \ge 2 is the number of response categories for item i. Let \boldsymbol{\theta}_j be the D-dimensional latent trait vector.

The category response probability implemented in both the C++ and Stan backends is a softmax over category scores:

P(Y_{ij} = k \mid \boldsymbol{\theta}_j) = \frac{ \exp\{k\,\eta_{ij} + d_{ik}\} }{ \sum_{r=0}^{K_i-1} \exp\{r\,\eta_{ij} + d_{ir}\} }, \qquad k = 0, 1, \dots, K_i - 1,

where

\eta_{ij} = \sum_{d=1}^{D} a_{id}\,\theta_{jd}.

The discrimination parameters satisfy a_{id} > 0 when q_{id} = 1 and a_{id} = 0 when q_{id} = 0. The d_{ik} values are category intercepts, not cumulative step difficulties; d_{i0} = 0 is fixed for identification and d_{i1}, \dots, d_{i,K_i-1} are free.

This formulation nests the standard (unidimensional) generalized partial credit model (Muraki, 1992) when D = 1 and all q_{i1} = 1.

Prior distributions:

a_{id} (free)

Log-normal: \log a_{id} \sim N(\mu_a, \sigma_a^2)

d_{ik} (free)

Normal: d_{ik} \sim N(\mu_d, \sigma_d^2) for k \ge 1; d_{i0}=0 is fixed. The same normal penalty is used by Stan and by the iStEM item update when use.prior = TRUE.

\boldsymbol{\theta}_j

Multivariate normal: \boldsymbol{\theta}_j \sim N_D(\mathbf{0}, \boldsymbol{\Sigma})

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. The joint posterior is sampled with multiple chains, providing posterior means, standard deviations, and \hat{R} diagnostics.

iStEM (method = "iStEM"):

Improved Stochastic EM alternating finite-grid block Gibbs person-sampling and item-parameter optimization (L-BFGS-B). Convergence monitored via Geweke diagnostics and batch-means MC error.

References

Muraki, E. (1992). A generalized partial credit model: Application of an EM algorithm. Applied Psychological Measurement, 16(2), 159–176. doi:10.1177/014662169201600206

Yao, L., & Schwarz, R. D. (2006). A multidimensional partial credit model for polytomous data. Applied Psychological Measurement, 30(4), 295–318.

See Also

sim.data.MGPCM, get.fit.index.MGPCM, logLik.MGPCM, rotate

Examples

sim <- sim.data.MGPCM(N = 20, I = 6, D = 2, length.poly = 4)
fit <- fit.MGPCM(sim$response, D = 2, method = "iStEM",
                 control.method = list(
                   vis = FALSE, seed = 123,
                   M = 2, B = 2, burnin.maxitr = 2,
                   maxitr = 3, eps1 = 10, eps2 = 10,
                   estimate.se = FALSE))
head(fit$theta$est)
fit$par$est[1:5, ]
gof <- get.fit.index(fit)
summary(gof)

Fit the Multidimensional Item Response Theory (MIRT) Model

Description

Fits a multidimensional extension of the 1PL, 2PL, 3PL, or 4PL item response model to binary response data. Two estimation backends are provided: full Bayesian inference via Hamiltonian Monte Carlo (Stan) and a fast stochastic-EM algorithm (iStEM) that scales to large data sets.

Usage

fit.MIRT(
  data,
  model = "2PL",
  D = NULL,
  Q.matrix = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "MIRT" containing the following components:

npar

Integer; number of free parameters (= freely estimated item parameters + free correlation elements).

method

Character; "stan" or "iStEM".

theta

List with matrices est, se, Rhat (N \times D); person parameter estimates.

par

List with matrices est, se, Rhat, free (I \times (D+3)); item parameter arrays. Columns are a1..aD, b, c, d.

Corr

List with matrices est, se, Rhat (D \times D); inter-trait correlation matrix.

Q.matrix

The I \times D Q-matrix used.

stan.obj

The stanfit object (Stan only; NULL for iStEM).

MCMC.obj

The list returned by rstan::extract() (Stan only; NULL for iStEM).

logLik

The marginal log-likelihood computed via Gauss–Hermite-type quadrature (class "logLik").

call

The matched call.

arguments

List of arguments used in fitting.

iStEM

List of iStEM diagnostic quantities (iStEM only), including burn-in size, convergence flags, and theta grid length.

Model Specification

Let Y_{ij} \in \{0, 1\} denote the binary response of person j = 1, \dots, N to item i = 1, \dots, I, and let \boldsymbol{\theta}_j = (\theta_{j1}, \dots, \theta_{jD})' denote the D-dimensional latent trait vector. The item response function (IRF) for the four model variants is:

M1PL (Rasch / one-parameter logistic):

P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j) = \frac{1}{1 + \exp\bigl[-\bigl(\sum_{d=1}^{D} a_{id}\,\theta_{jd} - b_i\bigr)\bigr]}, \qquad a_{id} = 1

The M1PL implementation fixes the slope to 1 and is restricted to D = 1; fixed unit slopes do not identify separate dimensions.

M2PL (two-parameter logistic):

P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j) = \frac{1}{1 + \exp\bigl[-\bigl(\sum_{d=1}^{D} a_{id}\,\theta_{jd} - b_i\bigr)\bigr]}, \qquad a_{id} > 0 \text{ if } q_{id} = 1,\; a_{id} = 0 \text{ otherwise}

The discrimination (slope) parameters a_{id} are freely estimated subject to the Q-matrix pattern and a log-normal prior.

M3PL (three-parameter logistic):

P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j) = c_i + (1 - c_i) \times \frac{1}{1 + \exp\bigl[-\bigl(\sum_{d=1}^{D} a_{id}\,\theta_{jd} - b_i\bigr)\bigr]}

where c_i \in [0, 1) is the lower-asymptote (pseudo-guessing) parameter.

M4PL (four-parameter logistic):

P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j) = c_i + (d_i - c_i) \times \frac{1}{1 + \exp\bigl[-\bigl(\sum_{d=1}^{D} a_{id}\,\theta_{jd} - b_i\bigr)\bigr]}

where c_i \in [0, 1) is the lower asymptote and d_i \in (0, 1] is the upper asymptote (1 - slippage).

In the unidimensional case (D = 1), these reduce to the standard 1PL–4PL models. For D > 1, the Q-matrix governs which dimensions load on each item, enabling both exploratory (default triangular identification) and confirmatory (user-specified Q-matrix) structures.

Prior distributions (Bayesian / MAP):

a_{id} (free)

Log-normal: \log a_{id} \sim N(\mu_a, \sigma_a^2). Defaults: \mu_a = 0.25, \sigma_a = 0.25.

b_i

Normal: b_i \sim N(\mu_b, \sigma_b^2). Defaults: \mu_b = 0, \sigma_b = 1.

c_i

Uniform: c_i \sim U(c_{\min}, c_{\max}). Defaults: c_{\min} = 0, c_{\max} = 0.35.

d_i

Uniform: d_i \sim U(d_{\min}, d_{\max}). Defaults: d_{\min} = 0.65, d_{\max} = 1.

\boldsymbol{\theta}_j

Multivariate normal: \boldsymbol{\theta}_j \sim N_D(\boldsymbol{\mu}_\theta, \boldsymbol{\Sigma}), with \boldsymbol{\mu}_\theta = \mathbf{0} and \boldsymbol{\Sigma} a correlation matrix.

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via Hamiltonian Monte Carlo (NUTS/HMC). The joint posterior of all parameters is explored using multiple Markov chains. Output includes posterior means, standard deviations, and \hat{R} convergence diagnostics for all parameters. Marginal log-likelihood is approximated via Gauss–Hermite-type quadrature over the latent space.

iStEM (method = "iStEM"):

An improved Stochastic EM (iStEM) algorithm that alternates between (a) sampling \boldsymbol{\theta}_j from its finite-grid full conditional as one D-dimensional block using the person's complete response likelihood and (b) maximizing the complete-data posterior for item parameters via L-BFGS-B. The inter-trait correlation matrix \boldsymbol{\Sigma} is estimated by constrained unit-diagonal normal-likelihood optimization. Convergence is monitored using Geweke (1992) convergence diagnostics and batch-means Monte Carlo error estimates. Standard errors are obtained from the final Monte Carlo chain.

References

Reckase, M. D. (2009). Multidimensional Item Response Theory. Springer. doi:10.1007/978-0-387-89976-3

Birnbaum, A. (1968). Some latent trait models and their use in inferring an examinee's ability. In F. M. Lord & M. R. Novick, Statistical theories of mental test scores (pp. 397–479). Addison-Wesley.

Barton, M. A., & Lord, F. M. (1981). An upper asymptote for the three-parameter logistic item-response model. ETS Research Report Series, 1981(1), i–21.

Geweke, J. (1992). Evaluating the accuracy of sampling-based approaches to the calculation of posterior moments. In J. M. Bernardo et al. (Eds.), Bayesian Statistics 4 (pp. 169–193). Oxford University Press.

See Also

good.of.fit for goodness-of-fit evaluation, get.fit.index.MIRT for MIRT-specific fit indices, sim.data.MIRT for simulating data from this model, rotate for post-hoc rotation of MIRT solutions, logLik.MIRT for marginal log-likelihood extraction.

Examples

# Simulate data from a 2-dimensional 2PL model
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")

# Fit via iStEM (fast, large-data friendly)
fit_istem <- fit.MIRT(sim$response, model = "m2pl", D = 2,
                      method = "iStEM",
                      control.method = list(
                        vis = FALSE, seed = 123,
                        M = 2, B = 2, burnin.maxitr = 2,
                        maxitr = 3, eps1 = 10, eps2 = 10,
                        estimate.se = FALSE))


# stan code, long time
# Fit via Stan (full Bayesian inference, computationally heavier)
fit_stan <- fit.MIRT(sim$response, model = "m2pl", D = 2,
                     method = "stan",
                     control.method = list(
                       chains = 1, iter = 200, warmup = 100,
                       cores = 1, seed = 123))


# Extract results
print(fit_istem$par$est)       # item parameter estimates
print(fit_istem$theta$est)     # person trait estimates
print(fit_istem$Corr$est)      # factor correlation matrix

# Compute goodness-of-fit indices
gof <- get.fit.index(fit_istem)
summary(gof)

Fit the Thurstonian Item Response Theory (TIRT) Model

Description

Fits the Thurstonian IRT model for forced-choice data. Unlike the FCMIRT/FCGGUM models that operate on the item-level endorsement probabilities, the TIRT model works directly at the level of paired comparisons: each pairwise comparison is treated as a binary outcome governed by a latent difference process with a probit link.

Usage

fit.TIRT(
  data,
  Q.matrix,
  block.items = NULL,
  fc.type = NULL,
  method = c("iStEM", "stan"),
  control.model = NULL,
  control.method = NULL
)

Arguments

Value

An object of class "TIRT" containing:

npar

Number of free parameters.

method

"stan" or "iStEM".

theta

List with est, se, Rhat (N \times D).

par

List with est, se, Rhat, free (I \times (D + 1)). Columns include the loading \lambda_i on the design dimension and \psi_i^2.

Corr

List with est, se, Rhat (D \times D).

gamma.matrix

List with est, se, Rhat (I \times I); pairwise intercept matrix.

pairs.matrix, pairs.value, response, response.total

Pairwise and response data structures.

logLik

Marginal log-likelihood (class "logLik").

Model Specification

Pairwise utility difference. For a pair of statements (i, k) in block b, the latent comparative judgment is:

y_{j,ik}^* = -\gamma_{ik} + \lambda_i \sum_{d=1}^{D} q_{id}\,\theta_{jd} - \lambda_k \sum_{d=1}^{D} q_{kd}\,\theta_{jd} + \varepsilon_{j,i} - \varepsilon_{j,k},

where:

• \gamma_{ik} is the pairwise intercept (unfolding threshold parameter). Skew-symmetry requires \gamma_{ik} = -\gamma_{ki}.

• \lambda_i > 0 is the loading magnitude of statement i; the sign of the statement direction is carried by q_{id}.

• q_{id} \in \{-1, 0, 1\} is the Q-matrix entry; each row has exactly one non-zero entry.

• \varepsilon_{j,i} \sim N(0, \psi_i^2) is the uniqueness (error) of statement i.

Binary pairwise response. The observed response is

Y_{j,ik} = \begin{cases} 1, & \text{if } y_{j,ik}^* \ge 0 \quad (\text{prefer } i \text{ over } k), \\ 0, & \text{otherwise}. \end{cases}

Under the normality of errors, the probability is:

P(Y_{j,ik} = 1 \mid \boldsymbol{\theta}_j) = \Phi\!\left( \frac{ -\gamma_{ik} + \lambda_i\,\mathbf{q}_i'\boldsymbol{\theta}_j - \lambda_k\,\mathbf{q}_k'\boldsymbol{\theta}_j }{ \sqrt{\psi_i^2 + \psi_k^2} } \right),

where \Phi(\cdot) is the standard normal CDF.

Identification constraints. Several standard constraints are applied:

• Case A (I_{\text{block}} = 2, D > 2): All \psi_i^2 = 0.5 are fixed.

• Case B (D = 2, I_{\text{block}} = 2): The first block's \lambda_i are fixed to 0.80, all \psi_i^2 = 0.5 are fixed.

• General case: The last item in each block has \psi_i^2 = 1.0 fixed. Pairwise \gamma_{ik} parameters for comparisons that are never observed under the supplied RANK/MOLE/PICK design are fixed to gamma.mu.

Correlation structure. The inter-trait correlation matrix \boldsymbol{\Sigma} is estimated as in the MIRT model. In the Stan file, \boldsymbol{\theta}_j is centered at zero; the iStEM backend uses control.model$theta.mu as the mean in the normal kernel.

Estimation Methods

Stan (method = "stan"):

Full Bayesian inference via HMC. The probit likelihood is evaluated over all pairwise comparisons.

iStEM (method = "iStEM"):

Improved Stochastic EM. Person sampling uses finite-grid block Gibbs; structural parameters (\lambda, \psi^2, \gamma) updated via optimization or closed-form steps.

References

Brown, A., & Maydeu-Olivares, A. (2011). Item response modeling of forced-choice questionnaires. Educational and Psychological Measurement, 71(3), 460–502. doi:10.1177/0013164410375112

Maydeu-Olivares, A., & Brown, A. (2010). Item response modeling of paired comparison and ranking data. Multivariate Behavioral Research, 45(6), 935–974.

Thurstone, L. L. (1927). A law of comparative judgment. Psychological Review, 34(4), 273–286.

See Also

sim.data.TIRT, get.fit.index.TIRT, logLik.TIRT

Examples

sim <- sim.data.TIRT(N.person = 20, N.block = 3, I.block = 2,
                     D = 2, fc.type = "RANK")
fit <- fit.TIRT(sim$data, Q.matrix = sim$Q.matrix,
                block.items = sim$block.items,
                fc.type = "RANK", method = "iStEM",
                control.method = list(
                  vis = FALSE, seed = 123,
                  M = 2, B = 2, burnin.maxitr = 2,
                  maxitr = 3, eps1 = 10, eps2 = 10,
                  estimate.se = FALSE))
head(fit$theta$est)
cor(fit$theta$est, sim$theta)
gof <- get.fit.index(fit)
summary(gof)

S3 Methods: fitted

Description

Extract model-implied response probabilities from fitted ForceChoice model objects. Returns the conditional probability of each observed response given each person's estimated latent trait \hat{\boldsymbol{\theta}}_j, evaluated via the model's response function.

Usage

## S3 method for class 'MIRT'
fitted(object, ...)

## S3 method for class 'MGPCM'
fitted(object, ...)

## S3 method for class 'MGGUM'
fitted(object, ...)

## S3 method for class 'FCMIRT'
fitted(object, ...)

## S3 method for class 'FCDCM'
fitted(object, ...)

## S3 method for class 'FCGDINA'
fitted(object, ...)

## S3 method for class 'FCGGUM'
fitted(object, ...)

## S3 method for class 'TIRT'
fitted(object, ...)

Arguments

Details

For binary-response models, each entry is the endorsement probability P(Y_{ij}=1 \mid \hat{\boldsymbol{\theta}}_j). For polytomous models, probabilities are returned in stacked format (one column per category). For forced-choice models, each entry is the probability of the observed ranking pattern in the given block.

Value

A numeric matrix of model-implied probabilities. Dimensions:

• Binary models (MIRT, TIRT): N \times I

• Polytomous models (MGPCM, MGGUM): N \times \sum K_i (stacked category probabilities)

• Forced-choice models (FCMIRT, FCGDINA, FCGGUM): N \times \sum K_b (block-pattern probabilities)

• FCDCM: N \times B (marginal block-choice probabilities after integrating over 2^D attribute patterns)

Methods (by class)

• fitted(MIRT): Fitted probabilities for MIRT objects. Returns N \times I matrix of endorsement probabilities.

• fitted(MGPCM): Fitted probabilities for MGPCM objects. Returns stacked category probability matrix.

• fitted(MGGUM): Fitted probabilities for MGGUM objects.

• fitted(FCMIRT): Fitted probabilities for FCMIRT objects. Returns block-pattern probability matrix.

• fitted(FCDCM): Fitted probabilities for FCDCM objects. Returns N \times B matrix of marginal block-choice probabilities after integrating over 2^D attribute patterns.

• fitted(FCGDINA): Fitted probabilities for FCGDINA objects. Returns block-pattern probability matrix after integrating over posterior attribute classes.

• fitted(FCGGUM): Fitted probabilities for FCGGUM objects.

• fitted(TIRT): Fitted probabilities for TIRT objects. Returns N \times I_{pairs} matrix of pairwise comparison probabilities.

Forced-Choice Data Conversion Formats

Description

Documents the three data objects used by the forced-choice conversion helpers: human-readable data, block definitions block.items, and model-ready response matrices. This overview is intended as the starting point before using get.response.from.data, get.data.from.response, the TIRT-specific converters, or the FCDCM-specific converters.

Details

The package uses two layers of forced-choice representation:

data

An N \times B matrix or data frame that is easy to read and edit. Rows are persons and columns are forced-choice blocks. A cell records the observed ordering with item labels separated by ">". For example, "3>4>5" means item 3 was ranked above item 4, which was ranked above item 5.

block.items

A list of length B. Element b gives the item labels appearing in column b of data. This object is the bridge between column order in the data file and item rows in model parameter matrices such as Q.matrix.

response

The compact numeric representation consumed by model fitting code. Its meaning depends on the model family. For FCGGUM, FCMIRT, and FCGDINA, response is an N \times B matrix of 1-based pattern indices. For TIRT, response is an N \times P matrix of pairwise binary outcomes. For FCDCM, response is an N \times B binary matrix for two-item blocks.

Choosing a Converter

FCGGUM, FCMIRT, and FCGDINA

Use get.response.from.data to convert character strings to pattern indices, and get.data.from.response for the inverse conversion.

TIRT

Use get.response.from.data.TIRT and get.data.from.response.TIRT. TIRT expands each block to pairwise comparisons, so its response columns are pairs rather than block-level pattern numbers.

FCDCM

Use get.response.from.data.FCDCM and get.data.from.response.FCDCM. Each block has exactly two statements, so response = 1 means the first statement in block.items[[b]] was preferred and response = 0 means the second statement was preferred.

Recovering block.items

Use get.block.items.from.data for generic multi-item forced-choice data and get.block.items.from.data.FCDCM for FCDCM pair data. Recovery is only possible for item labels that actually appear in the observed strings.

Core Conventions

• The bth element of block.items always corresponds to the bth column of data or response.

• fc.type = "RANK" expects a complete ranking such as "3>4>5" for a three-item block.

• fc.type = "MOLE" expects a most-least string such as "3>5": item 3 is most preferred and item 5 is least preferred.

• fc.type = "PICK" expects a single most-preferred item such as "3".

• Generic FC pattern-index responses are 1-based. They are row numbers in the deterministic pattern matrix generated internally; see generate_fc_permutation_patterns for the public pattern generator.

• TIRT data should use consecutive item labels across blocks, for example list(1:2, 3:5, 6:8). This is the format returned by sim.data.TIRT and expected by the TIRT conversion routines.

See Also

get.block.items.from.data, get.response.from.data, get.data.from.response, get.response.from.data.TIRT, get.data.from.response.TIRT, get.response.from.data.FCDCM, get.data.from.response.FCDCM

Examples

# Generic FC conversion: response is a block-level pattern index.
block.items <- list(1:2, 3:5)
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
resp <- get.response.from.data(dat, block.items, fc.type = "RANK")
resp
get.data.from.response(resp, block.items, fc.type = "RANK")

# TIRT conversion: response is pairwise 0/1 data.
tirt <- get.response.from.data.TIRT(dat, block.items, fc.type = "RANK")
tirt$response
get.data.from.response.TIRT(
  tirt$response, block.items, fc.type = "RANK",
  pairs.value = tirt$pairs.value
)

# FCDCM conversion: response is binary within each two-item block.
fcdcm.items <- list(c(1L, 3L), c(2L, 4L))
fcdcm.dat <- data.frame(
  block.1 = c("1>3", "3>1"),
  block.2 = c("2>4", "4>2"),
  stringsAsFactors = FALSE
)
fcdcm.resp <- get.response.from.data.FCDCM(fcdcm.dat, fcdcm.items)
fcdcm.resp$response
get.data.from.response.FCDCM(fcdcm.resp$response, fcdcm.items)

Compute forced-choice pattern probabilities from item endorsement probabilities

Description

Transforms item-level endorsement probabilities into block-level ranking pattern probabilities via the sequential Luce/Plackett choice rule. This is an R implementation of the C++ forced_choice_from_agree function used by cpp_model_FCMIRT and cpp_model_FCGGUM.

Usage

forced_choice_from_agree(agree, patterns.total, patterns)

Arguments

Value

An N \times \sum_B P_b matrix of forced-choice pattern probabilities, where P_b is the number of observed patterns for block b.

Degrees of freedom for a correlation matrix

Description

Degrees of freedom for a correlation matrix

Usage

free_corr_npar(D, include_corr = TRUE)

Arguments

Value

Integer, the number of free parameters in a D x D correlation matrix.

Generate forced-choice permutation patterns

Description

Produces the full-ranking patterns (patterns.total) and the observed patterns (patterns) for each block, based on the forced-choice response type.

Usage

generate_fc_permutation_patterns(block.items, fc.type)

Arguments

Value

A named list with components patterns.total (list of full-ranking matrices) and patterns (list of observed-pattern matrices).

Generate latent trait vectors from a multivariate normal distribution

Description

When D > 1, uses MASS::mvrnorm with the supplied correlation matrix. When D == 1, uses standard normal draws.

Usage

generate_theta_mvn(N, D, Corr)

Arguments

Value

An N \times D numeric matrix of latent trait values.

Extract Block Items from Forced-Choice Data

Description

Infers the item composition of each forced-choice block from a character data matrix. Each cell should encode the within-block item ordering (e.g. "2>1>3" for a rank-3 block). The function parses all non-missing cells per block and returns sorted, unique item indices.

This function is the recommended way to recover block.items when only character-rank data are available. It works for all forced-choice types ("RANK", "MOLE", "PICK") as long as every item appears at least once across persons.

Usage

get.block.items.from.data(data)

Arguments

Details

The returned block.items list defines the block layout used by the other converters. If data has B columns, the result has B elements, and result element b belongs to data column b. Item labels are treated as global item indices; they are not recoded to local positions.

The function scans observed strings only. Therefore, for partial-response formats, it can only recover items that appear in the observed partial strings:

• For "RANK", a complete ranking normally contains every item in the block, so one valid row can be sufficient.

• For "MOLE", only most- and least-preferred items appear in each cell. An item that is never chosen as most or least cannot be recovered from data alone.

• For "PICK", only picked items appear. Items that are never picked cannot be recovered from data alone.

In those partial-response cases, pass a complete user-defined block.items list to the fitting or conversion function when the raw data do not mention every item.

Value

A list of length B. Each element is an integer vector of global item indices appearing in that block, sorted in ascending order.

See Also

get.block.items.from.data.FCDCM for the FCDCM (binary-pair) variant.

get.response.from.data to convert character data to an integer pattern-index matrix.

Examples

# 3 persons, 2 blocks.
# Block 1 contains items 1 and 2; block 2 contains items 3, 4, and 5.
dat <- data.frame(
  block.1 = c("1>2", "2>1", "1>2"),
  block.2 = c("3>4>5", "5>4>3", "4>3>5"),
  stringsAsFactors = FALSE
)
get.block.items.from.data(dat)

Extract Block Items from FCDCM Data

Description

Recovers the two-item composition of each FCDCM block from a character data matrix of "a>b" / "b>a" preference strings. Because every FCDCM block always compares exactly two statements, this function only needs to inspect the first non-missing row of each column.

Usage

get.block.items.from.data.FCDCM(data)

Arguments

Details

The returned item pair is sorted in ascending order. For example, both "1>3" and "3>1" imply c(1L, 3L) for that block. This sorted pair is then the default coding direction used by get.response.from.data.FCDCM: response value 1 means the first element of the pair was preferred, and response value 0 means the second element was preferred.

This helper assumes the two compared statements are fixed within each column. If a column accidentally mixes different item pairs, only the first parseable non-missing cell determines the returned pair, so such data should be cleaned before conversion.

Value

A list of length B. Each element is a two-element integer vector c(a, b) with a < b.

See Also

get.block.items.from.data for the generic multi-item variant used by FCGGUM, FCMIRT, and TIRT.

get.response.from.data.FCDCM to convert FCDCM data strings to a 0/1 response matrix.

Examples

dat <- data.frame(
  b1 = c("1>3", "3>1", "1>3"),
  b2 = c("2>4", "2>4", "4>2"),
  stringsAsFactors = FALSE
)
get.block.items.from.data.FCDCM(dat)

Convert an Integer Response (Pattern-Index) Matrix to FC Data Strings

Description

Converts an integer matrix of pattern indices back to human-readable forced-choice data strings. This is the generic converter used by FCGGUM, FCMIRT, and FCGDINA where each column of the response matrix is an index into the block's observed permutation-pattern list.

Usage

get.data.from.response(response, block.items, fc.type = "RANK")

Arguments

Value

A data frame with N rows and B columns. Column names are "block.1", ..., "block.B". Cell values are character strings: full rankings ("2>5>8") for "RANK", "best>worst" pairs for "MOLE", and single integers for "PICK".

Pattern Generation and Numbering

For a block with K items, the set of possible response patterns depends on the forced-choice type:

RANK

All K! full permutations of the K items are generated. The patterns are listed in lexicographic order of the within-block item positions. For example, a 3-item block with items c(2,5,8) produces 3! = 6 patterns: (2,5,8), (2,8,5), (5,2,8), (5,8,2), (8,2,5), (8,5,2). Pattern index 1 means the first pattern was observed.

MOLE

For a K-item block, K(K-1) most-least observation patterns are possible: K choices for the most preferred item times K-1 choices for the least preferred item. Pattern (a,b) means item a was most preferred and item b was least preferred.

PICK

For a K-item block, exactly K patterns exist: one for each possible most-preferred item.

In all cases the pattern index (an integer from 1 to the number of observed patterns) is the row number in the matrix returned by the internal permutation helper for that block. The same deterministic pattern construction is exposed by generate_fc_permutation_patterns.

This format is a compact block-level encoding. One response column equals one forced-choice block, even when the block contains more than two items. This is the representation expected by the generic forced-choice model families FCGGUM, FCMIRT, and FCGDINA. It should not be confused with the TIRT pairwise format, where one block usually expands to several pair columns.

See Also

get.response.from.data for the reverse conversion.

generate_fc_permutation_patterns for pattern generation.

get.data.from.response.TIRT for the TIRT-specific converter.

Examples

# 2 persons, 2 RANK blocks.
items <- list(1:2, 3:5)
resp <- cbind(c(1, 2), c(1, 6))
get.data.from.response(resp, items, fc.type = "RANK")

# Mixed block formats: first block is most-least, second block is pick.
mixed.items <- list(1:3, 4:6)
mixed.resp <- cbind(c(1, 6), c(1, 3))
get.data.from.response(
  mixed.resp, mixed.items, fc.type = c("MOLE", "PICK")
)

Convert an FCDCM Response Matrix to FC Data Strings

Description

Converts a binary FCDCM response matrix (0/1 or 1/2 coding) back to human-readable "a>b" / "b>a" preference strings. Each block compares exactly two items; the response indicates which item was selected.

Usage

get.data.from.response.FCDCM(response, block.items)

Arguments

Value

A data frame with N rows and B columns. Each cell is a character string "a>b" or "b>a".

Response Coding

Two coding conventions are accepted:

• 0/1 coding: 1 means the first-named item in block.items was preferred; 0 means the second-named item was preferred.

• 1/2 coding: 1 means the first-named item; 2 means the second-named item. This is auto-detected and converted.

The output always uses "a>b" format where a and b are the two item indices in the comparison order.

The direction is controlled by block.items. If block.items[[1]] = c(1L, 3L), then response value 1 becomes "1>3" and response value 0 becomes "3>1". With 1/2 coding, value 1 has the same meaning as above and value 2 means the second item. A response matrix must use one coding convention consistently; mixed 0/1/2 values are rejected.

See Also

get.response.from.data.FCDCM for the reverse conversion.

get.data.from.response for the generic multi-item converter.

Examples

items <- list(c(1L, 3L), c(2L, 4L))
resp <- cbind(c(1, 0, 1), c(0, 1, 1))
dat <- get.data.from.response.FCDCM(resp, items)
dat
get.response.from.data.FCDCM(dat, items)$response

# The same preferences can also be supplied as 1/2 responses.
resp12 <- cbind(c(1, 2, 1), c(2, 1, 1))
get.data.from.response.FCDCM(resp12, items)

Convert TIRT Pairwise-Response Matrix to Forced-Choice Data Strings

Description

Converts a Thurstonian IRT pairwise-response matrix back to the human-readable forced-choice strings used in data. This is the inverse of get.response.from.data.TIRT.

Usage

get.data.from.response.TIRT(
  response,
  block.items,
  fc.type = NULL,
  pairs.value = NULL
)

Arguments

Details

TIRT differs from the generic FC converters because the model is expressed through pairwise comparisons. The input response is therefore not a block-level pattern-index matrix. It is an N \times P binary matrix, where each column is one observed item pair and each entry is coded:

• 1: the first item in that pair was preferred;

• 0: the second item in that pair was preferred.

The number of response columns contributed by a block with K items is determined by fc.type:

RANK

All K(K-1)/2 unordered pairs are observed. Pair columns are generated in the order (1,2), (1,3), \dots, (K-1,K) using the item labels in block.items[[b]].

MOLE

Only the pairs needed to identify the most- and least-preferred items are retained. The block contributes 2K - 3 response columns per person.

PICK

Only the pairs involving the picked item are retained. The block contributes K - 1 response columns per person.

For "MOLE" and "PICK", the identities of the retained pairs can vary by person. The pairs.value object records those person-specific pair definitions and is required to reconstruct data strings without ambiguity. It is normally copied directly from the pairs.value component returned by get.response.from.data.TIRT.

TIRT conversion assumes consecutive item labels across blocks, for example list(1:2, 3:5). This is the layout returned by sim.data.TIRT.

Value

A data frame with N rows and B columns. Column names are "block.1", "block.2", etc. Cell values are character strings encoding the within-block ordering: full rankings for "RANK", "best>worst" for "MOLE", and single integers for "PICK".

See Also

get.response.from.data.TIRT for the reverse conversion.

get.data.from.response for the generic (non-TIRT) converter used by FCGGUM and FCMIRT.

Examples

# 2 RANK blocks: block 1 has items 1,2; block 2 has items 3,4,5.
items <- list(1:2, 3:5)
resp <- cbind(
  c(1, 0),            # block 1 pair: 1 vs 2
  c(1, 0),            # block 2 pair: 3 vs 4
  c(1, 0),            # block 2 pair: 3 vs 5
  c(1, 0)             # block 2 pair: 4 vs 5
)
get.data.from.response.TIRT(resp, items, fc.type = "RANK")

Goodness-of-Fit Indices for Fitted Models

Description

Generic function to compute a comprehensive suite of model-fit diagnostics for fitted ForceChoice model objects. The function dispatches on the class of the fitted model and returns an object of class "good.of.fit" containing likelihood-based, limited-information, and residual-based diagnostics.

Usage

## S3 method for class 'FCDCM'
get.fit.index(object, ...)

## S3 method for class 'FCGDINA'
get.fit.index(object, ...)

## S3 method for class 'FCGGUM'
get.fit.index(object, ...)

## S3 method for class 'FCMIRT'
get.fit.index(object, ...)

## S3 method for class 'MGGUM'
get.fit.index(object, ...)

## S3 method for class 'MGPCM'
get.fit.index(object, ...)

## S3 method for class 'MIRT'
get.fit.index(object, ...)

## S3 method for class 'TIRT'
get.fit.index(object, ...)

Arguments

Value

An object of class "good.of.fit". Use summary.good.of.fit and print.good.of.fit for formatted output. Key components:

• LogLik, deviance, AIC, AICc, BIC, CAIC, SABIC, HQIC

• M2.value, df, p.value

• RMSEA2, RMSEA.lower, RMSEA.upper, RMSEA.p.close

• SRMSR

• CFI, TLI, IFI

• McFadden.R2, CoxSnell.R2, Nagelkerke.R2

• q3.mean, q3.abs.max, q3.adjusted.abs.max

• posterior.entropy, posterior.entropy.normalized

Methods (by class)

• get.fit.index(FCDCM): FCDCM model: binary block responses with quadrature over higher-order \theta and exact marginalization over 2^D attribute patterns.

• get.fit.index(FCGDINA): FCGDINA model: forced-choice CDM with nominal binary expansion; within-block pairs excluded.

• get.fit.index(FCGGUM): FCGGUM model: forced-choice unfolding with nominal binary expansion; within-block pairs excluded.

• get.fit.index(FCMIRT): FCMIRT model: forced-choice ranking data expanded to nominal binary indicators; within-block pairs excluded from bivariate moments.

• get.fit.index(MGGUM): MGGUM model: polytomous unfolding responses with M2* category-collapsed construction.

• get.fit.index(MGPCM): MGPCM model: polytomous responses with M2* category-collapsed construction.

• get.fit.index(MIRT): MIRT model: binary responses with Gauss–Hermite quadrature over D-dimensional latent space.

• get.fit.index(TIRT): TIRT model: pairwise binary responses with within-block pairs excluded via bivariate.groups.

Limited-Information M2 Framework

Following Maydeu-Olivares and Joe (2005, 2006), the test statistic uses first- and second-order marginal moments rather than the full contingency table, making it suitable for sparse high-dimensional responses.

Let \boldsymbol{\pi}(\boldsymbol{\psi}) be the vector of M model-implied univariate and bivariate moments, \mathbf{p} the observed moments, and \boldsymbol{\Delta} = \partial\boldsymbol{\pi}/\partial\boldsymbol{\psi}' the Jacobian. The M2 statistic is:

M_2 = N\,\mathbf{e}'\hat{\mathbf{C}}_2\mathbf{e}, \qquad \mathbf{e} = \mathbf{p} - \boldsymbol{\pi}(\hat{\boldsymbol{\psi}}),

where \hat{\mathbf{C}}_2 = \boldsymbol{\Delta}_c (\boldsymbol{\Delta}_c'\hat{\boldsymbol{\Xi}}_2\boldsymbol{\Delta}_c)^{-1} \boldsymbol{\Delta}_c' with \boldsymbol{\Delta}_c the orthogonal complement of \boldsymbol{\Delta}. Under the null, M_2 \sim \chi^2_{M - p} asymptotically.

Fit Index Formulas

Information criteria (Akaike 1974; Schwarz 1978; Bozdogan 1987; Sclove 1987; Hannan & Quinn 1979):

\begin{aligned} \text{AIC} &= -2\ell + 2p, \\ \text{AICc} &= \text{AIC} + \frac{2p(p+1)}{N-p-1}, \\ \text{BIC} &= -2\ell + p\log N, \\ \text{CAIC} &= -2\ell + p(\log N + 1), \\ \text{SABIC} &= -2\ell + p\log\!\bigl(\frac{N+2}{24}\bigr), \\ \text{HQIC} &= -2\ell + 2p\log(\log N). \end{aligned}

RMSEA (Browne & Cudeck 1993):

\text{RMSEA} = \sqrt{\max\!\left(0,\; \frac{M_2 - df}{N \cdot df}\right)}, \qquad df = M - p.

Confidence intervals via non-central \chi^2 inversion; close-fit test H_0: \text{RMSEA} \le 0.05.

SRMSR:

\text{SRMSR} = \sqrt{\frac{1}{J}\sum_{i<j}(r_{ij}^{\text{obs}} - r_{ij}^{\text{model}})^2}.

CFI / TLI / IFI (Bentler 1990; Tucker & Lewis 1973; Bollen 1989):

\begin{aligned} \text{CFI} &= 1 - \frac{\max(M_2 - df, 0)}{\max(M_2^{\text{null}} - df^{\text{null}},\; M_2 - df,\; 0)}, \\[4pt] \text{TLI} &= \frac{M_2^{\text{null}}/df^{\text{null}} - M_2/df}{M_2^{\text{null}}/df^{\text{null}} - 1}, \\[4pt] \text{IFI} &= \frac{M_2^{\text{null}} - M_2}{M_2^{\text{null}} - df}. \end{aligned}

Pseudo-R^2:

\begin{aligned} R^2_{\text{McF}} &= 1 - \ell/\ell_0, \\ R^2_{\text{CS}} &= 1 - \exp\!\bigl(\tfrac{2}{N}(\ell_0 - \ell)\bigr), \\ R^2_{\text{N}} &= R^2_{\text{CS}} / \bigl(1 - \exp(2\ell_0/N)\bigr), \\ R^2_{\text{AN}} &= G^2/(G^2 + N), \quad G^2 = D_0 - D. \end{aligned}

Yen's Q3 (Yen 1984):

Q_{3,ik} = \text{Corr}(r_{ji}, r_{jk}), \qquad r_{ji} = Y_{ji} - E[Y_{ji} \mid \hat{\boldsymbol{\theta}}_j].

Posterior diagnostics (Celeux & Soromenho 1996):

E = -\frac{1}{N}\sum_{j=1}^{N}\sum_{c=1}^{Q}\hat{\tau}_{jc}\log\hat{\tau}_{jc}, \qquad E_{\text{norm}} = 1 - E / \log Q.

Heuristic Guidelines

• RMSEA: \le 0.05 close, \le 0.08 reasonable

• SRMSR: \le 0.08 acceptable (Hu & Bentler 1999)

• CFI / TLI: \ge 0.95 good, \ge 0.90 acceptable

• Normalized entropy: \ge 0.70 acceptable separation

References

Akaike, H. (1974). IEEE Trans. Autom. Control, 19, 716–723. Bozdogan, H. (1987). Psychometrika, 52, 345–370. Browne, M. W., & Cudeck, R. (1993). In Bollen & Long (Eds.), Testing structural equation models (pp. 136–162). Sage. Celeux, G., & Soromenho, G. (1996). J. Classification, 13, 195–212. Hu, L. T., & Bentler, P. M. (1999). Struct. Equ. Modeling, 6, 1–55. Maydeu-Olivares, A., & Joe, H. (2005). JASA, 100, 1009–1020. Maydeu-Olivares, A., & Joe, H. (2006). Psychometrika, 71, 713–732. Schwarz, G. (1978). Ann. Statist., 6, 461–464. Yen, W. M. (1984). Appl. Psychol. Meas., 8, 125–145.

See Also

good.of.fit for the underlying engine, summary.good.of.fit for formatted summary tables.

Examples

sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)
gof <- get.fit.index(fit)
summary(gof)

# Custom RMSEA confidence level (99%)
gof99 <- get.fit.index(fit, alpha = 0.005)
summary(gof99)

Extract pointwise log-likelihood matrix

Description

For Stan-fitted models, returns the posterior draws of pointwise log-likelihood (an S \times N_{\text{obs}} matrix for most models, or S \times N for FCDCM and FCGDINA). For EM and iStEM fits, returns NULL.

Usage

get.log_lik(object, ...)

## Default S3 method:
get.log_lik(object, ...)

Arguments

Details

The returned matrix can be passed directly to loo or waic for model comparison.

Value

An S \times N matrix of pointwise log-likelihood draws (Stan), or NULL (EM / iStEM).

Methods (by class)

• get.log_lik(default): Default method; returns object$log_lik when present and NULL otherwise.

Examples

# stan code, long time
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "2PL")
fit <- fit.MIRT(sim$response, model = "2PL", D = 2, method = "stan")
log_lik <- get.log_lik(fit)
loo::loo(log_lik)
loo::waic(log_lik)

Convert FC Data Strings to an Integer Response (Pattern-Index) Matrix

Description

Parses human-readable forced-choice data strings into integer pattern indices. This is the generic converter used by FCGGUM, FCMIRT, and FCGDINA. Each data cell is matched against the full set of permutation/observation patterns for that block, and the resulting row index is stored in the response matrix.

Usage

get.response.from.data(data, block.items, fc.type = "RANK")

Arguments

Value

An N \times B integer matrix. Each entry is a 1-based pattern index (row number in the block's pattern matrix). Column names are "block.1", ..., "block.B".

Pattern Matching

The conversion first generates all possible observation patterns for each block via the internal permutation helper:

• RANK (K items): all K! full rankings, ordered lexicographically by within-block position.

• MOLE: K(K-1) most-least observation patterns.

• PICK: K best-only patterns.

Each data cell string is parsed into an integer vector of global item indices, which is then matched (as an ordered sequence) against the pattern matrix. The 1-based row index of the match becomes the response value. Pattern ordering is deterministic and reproducible.

A non-missing cell that cannot be matched to a valid pattern is returned as NA_integer_. This is useful for data-screening workflows: after conversion, check anyNA(response) before passing the response matrix to a fitting function.

See Also

get.data.from.response for the reverse conversion.

generate_fc_permutation_patterns for pattern generation details.

get.response.from.data.TIRT for the TIRT-specific converter.

Examples

# 2 persons, 2 RANK blocks.
items <- list(1:2, 3:5)
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
resp <- get.response.from.data(dat, items, fc.type = "RANK")
resp
get.data.from.response(resp, items, fc.type = "RANK")

# Mixed block formats: most-least plus pick.
dat.mixed <- data.frame(
  mole = c("1>3", "3>2"),
  pick = c("4", "6"),
  stringsAsFactors = FALSE
)
mixed.items <- list(1:3, 4:6)
get.response.from.data(
  dat.mixed, mixed.items, fc.type = c("MOLE", "PICK")
)

Convert FCDCM Data Strings to a Binary Response Matrix

Description

Parses FCDCM preference strings ("a>b" / "b>a") into a 0/1 binary response matrix. Each block compares exactly two items.

Usage

get.response.from.data.FCDCM(data, block.items)

Arguments

Details

For each block, only two strings are valid: "a>b" and "b>a", where a = block.items[[b]][1] and b = block.items[[b]][2]. Leading and trailing whitespace is ignored. Missing values or strings that do not match the block-specific item pair produce an error, because FCDCM fitting requires a complete binary response matrix.

If block.items was obtained from get.block.items.from.data.FCDCM, the pair is sorted in ascending order. In that common workflow, response value 1 means the smaller item index was preferred and response value 0 means the larger item index was preferred.

Value

A named list with component response, an N \times B integer matrix coded 0/1.

Response Coding

The output uses 0/1 coding: 1 indicates preference for the first-named item in block.items[[b]]; 0 indicates preference for the second-named item. This coding is the native format expected by the FCDCM model estimation functions.

See Also

get.data.from.response.FCDCM for the reverse conversion.

get.response.from.data for the generic multi-item converter.

Examples

items <- list(c(1L, 3L), c(2L, 4L))
dat <- data.frame(
  b1 = c("1>3", "3>1", "1>3"),
  b2 = c("2>4", "2>4", "4>2"),
  stringsAsFactors = FALSE
)
get.response.from.data.FCDCM(dat, items)
get.data.from.response.FCDCM(
  get.response.from.data.FCDCM(dat, items)$response, items
)

Convert TIRT Forced-Choice Data to Pairwise-Response Matrix

Description

Parses human-readable forced-choice data strings (full rankings, most-least choices, or best-only picks) into the Thurstonian IRT pairwise binary response format. Each unordered item pair within a block receives a 1/0 outcome indicating which item was preferred.

Usage

get.response.from.data.TIRT(data, block.items, fc.type = NULL)

Arguments

Details

This function expands each block column in data into one or more pairwise response columns. Pair columns are grouped by block in the same order as block.items. Within a pair column, the coding is always 1 if the first item in the pair is preferred, and 0 if the second item is preferred.

Item labels must match the values supplied in block.items; they do not need to be consecutive. For example, if block.items = list(c(2, 7), c(10, 20, 30)), the second block can contain "10>20>30", "30>10", or "20", depending on fc.type.

Value

A list with two components:

response

An N \times P integer matrix of pairwise binary outcomes (1/0). For block b, the number of contributed columns is K_b(K_b-1)/2 for RANK, 2K_b - 3 for MOLE, and K_b - 1 for PICK.

pairs.value

A list of length N, each element being a list of length B of integer pair-definition matrices. Required as input for get.data.from.response.TIRT.

Pattern Naming and Pair Encoding

For a block with K items, the number of pair columns depends on fc.type: K(K-1)/2 for "RANK", 2K - 3 for "MOLE", and K - 1 for "PICK". For each retained pair:

• RANK: the item ranked earlier in the ordering is preferred. For block.items[[b]] = 3:5, pair order is (3,4), (3,5), (4,5). The string "3>4>5" therefore produces pairwise responses 1, 1, 1.

• MOLE: only the most- and least-preferred items are identified (e.g. "3>2" in a 3-item block). The remaining items are treated as tied in the middle, producing preference relations consistent with the partial ordering.

• PICK: only the most-preferred item is identified (e.g. "3" in a 3-item block). All other items are treated as equally less preferred.

The pairs.value component records the actual pair matrices used for each person and block. It is essential for converting MOLE/PICK responses back to data, because the retained pair set can differ across persons.

See Also

get.data.from.response.TIRT for the reverse conversion.

get.response.from.data for the generic (non-TIRT) converter used by FCGGUM and FCMIRT.

Examples

# 2 persons, 2 RANK blocks.
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
items <- list(1:2, 3:5)
result <- get.response.from.data.TIRT(dat, items, fc.type = "RANK")
result$response
result$pairs.value[[1]]
get.data.from.response.TIRT(
  result$response, items, fc.type = "RANK",
  pairs.value = result$pairs.value
)

# Mixed partial-response blocks.
dat.partial <- data.frame(
  mole = c("1>3", "2>1"),
  pick = c("4", "5"),
  stringsAsFactors = FALSE
)
items.partial <- list(1:3, 4:6)
partial <- get.response.from.data.TIRT(
  dat.partial, items.partial, fc.type = c("MOLE", "PICK")
)
partial$response
get.data.from.response.TIRT(
  partial$response, items.partial, fc.type = c("MOLE", "PICK"),
  pairs.value = partial$pairs.value
)

Build the CDM design matrix for a set of attribute patterns

Description

Constructs the design matrix X used in the cognitive diagnostic model probability formulation p = X\delta. The structure depends on the model type:

DINA

Intercept + single mastery indicator (all attributes mastered).

DINO

Intercept + single "at-least-one" indicator.

ACDM

Intercept + main effects of each attribute.

GDINA

Full saturated interaction matrix (all 2^K columns).

Usage

get_design_matrix_cdm(patterns, model = "GDINA")

Arguments

Value

A numeric design matrix X with L rows. Column count depends on the model.

Find precedent (subset) patterns for monotonicity enforcement

Description

For each attribute mastery pattern, identifies which other patterns are proper subsets (i.e., mastering a subset of the attributes). Used to enforce the GDINA monotonicity constraint: mastering more attributes should never decrease the success probability.

Usage

get_precedent_patterns(patterns)

Arguments

Details

Equivalent to preloclist in the GDINA R package.

Value

A list of length L; the l-th element is an integer vector of row indices corresponding to patterns that are proper subsets of pattern l.

Goodness-of-Fit Indices for Latent Probability Models

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-R^2 measures, residual diagnostics, local-dependence statistics (Yen's Q3), and posterior classification diagnostics.

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

Value

An object of class "good.of.fit" (a list). Key components:

LogLik, deviance

Log-likelihood and deviance.

npar, N, nitems

Parameter count, sample size, number of items/indicators.

AIC, AICc, BIC, CAIC, SABIC, HQIC

Information criteria.

M2.value, df, p.value

M2 statistic, degrees of freedom, asymptotic p-value.

RMSEA2, RMSEA.lower, RMSEA.upper, RMSEA.CI.level, RMSEA.p.close

RMSEA estimate, confidence interval, interval level, close-fit test p-value.

SRMSR, RMSR

Standardized and raw root mean square residuals.

CFI, TLI, IFI

Incremental fit indices.

McFadden.R2, Nagelkerke.R2, CoxSnell.R2, AldrichNelson.R2, VeallZimmermann.R2

Pseudo-R^2 measures.

residuals, residuals.standardized, correlation.residuals

Residual vectors.

moments.observed, moments.predicted

First- and second-order marginal moments.

q3.mean, q3.abs.max, q3.adjusted.abs.max, q3.p95

Yen's Q3 local dependence statistics.

mean.max.posterior, median.max.posterior, min.max.posterior

Posterior classification diagnostics.

null.LogLik, null.M2.value, null.df

Null (independence) model diagnostics.

LRT, LRT.df, LRT.p

Likelihood ratio test against the null model.

Likelihood and Information Criteria

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

Deviance:

D = -2\ell

AIC (Akaike, 1974):

\text{AIC} = D + 2p

AICc (Hurvich & Tsai, 1989), small-sample correction:

\text{AICc} = \text{AIC} + \frac{2p(p+1)}{N - p - 1}, \quad N > p + 1

BIC (Schwarz, 1978):

\text{BIC} = D + p \log N

CAIC (Bozdogan, 1987), consistent AIC:

\text{CAIC} = D + p(\log N + 1)

SABIC (Sclove, 1987), sample-size adjusted BIC:

\text{SABIC} = D + p \log\bigl(\frac{N + 2}{24}\bigr)

HQIC (Hannan & Quinn, 1979):

\text{HQIC} = D + 2p \log(\log N), \quad N > e

Limited-Information M2 Family

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

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

M2 statistic:

M_2 = N\, \mathbf{e}'\hat{\mathbf{C}}_2\mathbf{e},

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

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

RMSEA (Root Mean Square Error of Approximation):

\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 \chi^2 inversion. The close-fit test evaluates H_0: \text{RMSEA} \le 0.05.

SRMSR (Standardized Root Mean Square Residual):

\text{SRMSR} = \sqrt{ \frac{1}{J} \sum_{i < j} (r_{ij}^{\text{obs}} - r_{ij}^{\text{model}})^2 },

where r_{ij} are the observed and model-implied correlation residuals, summed over J unique off-diagonal pairs.

McDonald's NCI (Non-Centrality Index):

\text{NCI} = \exp\!\left(-\frac{\max(M_2 - df, 0)}{2N}\right)

Incremental / Comparative Fit Indices

CFI (Comparative Fit Index):

\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 M_2^{\text{null}} with df^{\text{null}} degrees of freedom.

TLI (Tucker–Lewis Index, a.k.a. NNFI):

\text{TLI} = \frac{M_2^{\text{null}} / df^{\text{null}} - M_2 / df} {M_2^{\text{null}} / df^{\text{null}} - 1}

IFI (Incremental Fit Index, a.k.a. BFI):

\text{IFI} = \frac{M_2^{\text{null}} - M_2}{M_2^{\text{null}} - df}

Pseudo-R^2 Measures

McFadden's R^2:

R^2_{\text{McF}} = 1 - \frac{\ell}{\ell_0}

McFadden's adjusted R^2:

R^2_{\text{McF,adj}} = 1 - \frac{\ell - p}{\ell_0}

Cox–Snell R^2:

R^2_{\text{CS}} = 1 - \exp\!\left(\frac{2}{N}(\ell_0 - \ell)\right)

Nagelkerke R^2:

R^2_{\text{N}} = \frac{R^2_{\text{CS}}} {1 - \exp(2\ell_0 / N)}

Aldrich–Nelson R^2:

R^2_{\text{AN}} = \frac{G^2}{G^2 + N}, \quad G^2 = D_0 - D

Veall–Zimmermann R^2:

R^2_{\text{VZ}} = R^2_{\text{AN}} \times \frac{-2\ell_0 + N}{-2\ell_0}

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

Yen's Q3 Local Dependence

For each pair of items (i, k), the residual correlation is

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

Heuristic Guidelines

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

• RMSEA: \le 0.05 close fit; \le 0.08 reasonable; \le 0.10 mediocre (Browne & Cudeck, 1993)

• SRMSR: \le 0.08 acceptable (Hu & Bentler, 1999)

• CFI / TLI: \ge 0.95 good; \ge 0.90 acceptable

References

Akaike, H. (1974). A new look at the statistical model identification. 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. 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.), Testing structural equation models (pp. 136–162). Sage.

Christensen, K. B., Makransky, G., & Horton, M. C. (2017). Critical values for Yen's Q3. 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. 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. 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. 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. 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. 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. 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.), Frontiers in econometrics (pp. 105–142). Academic Press.

Schwarz, G. (1978). Estimating the dimension of a model. 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. 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. Applied Psychological Measurement, 8, 125–145. doi:10.1177/014662168400800201

See Also

get.fit.index for model-specific wrappers, summary.good.of.fit for formatted fit tables, print.good.of.fit for the print method.

Extract Log-Likelihood from Fitted Models

Description

Extracts the marginal log-likelihood from a fitted ForceChoice model object. For continuous-trait IRT models, the log-likelihood is computed by numerically integrating the joint likelihood of the observed responses over the latent trait distribution using Cartesian-product normal quadrature. For FCGDINA, the marginal likelihood is obtained by summing over the 2^D discrete attribute profiles.

For a sample of N independent persons with responses \mathbf{Y}_j, the marginal log-likelihood is:

\ell = \sum_{j=1}^{N} \log \int P(\mathbf{Y}_j \mid \boldsymbol{\theta})\, \phi_D(\boldsymbol{\theta}; \mathbf{0}, \boldsymbol{\Sigma})\, d\boldsymbol{\theta},

where \phi_D(\cdot) is the D-variate normal density with correlation matrix \boldsymbol{\Sigma}. The integral is approximated on a Cartesian-product quadrature grid over [-6, 6]^D.

The continuous-trait quadrature weights are normalized normal densities computed on the grid points, with the fitted correlation matrix used when available. FCGDINA instead uses the estimated class-proportion vector \boldsymbol{\pi} over attribute profiles.

S3 methods for extracting marginal log-likelihoods from fitted ForceChoice model objects.

Usage

## S3 method for class 'FCDCM'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'FCGDINA'
logLik(object, ...)

## S3 method for class 'FCGGUM'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'FCMIRT'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'MGGUM'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'MGPCM'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'MIRT'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

## S3 method for class 'TIRT'
logLik(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

Arguments

Details

For MIRT, MGPCM, MGGUM, FCMIRT, FCGGUM, TIRT, and FCDCM objects, the likelihood is evaluated by marginalizing over a normal quadrature grid (and, for FCDCM, over attribute profiles conditional on the higher-order trait). For FCGDINA objects, the likelihood is evaluated exactly over the 2^D latent attribute profiles.

Value

An object of class "logLik" with attributes:

• nobs: number of observations (N)

• df: number of free parameters

• theta.norm: continuous-trait quadrature grid points, when applicable

• prob: model-implied response probabilities at grid points, when applicable

• pi: quadrature weights or FCGDINA class probabilities

• L: quadrature grid size used, when applicable

• prob.class: FCGDINA class-conditional forced-choice probabilities, when applicable

An object of class "logLik": a length-one numeric vector containing the marginal log-likelihood, with at least attributes nobs (sample size) and df (number of free parameters). Continuous-trait methods also attach quadrature diagnostics such as theta.norm, prob, pi, and L; FCGDINA attaches latent-class probabilities and class-conditional response probabilities.

Functions

• logLik(FCDCM): FCDCM model: higher-order trait quadrature with exact marginalization over discrete attribute profiles.

• logLik(FCGDINA): FCGDINA model: marginal forced-choice probabilities over all 2^D attribute profiles.

• logLik(FCGGUM): FCGGUM model: forced-choice unfolding block probabilities with multivariate normal quadrature.

• logLik(FCMIRT): FCMIRT model: forced-choice block pattern probabilities with multivariate normal quadrature.

• logLik(MGGUM): MGGUM model: polytomous unfolding responses with per-item block-structured quadrature evaluation.

• logLik(MGPCM): MGPCM model: polytomous responses integrated over the fitted multivariate normal latent distribution.

• logLik(MIRT): MIRT model: multivariate normal quadrature over D-dimensional latent space with Gaussian correlation structure.

• logLik(TIRT): TIRT model: pairwise binary probit probabilities with multivariate normal quadrature over traits.

See Also

fit.MIRT, get.fit.index, good.of.fit

Examples

sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)
ll <- logLik(fit, L = 9)
as.numeric(ll)
attr(ll, "df")

Build CDM item response probabilities for attribute mastery patterns

Description

Computes the probability of endorsing an item for each attribute mastery pattern under the specified CDM condensation rule (DINA, DINO, ACDM, or GDINA). p0 is the lower-bound (guessing) probability and p1 is the upper-bound (1 - slipping) probability.

Usage

make_item_prob_cdm(patterns, model, p0, p1, mono.constraint = TRUE)

Arguments

Value

A named numeric vector of probabilities, one per pattern row.

Multivariate normal quadrature grid with Cholesky-stabilised weights

Description

Used by all continuous-trait logLik() methods.

Usage

make_quadrature_grid_mvn(
  Corr,
  theta.mu,
  D,
  L = NULL,
  theta.low = -6,
  theta.up = 6
)

Arguments

Value

A list with theta.norm (grid matrix) and pi (normalised prior-weight column vector).

Free-parameter mask for MGGUM models

Description

Free-parameter mask for MGGUM models

Usage

mggum_par_free_mask(Q.matrix, length.poly, max_poly = max(length.poly))

Arguments

Value

An I x (2D + max_poly) logical matrix.

Free-parameter mask for MGPCM models

Description

Free-parameter mask for MGPCM models

Usage

mgpcm_par_free_mask(Q.matrix, length.poly, max_poly = max(length.poly))

Arguments

Value

An I x (D + max_poly) logical matrix.

Free-parameter mask for MIRT models

Description

Free-parameter mask for MIRT models

Usage

mirt_par_free_mask(model_type, Q.matrix)

Arguments

Value

An I x (D+3) logical matrix.

Compute FCDCM Block Response Probabilities

Description

Compute FCDCM Block Response Probabilities

Usage

model.FCDCM(zeta, par, patterns)

Arguments

Value

Matrix of probabilities for choosing the first statement in each block: \eta_{0b} if \zeta_{A_b}<\zeta_{B_b}, 0.5 if equal, and 0.5+\eta_{ABb} if \zeta_{A_b}>\zeta_{B_b}.

Compute FCGDINA forced-choice pattern probabilities

Description

Computes block-level forced-choice response probabilities from known attribute profiles and item-level CDM delta parameters. This is the deterministic probability engine used by sim.data.FCGDINA for response generation and is useful for checking a fitted or simulated FCGDINA parameterization.

Usage

model.FCGDINA(
  alpha,
  delta.list,
  design.matrix.list,
  Q.matrix,
  patterns.total,
  patterns,
  prob.item = NULL
)

Arguments

Details

Item endorsement probabilities are first computed by compute_fcgdina_item_prob. For person n and statement i, the probability is

p_{ni} = \mathbf{x}_i(\boldsymbol{\alpha}_n)' \boldsymbol{\delta}_i,

where \mathbf{x}_i(\boldsymbol{\alpha}_n) is the relevant row of the item CDM design matrix. The item probabilities are then converted to block-level forced-choice pattern probabilities by forced_choice_from_agree.

Value

An N \times \sum_b P_b matrix of forced-choice response probabilities, where P_b is the number of observable patterns in block b.

See Also

sim.data.FCGDINA, compute_fcgdina_item_prob, forced_choice_from_agree

Examples

sim <- sim.data.FCGDINA(N.person = 10, N.block = 2, I.block = 2,
                        D = 2, model = "DINA")
prob <- model.FCGDINA(
  alpha = sim$alpha,
  delta.list = sim$delta.list,
  design.matrix.list = sim$design.matrix.list,
  Q.matrix = sim$Q.matrix,
  patterns.total = sim$patterns.total,
  patterns = sim$patterns
)
stopifnot(all(abs(rowSums(prob) - length(sim$block.items)) < 1e-8))

Compute FCGGUM Forced-Choice Pattern Probabilities

Description

Compute FCGGUM Forced-Choice Pattern Probabilities

Usage

model.FCGGUM(theta, par, patterns.total, patterns)

Arguments

Value

Block ranking probability matrix. The code first computes binary GGUM endorsement probabilities from the distance-based MGGUM formula, transforms them to logits, and then applies the sequential Luce/Plackett rule. MOLE and PICK probabilities are sums over compatible full rankings normalized over observed patterns.

Compute FCMIRT Forced-Choice Pattern Probabilities

Description

Compute FCMIRT Forced-Choice Pattern Probabilities

Usage

model.FCMIRT(theta, par, patterns.total, patterns)

Arguments

Value

N x sum(pattern counts) probability matrix. For each block, item endorsement probabilities are first computed by model.MIRT, transformed to logits, and then combined with a sequential Luce/Plackett rule. MOLE and PICK probabilities are obtained by summing compatible full-ranking probabilities and normalizing over the observed block patterns.

Compute MGGUM Category Response Probabilities

Description

Compute MGGUM Category Response Probabilities

Usage

model.MGGUM(theta, par)

Arguments

Value

An N \times \sum_i K_i matrix of stacked category probabilities. The implementation uses r_{ij} = [\sum_d a_{id}^2(\theta_{jd}-\delta_{id})^2]^{1/2} and P(Y_{ij}=k) \propto \exp\{k r_{ij}-\psi_{ik}\} + \exp\{(2K_i-1-k)r_{ij}-\psi_{ik}\}.

Compute MGPCM Category Response Probabilities

Description

Compute MGPCM Category Response Probabilities

Usage

model.MGPCM(theta, par)

Arguments

Value

An N \times \sum_i K_i matrix of category probabilities (stacked by item), where P(Y_{ij}=k) \propto \exp\{k\,\mathbf{a}_i' \boldsymbol{\theta}_j + d_{ik}\}.

Compute MIRT Item Response Probabilities

Description

Computes the probability of a correct response for each person–item combination under the multidimensional 1PL–4PL models. This is the core IRF (item response function) used throughout the package.

Usage

model.MIRT(theta, par)

Arguments

Value

An N \times I matrix of response probabilities P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j).

See Also

fit.MIRT for the full model specification.

Compute TIRT Pairwise Comparison Probabilities

Description

Compute TIRT Pairwise Comparison Probabilities

Usage

model.TIRT(theta, lambda, psi2, gamma.matrix, Q.matrix, pairs.matrix)

Arguments

Value

Matrix of pairwise choice probabilities: \Phi\{[-\gamma_{ik} + (|\lambda_i|q_i - |\lambda_k|q_k)'\theta_j] / \sqrt{\psi_i^2+\psi_k^2}\}.

Map resolved model name to integer code

Description

Converts the canonical model string returned by resolve_model_type() to the integer code expected by the Stan models (1 = 1PL, 2 = 2PL, 3 = 3PL, 4 = 4PL).

Usage

model_type_to_int(model)

Arguments

Value

Integer model type code.

S3 Methods: nobs

Description

Extracts the number of observations (persons) from a fitted ForceChoice model object. Returns the number of rows in the response matrix used for model fitting.

Usage

## S3 method for class 'MIRT'
nobs(object, ...)

## S3 method for class 'MGPCM'
nobs(object, ...)

## S3 method for class 'MGGUM'
nobs(object, ...)

## S3 method for class 'FCMIRT'
nobs(object, ...)

## S3 method for class 'FCDCM'
nobs(object, ...)

## S3 method for class 'FCGDINA'
nobs(object, ...)

## S3 method for class 'FCGGUM'
nobs(object, ...)

## S3 method for class 'TIRT'
nobs(object, ...)

Arguments

Value

An integer: the sample size N.

Methods (by class)

• nobs(MIRT): Number of observations (persons) for MIRT objects.

• nobs(MGPCM): Number of observations for MGPCM objects.

• nobs(MGGUM): Number of observations for MGGUM objects.

• nobs(FCMIRT): Number of observations for FCMIRT objects.

• nobs(FCDCM): Number of observations for FCDCM objects.

• nobs(FCGDINA): Number of observations for FCGDINA objects.

• nobs(FCGGUM): Number of observations for FCGGUM objects.

• nobs(TIRT): Number of observations for TIRT objects.

Normalise and recycle forced-choice type vector

Description

Normalise and recycle forced-choice type vector

Usage

normalize_fc_type(fc.type, N.block, default = "RANK")

Arguments

Value

A character vector of length N.block.

Convert binary matrix rows to string keys

Description

Collapses each row of a binary matrix to a single string by pasting the entries without separator (e.g. c(0,1,0) becomes "010").

Usage

pattern_key(x)

Arguments

Value

A character vector of length nrow(x).

S3 Methods: plot

Description

Draws log-likelihood trace plots for fitted ForceChoice model objects. Stan, iStEM, and EM fits are visualised through the same convergence target: the total log-likelihood recorded across iterations of the corresponding estimation algorithm.

Usage

## S3 method for class 'MIRT'
plot(x, y = NULL, ...)

## S3 method for class 'MGPCM'
plot(x, y = NULL, ...)

## S3 method for class 'MGGUM'
plot(x, y = NULL, ...)

## S3 method for class 'FCMIRT'
plot(x, y = NULL, ...)

## S3 method for class 'FCDCM'
plot(x, y = NULL, ...)

## S3 method for class 'FCGGUM'
plot(x, y = NULL, ...)

## S3 method for class 'FCGDINA'
plot(x, y = NULL, ...)

## S3 method for class 'TIRT'
plot(x, y = NULL, ...)

Arguments

Details

The horizontal axis is the saved Stan iteration, iStEM iteration, or EM iteration. The vertical axis is the summed log-likelihood. Stan plots use log_lik or log_lik_group from generated quantities and draw all chains in one panel. iStEM plots use the iteration-level iStEM$logLik.trace, and the stable chain is the final M * B iStEM iterations. EM plots use EM$logLik.trace. For Stan and iStEM fits, a vertical dashed line marks the stable-chain boundary. EM fits do not have a stable-chain boundary.

Value

Invisibly returns NULL. Plots are produced as a side effect on the current graphics device.

Methods (by class)

• plot(MIRT): Log-likelihood trace plot for MIRT objects.

• plot(MGPCM): Log-likelihood trace plot for MGPCM objects.

• plot(MGGUM): Log-likelihood trace plot for MGGUM objects.

• plot(FCMIRT): Log-likelihood trace plot for FCMIRT objects.

• plot(FCDCM): Log-likelihood trace plot for FCDCM objects.

• plot(FCGGUM): Log-likelihood trace plot for FCGGUM objects.

• plot(FCGDINA): Log-likelihood trace plot for FCGDINA objects.

• plot(TIRT): Log-likelihood trace plot for TIRT objects.

S3 Methods: predict

Description

Predict response probabilities from fitted ForceChoice model objects. Given a fitted model and optionally new person parameter (latent trait) values, returns the model-implied response probabilities. When newdata is not provided, predictions are made at the estimated latent trait values for each person.

Usage

## S3 method for class 'MIRT'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'MGPCM'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'MGGUM'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'FCMIRT'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'FCDCM'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'FCGDINA'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'FCGGUM'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

## S3 method for class 'TIRT'
predict(object, newdata = NULL, type = c("probability", "response"), ...)

Arguments

Value

type = "probability"

For binary models (MIRT, TIRT): an M \times I matrix of endorsement probabilities. For polytomous models (MGPCM, MGGUM): an M \times \sum K_i matrix of stacked category probabilities. For forced-choice models (FCMIRT, FCGGUM): an M \times \sum K_b matrix of block-pattern probabilities. For FCDCM: an M \times B matrix of marginal block-choice probabilities.

type = "response"

For binary models: an M \times I matrix of simulated 0/1 responses. For polytomous models: an M \times I matrix of category indices. For forced-choice models: an M \times B matrix of chosen pattern indices.

Methods (by class)

• predict(MIRT): Predict response probabilities or simulated responses from MIRT objects.

• predict(MGPCM): Predict response probabilities from MGPCM objects.

• predict(MGGUM): Predict response probabilities from MGGUM objects.

• predict(FCMIRT): Predict response probabilities from FCMIRT objects.

• predict(FCDCM): Predict response probabilities from FCDCM objects.

• predict(FCGDINA): Predict response probabilities from FCGDINA objects. For newdata, provide either binary alpha profiles or class probability rows.

• predict(FCGGUM): Predict response probabilities from FCGGUM objects.

• predict(TIRT): Predict response probabilities from TIRT objects.

S3 Methods: print

Description

Provides user-friendly, formatted console output for objects generated by the ForceChoice package. This generic function dispatches to class-specific methods that display concise summaries of fitted models, simulation datasets, goodness-of-fit indices, and rotated solutions. Designed for interactive use and quick diagnostic inspection.

Usage

## S3 method for class 'good.of.fit'
print(x, digits = 4, ...)

## S3 method for class 'summary.good.of.fit'
print(x, ...)

## S3 method for class 'MIRT'
print(x, ...)

## S3 method for class 'summary.MIRT'
print(x, ...)

## S3 method for class 'MGPCM'
print(x, ...)

## S3 method for class 'summary.MGPCM'
print(x, ...)

## S3 method for class 'MGGUM'
print(x, ...)

## S3 method for class 'summary.MGGUM'
print(x, ...)

## S3 method for class 'FCMIRT'
print(x, ...)

## S3 method for class 'summary.FCMIRT'
print(x, ...)

## S3 method for class 'FCDCM'
print(x, ...)

## S3 method for class 'summary.FCDCM'
print(x, ...)

## S3 method for class 'FCGDINA'
print(x, ...)

## S3 method for class 'summary.FCGDINA'
print(x, ...)

## S3 method for class 'FCGGUM'
print(x, ...)

## S3 method for class 'summary.FCGGUM'
print(x, ...)

## S3 method for class 'TIRT'
print(x, ...)

## S3 method for class 'summary.TIRT'
print(x, ...)

## S3 method for class 'data.MIRT'
print(x, ...)

## S3 method for class 'data.MGPCM'
print(x, ...)

## S3 method for class 'data.MGGUM'
print(x, ...)

## S3 method for class 'data.FCMIRT'
print(x, ...)

## S3 method for class 'data.FCDCM'
print(x, ...)

## S3 method for class 'data.FCGDINA'
print(x, ...)

## S3 method for class 'data.FCGGUM'
print(x, ...)

## S3 method for class 'data.TIRT'
print(x, ...)

Arguments

Details

Each method produces a structured, human-readable summary optimized for its object type:

Fitted Model Objects

Invokes summary() internally and prints comprehensive output including:

• Model call and configuration (family, method, dimensions)

• Data characteristics (N, I or B, response type)

• Fit statistics (LogLik, npar, AIC, BIC)

• Factor correlation matrix

• Person parameter summary (N x D)

• Item / statement / block parameter summary

• For FCDCM: higher-order delta parameters and classification diagnostics

• For TIRT: loading (lambda) parameter summary

• Convergence diagnostics (algorithm, batches, latent grid length L)

Goodness-of-Fit Objects (good.of.fit)

Delegates to summary.good.of.fit and prints:

• Overview table (sample size, items, parameters, moments)

• Limited-information absolute fit (M2, RMSEA, SRMSR)

• Incremental / comparative fit (CFI, TLI, IFI)

• Likelihood and information criteria (AIC, BIC, SABIC, CAIC)

• Pseudo-R^2 measures

Value

Invisibly returns the input object x. No data is modified.

Methods (by class)

• print(good.of.fit): Print method for good.of.fit objects. Delegates to summary.good.of.fit and prints formatted tables.

• print(summary.good.of.fit): Print method for summary.good.of.fit objects. Displays overview, absolute-fit, comparative-fit, likelihood/IC, and pseudo-R^2 tables.

• print(MIRT): Print method for MIRT objects. Multidimensional IRT (1PL–4PL) model summary.

• print(summary.MIRT): Print method for summary.MIRT objects. Shows model config, data info, fit stats, factor correlations, person/item parameter summaries, and convergence.

• print(MGPCM): Print method for MGPCM objects. Multidimensional Generalized Partial Credit Model summary.

• print(summary.MGPCM): Print method for summary.MGPCM objects. Shows polytomous model config, fit stats, factor correlations, person/item parameter summaries, and convergence.

• print(MGGUM): Print method for MGGUM objects. Multidimensional Generalized Graded Unfolding Model summary.

• print(summary.MGGUM): Print method for summary.MGGUM objects. Shows unfolding model config, fit stats, factor correlations, person/item parameter summaries, and convergence.

• print(FCMIRT): Print method for FCMIRT objects. Forced-Choice Multidimensional IRT model summary.

• print(summary.FCMIRT): Print method for summary.FCMIRT objects. Shows forced-choice model config with block info, fit stats, factor correlations, person/statement parameter summaries.

• print(FCDCM): Print method for FCDCM objects. Forced-Choice Diagnostic Classification Model summary with higher-order trait, attribute profiles, and classification diagnostics.

• print(summary.FCDCM): Print method for summary.FCDCM objects. Shows higher-order delta parameters, block eta parameters, attribute classification summary, and convergence.

• print(FCGDINA): Print method for FCGDINA objects. Forced-Choice GDINA model summary.

• print(summary.FCGDINA): Print method for summary.FCGDINA objects. Shows CDM type, forced-choice block info, fit stats, delta summaries, posterior attribute probabilities, and convergence.

• print(FCGGUM): Print method for FCGGUM objects. Forced-Choice Generalized Graded Unfolding Model summary.

• print(summary.FCGGUM): Print method for summary.FCGGUM objects. Shows forced-choice unfolding model config, fit stats, factor correlations, person/statement parameter summaries.

• print(TIRT): Print method for TIRT objects. Thurstonian IRT for Forced-Choice model summary.

• print(summary.TIRT): Print method for summary.TIRT objects. Shows pairwise-comparison model config, fit stats, factor correlations, loading/person parameter summaries.

• print(data.MIRT): Print method for data.MIRT objects.

• print(data.MGPCM): Print method for data.MGPCM objects.

• print(data.MGGUM): Print method for data.MGGUM objects.

• print(data.FCMIRT): Print method for data.FCMIRT objects.

• print(data.FCDCM): Print method for data.FCDCM objects.

• print(data.FCGDINA): Print method for data.FCGDINA objects.

• print(data.FCGGUM): Print method for data.FCGGUM objects.

• print(data.TIRT): Print method for data.TIRT objects.

Output Conventions

• Numeric values are rounded to the precision specified by digits (default 4).

• Parameter summary tables show Min, Q1, Median, Mean, Q3, Max across items/statements for each parameter type.

• Convergence diagnostics adapt to the estimation backend (iStEM batch diagnostics vs. Stan HMC notes).

S3 Methods: residuals

Description

Compute residuals from fitted ForceChoice model objects. Supported types are raw (response), Pearson, and deviance residuals.

Usage

## S3 method for class 'MIRT'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'MGPCM'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'MGGUM'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'FCMIRT'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'FCDCM'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'FCGDINA'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'FCGGUM'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

## S3 method for class 'TIRT'
residuals(object, type = c("raw", "pearson", "deviance"), ...)

Arguments

Details

Residual types follow standard GLM conventions for binary responses:

• raw: e_{ij} = y_{ij} - \hat{p}_{ij}

• Pearson: r_{ij} = e_{ij} / \sqrt{\hat{p}_{ij}(1-\hat{p}_{ij})}

• deviance: d_{ij} = \mathrm{sign}(e_{ij}) \sqrt{2\left[y_{ij}\log\frac{y_{ij}}{\hat{p}_{ij}} + (1-y_{ij})\log\frac{1-y_{ij}}{1-\hat{p}_{ij}}\right]}

For polytomous and forced-choice models, residuals are computed on a category-indicator matrix. This treats ordered categories and nominal forced-choice response patterns as multinomial outcomes rather than as numeric scores.

Value

A numeric matrix with the same dimensions as the corresponding fitted output.

Methods (by class)

• residuals(MIRT): Residuals for MIRT objects.

• residuals(MGPCM): Residuals for MGPCM objects.

• residuals(MGGUM): Residuals for MGGUM objects.

• residuals(FCMIRT): Residuals for FCMIRT objects.

• residuals(FCDCM): Residuals for FCDCM objects.

• residuals(FCGDINA): Residuals for FCGDINA objects.

• residuals(FCGGUM): Residuals for FCGGUM objects.

• residuals(TIRT): Residuals for TIRT objects.

Resolve the number of latent dimensions

Description

Uses an explicit D, or infers it from the number of columns in a supplied Q-matrix. Latent dimensionality is never guessed from the number of items or blocks.

Usage

resolve_D(D, Q.matrix = NULL, block.items = NULL, I = NULL)

Arguments

Value

Integer D.

Auto-detect block.items from forced-choice ranking data

Description

Parses ranking strings like "2>1>3" to extract the set of item indices in each block. Only works when data columns contain character ranking strings.

Usage

resolve_block_items(block.items, data)

Arguments

Value

A list of integer vectors (one per block), or NULL if auto-detection is not possible.

Resolve forced-choice block and Q-matrix configuration

Description

Shared validation and auto-generation logic used by sim.data.FCMIRT, sim.data.FCGGUM, sim.data.FCGDINA, and sim.data.TIRT.

Usage

resolve_fc_blocks(
  Q.matrix,
  block.items,
  I.block,
  N.block,
  D,
  q.valid.values,
  q.row.check
)

Arguments

Value

A named list with components I.states, N.block, I.block, block.items, Q.matrix, D. Q.matrix is NULL if it was not supplied and should be generated later (e.g. by sim.Q.matrix.FC or sim.data.Q.CDM).

Auto-detect forced-choice response type from data

Description

When fc.type is NULL, inspects the ranking strings in the data columns to infer whether they represent RANK, MOLE, or PICK.

Usage

resolve_fc_type(fc.type, data, block.items = NULL)

Arguments

Value

Character vector of fc.type values (one per block).

Resolve IRT model type with alias support

Description

Accepts both internal codes ("m1pl", "m2pl", "m3pl", "m4pl") and user-friendly aliases ("Rasch", "1PL", "2PL", "3PL", "4PL").

Usage

resolve_model_type(model)

Arguments

Value

Lower-case internal model code.

Restore MCMC threading environment to its previous state

Description

Restore MCMC threading environment to its previous state

Usage

restore_mcmc_env(old)

Arguments

Value

Invisibly NULL.

S3 Methods: rotate

Description

Applies factor rotation to the posterior mean parameter estimates of fitted exploratory multidimensional models from the ForceChoice package. Rotation reparameterises the latent space to improve interpretability of factor loadings while preserving the model-implied covariance structure. Standard errors and other posterior uncertainty summaries are carried over from the original fit object without recomputation. No per-iteration rotation or cross-iteration alignment is performed.

For GPArotation methods, theta is re-standardized to a standard normal scale after rotation. For Promax rotation, no post-rotation standardization is applied. Loadings and the factor correlation matrix are updated accordingly to preserve model-implied covariances.

Rotation is not permitted when the fitted Q.matrix contains zeros because that confirmatory structure would not generally be preserved under rotation.

Usage

## S3 method for class 'MGPCM'
rotate(
  object,
  method,
  vis = TRUE,
  target.a = NULL,
  target.theta = NULL,
  pst.W = NULL,
  lp.p = 1,
  lp.gpaiter = 5,
  promax_m = 4,
  ...
)

## S3 method for class 'MIRT'
rotate(
  object,
  method,
  vis = TRUE,
  target.a = NULL,
  target.theta = NULL,
  pst.W = NULL,
  lp.p = 1,
  lp.gpaiter = 5,
  promax_m = 4,
  ...
)

Arguments

Details

Only posterior means are rotated. For MGPCM objects, the first D columns of object$par$est are treated as discrimination parameters; all category intercepts are unchanged.

Value

rotate.MIRT

An object of class "RotateMIRT" containing the rotated "MIRT" fit object (object), the matched call (call), and the rotation arguments (arguments). Standard errors in the fitted object are preserved without recomputation.

rotate.MGPCM

An object of class "RotateMGPCM" containing the rotated "MGPCM" fit object (object), the matched call (call), and the rotation arguments (arguments). Category intercepts are retained from the original fit.

Methods (by class)

• rotate(MGPCM): Applies a factor rotation to the posterior mean discrimination parameters of MGPCM objects. The latent trait estimates and factor correlation matrix are transformed consistently. Category intercepts and posterior uncertainty summaries are retained from the original fit without recomputation.

• rotate(MIRT): Applies rotation to the posterior mean of loadings only from MIRT objects. Loadings (a) and factor correlation matrix (Corr) are updated to preserve model-implied covariances. For GPArotation methods, theta is re-standardized to a standard normal scale after rotation; for Promax, no post-rotation standardization is applied.

See Also

fit.MIRT, fit.MGPCM

Sample forced-choice responses from block-level pattern probabilities

Description

Uses inverse-CDF multinomial sampling (identical to the C++ implementation in forced_choice_from_agree) to draw a discrete pattern index for each person-block combination.

Usage

sample_fc_responses(prob, patterns, N.person, N.block)

Arguments

Value

A named list with response (N \times B integer matrix of pattern indices) and data (N \times B character matrix of ranking strings like "1>3>2").

Setup single-threaded MCMC environment

Description

Ensures each MCMC chain runs strictly on a single OS thread by setting environment variables that control Stan-internal threading and BLAS-level parallelism. The validated core count is returned inside the result list.

Usage

setup_mcmc_env(cores)

Arguments

Value

A named list with old environment values and the validated cores value. Pass this to restore_mcmc_env() to restore the previous thread-control state.

Simulate Data from the Forced-Choice DCM Model

Description

Generates forced-choice paired-comparison data from a higher-order cognitive diagnostic model (DINA/DINO). The continuous higher-order trait governs attribute mastery probabilities via a logistic link; two-statement blocks produce binary choices based on attribute mastery patterns. In each block, selecting the first statement has probability \eta_0 when its condensed mastery is lower than the second statement's, 0.5 when they are equal, and 0.5+\eta_{AB} when it is higher.

Usage

sim.data.FCDCM(
  N.person = 1000,
  N.block = 10,
  D = 3,
  dcm.type = "DINA",
  control = NULL
)

Arguments

Value

An object of class "data.FCDCM" containing data, response, theta, alpha, zeta, par, Q.matrix, block.items, prob, and data-generating arguments.

See Also

fit.FCDCM, model.FCDCM