irtc.mml.2pl: Marginal Maximum Likelihood Estimation of Slope...

In IRTC: Marginal Maximum Likelihood Estimation for Item Response Models

Marginal Maximum Likelihood Estimation of Slope (Discrimination) Item Response Models

Description

Estimates unidimensional and multidimensional item response models with estimated item slopes (discriminations) by marginal maximum likelihood (MML). Supported models are the two-parameter logistic model ("2PL"), the generalized partial credit model ("GPCM"), their design-matrix and slope-group variants ("GPCM.design", "2PL.groups", "GPCM.groups").

Usage

irtc.mml.2pl(resp, Y = NULL, group = NULL, irtmodel = "2PL",
   formulaY = NULL, dataY = NULL, ndim = 1, pid = NULL,
   xsi.fixed = NULL, xsi.inits = NULL, beta.fixed = NULL, beta.inits = NULL,
   variance.fixed = NULL, variance.inits = NULL, est.variance = FALSE,
   A = NULL, B = NULL, B.fixed = NULL, Q = NULL, est.slopegroups = NULL,
   E = NULL, gamma.init = NULL, pweights = NULL, userfct.variance = NULL,
   variance.Npars = NULL, item.elim = TRUE, verbose = TRUE,
   method = c("auto", "grid", "streaming"), control = list())

Arguments

resp	A data frame or matrix of item responses (NA = missing).
Y	Optional covariate matrix for the latent regression.
group	Optional integer vector of group identifiers for multiple groups.
irtmodel	The estimated model: one of "2PL", "GPCM", "GPCM.design", "2PL.groups", "GPCM.groups".
formulaY	Optional formula for the latent regression (with dataY).
dataY	Optional covariate data frame used with formulaY.
ndim	Number of latent dimensions (when no Q/B is given).
pid	Optional vector of person identifiers.
xsi.fixed	Optional matrix (index, value) fixing item intercept parameters.
xsi.inits	Optional matrix of initial item parameters.
beta.fixed	Optional matrix fixing regression coefficients, or FALSE.
beta.inits	Optional matrix of initial regression coefficients.
variance.fixed	Optional matrix fixing covariance entries.
variance.inits	Optional initial covariance matrix.
est.variance	Logical: estimate the covariance matrix? (default FALSE).
A	Optional design array for item intercepts.
B	Optional design array for item slopes.
B.fixed	Optional matrix fixing entries of the slope array B.
Q	Optional loading (Q-) matrix mapping items to dimensions.
est.slopegroups	Optional vector grouping items that share a common estimated slope.
E	Optional design array used with est.slopegroups / GPCM.design.
gamma.init	Optional initial values for the estimated slope parameters.
pweights	Optional vector of person (case) weights.
userfct.variance	Optional user function constraining the covariance matrix.
variance.Npars	Number of estimated parameters in a user-constrained covariance.
item.elim	Logical: eliminate items with empty response categories?
verbose	Logical: print estimation progress?
method	Estimation engine. "grid" is the standard full-quadrature path. "streaming" routes to a dimension-factorized streaming engine for large between-item (simple-structure) multidimensional 2PL/GPCM models; it supports latent regression (Y), multiple groups (group, with per-group covariances), and case weights (pweights), but not the advanced item-design arguments (A, B, xsi.fixed, etc.), which force "grid". "auto" (default) predicts which engine is faster from (N, items, dims, nodes, unique covariate patterns) and routes accordingly (falling back to "grid" for unidimensional/small/unsupported models); the chosen engine and reasoning are returned in the routing component of the result. With case weights the result also reports the Kish effective sample size in n_eff.
control	List of control arguments (e.g. maxiter, conv, nodes, Msteps). Performance-related elements: n_threads (threads for the parallel E-step and slope M-step; default and maximum = 2), fast (logical, default FALSE; approximate mode pruning negligible-weight quadrature nodes), fast_threshold (pruning cutoff, default 1e-6), and acceleration ("none" default, or "squarem"/"Ramsay"/"Yu" to accelerate the grid EM). The streaming engine additionally accepts reg for opt-in statistical regularization (slope_penalty, slope_max, sigma_shrink, and sigma_shrink_pooled for shrinking per-group covariances toward the pooled estimate; default off), and group_structure ("full" = independent per-group covariances, default; "mean" = shared covariance with free group means). When fast=TRUE the streaming engine prunes quadrature nodes by a calibrated mass_budget (default 1e-3): after a few full-grid burn-in iterations it drops the lowest-importance nodes holding at most that fraction of the combined prior-and-posterior mass, retained per (covariate, group) pattern and unioned so extreme responders and small groups are protected. mass_budget is a pruning budget, not a guaranteed error. The real accuracy is measured: with verify="stratified" (default) a stratified subsample (groups, high weights, extreme responders, high-missingness; verify_n, verify_seed) is run through both the full and pruned grids at the final parameters, and the per-metric error quantiles (deviance / EAP / posterior moments / one-M-step parameter change, against tol_deviance/tol_eap/tol_moment/tol_par) are returned in accuracy_report with a met verdict. refine=TRUE refits with a tighter budget until the tolerances are met.

Value

An object of class irtc (see irtc.mml) with, in addition, the estimated slope array B and the slope parameter vector. Streaming-engine fits also carry a routing component (chosen engine and reasoning) and, when fast=TRUE with verification on, an accuracy_report: a measured, stratified approximation check (per-metric error quantiles plus a met verdict), not a strict mathematical error bound.

See Also

irtc.mml for fixed-slope (Rasch / PCM / RSM) models.

Examples

data(data.sim.rasch)
mod1 <- irtc.mml.2pl(resp = data.sim.rasch, irtmodel = "2PL")
summary(mod1)

data(data.gpcm)
mod2 <- irtc.mml.2pl(resp = data.gpcm, irtmodel = "GPCM")
summary(mod2)

IRTC documentation built on July 24, 2026, 5:07 p.m.