fit.MGGUM: Fit the Multidimensional Generalized Graded Unfolding Model...

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

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

data	An N \times I matrix of integer responses coded 0, 1, \dots, K_i-1.
D	Integer; number of latent dimensions (D \ge 1). Default is 2.
Q.matrix	An optional I \times D matrix with entries -1, 0, 1. See section Q-matrix sign convention. Default generates a random signed matrix.
length.poly	Integer vector (length I) or scalar giving the number of categories per item. If NULL, inferred from the observed response maxima.
method	Estimation method: "iStEM" (default) or "stan".
control.model	A named list of model-level hyperparameters for the GGUM unfolding model. 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. 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. These priors regularize item locations on the positive side of each 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 item locations on the negative side of each dimension. tau.mu, tau.sigma Location and scale for the log-normal prior on positive threshold magnitudes -\tau_{ik} for k \ge 1. Defaults: 0, 0.5. The thresholds satisfy \tau_{i1} < \tau_{i2} < \dots < \tau_{i,K_i-1} < 0 with \tau_{i0} = 0 fixed for identification. 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). Values closer to 1 reduce step size and improve sampling for difficult posteriors. 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 (default: 1.5). The burn-in phase ends when \sum z^2 / K < \epsilon_1 or the MC error criterion is satisfied. eps2 Monte Carlo error tolerance (default: 0.4). The algorithm continues until max(d_k \cdot N) < \epsilon_2. 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 during the item-parameter update (default: 50). Increase if item optimization does not converge within this limit. 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 gaps used to construct ordered thresholds. Defaults are 1e-4 and 6.

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. \Sexpr[results=rd]{tools:::Rd_expr_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)

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