fit.FCGGUM: Fit the Forced-Choice Generalized Graded Unfolding Model...

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

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

data	An N \times B forced-choice data matrix with ranking strings or 1-based pattern indices.
Q.matrix	An optional I \times D matrix with entries -1, 0, 1. See fit.MGGUM for the sign convention.
block.items	A list of length B giving global item indices in each block. Parsed from data if NULL and data contains ranking strings.
D	Integer; number of latent dimensions. If NULL, inferred from Q.matrix when available, otherwise from the block structure.
fc.type	Forced-choice response type: "RANK" (default), "MOLE", or "PICK".
method	Estimation method: "iStEM" (default) or "stan".
control.model	A named list of model-level hyperparameters for the GGUM unfolding model in a forced-choice framework. Supported entries: a.mu, a.sigma Prior location and scale for \log a_{id} (log-normal). Defaults: 0, 0.5. The log-normal prior ensures positivity of discrimination parameters in the unfolding model. The zero mean-log encourages slopes near 1 unless the data strongly indicate otherwise. delta.pos.mu, delta.pos.sigma Prior mean and SD for \delta_{id} when q_{id} = 1 (positive-side item locations; normal). Defaults: 1, 0.5. In the FC context, these priors regularize the location of statements on the positive side of each latent dimension. delta.neg.mu, delta.neg.sigma Prior mean and SD for \delta_{id} when q_{id} = -1 (negative-side item locations; normal). Defaults: -1, 0.5. These priors regularize statement locations on the negative side of each dimension. tau.mu, tau.sigma Location and scale for the log-normal prior on the positive threshold magnitude -\tau_{i1}. Defaults: 0, 0.5. In the binary FCGGUM, each statement has a single free threshold \tau_{i1}<0. theta.mu Prior mean vector for \boldsymbol{\theta}_j. Default: rep(0, D). L Theta grid size per dimension for marginal log-likelihood computation and iStEM block Gibbs sampling. Default adapts to D. theta.lower, theta.upper Bounds for the theta grid used by marginal log-likelihood computation and iStEM block Gibbs sampling. Defaults: -6, 6.
control.method	A named list of method-specific tuning parameters. Common entries (used by both Stan and iStEM): cores Number of CPU cores for parallel chains (Stan) or ignored (iStEM). Default: the number of chains. vis Logical; if TRUE (default), prints progress information to the console. seed Random seed for reproducibility. Default: a random integer. Stan-specific entries: chains Number of MCMC chains (default: 2). iter Total iterations per chain (default: 5000). warmup Warmup/burn-in iterations per chain (default: iter / 2). thin Thinning interval (default: 1). init Initial values: "random" (default) for uniform(-2, 2) initialization, or a list of initial values per chain. algorithm MCMC algorithm: "HMC" (default), "HMC", or "Fixed_param". adapt_delta Target average acceptance probability (NUTS; default: 0.95). The GGUM likelihood involves summation terms that can create challenging posterior geometries; consider increasing to 0.9–0.95 if divergences occur. max_treedepth Maximum tree depth (NUTS; default: 10). Increase if "max treedepth exceeded" warnings appear. stepsize Initial step size for the leapfrog integrator (auto-tuned by Stan if not set). int_time Total integration time for HMC trajectories (only when algorithm = "HMC"). metric Mass matrix type: "unit_e", "diag_e" (default), or "dense_e". adapt_engaged Logical; if TRUE (default), warmup adaptation is enabled. adapt_init_buffer, adapt_term_buffer, adapt_window Warmup adaptation scheduling parameters (defaults: 25, 50, 25). iStEM-specific entries: M Number of burn-in batches retained for Geweke convergence diagnosis (default: 10; must be \ge 2). B Batch size: MCMC iterations per batch (default: 20). burnin.maxitr Maximum burn-in batches (default: 100). maxitr Maximum total batches (default: 2000). eps1 Geweke z-score convergence threshold for burn-in (default: 1.5). eps2 Monte Carlo error tolerance for the final chain (default: 0.4). frac1, frac2 Fractions for the Geweke diagnostic (defaults: 0.1, 0.5). corr.optim.maxit Maximum L-BFGS-B iterations for the constrained unit-diagonal correlation update (default: 50). optim.maxit Maximum L-BFGS-B iterations per item (default: 50). GGUM item parameters (a, \delta, \tau) are optimized jointly under monotonicity and sign constraints. Increase if optimization warnings appear. fix.corr Logical; if TRUE, the inter-trait correlation matrix is fixed to the identity (default: FALSE). estimate.se Logical; if TRUE (default), standard errors are computed from the final Monte Carlo chain. delta.lower Lower bound on |\delta_{id}| (default: 1e-4). Ensures item locations are bounded away from zero for active dimensions. tau.gap.lower, tau.gap.upper Lower and upper bounds on the positive gap used to construct \tau_{i1}<0. Defaults are 1e-4 and 6.

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)

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