gpcmodel: Generalized Partial Credit Model Fitting Function

In psychotools: Psychometric Modeling Infrastructure

Generalized Partial Credit Model Fitting Function

Description

gpcmodel is a basic fitting function for generalized partial credit models providing a wrapper around mirt and multipleGroup relying on marginal maximum likelihood (MML) estimation via the standard EM algorithm.

Usage

gpcmodel(y, weights = NULL, impact = NULL, type = c("GPCM", "PCM"),
  grouppars = FALSE, vcov = TRUE, nullcats = "downcode", 
  start = NULL, method = "BFGS", maxit = 500, reltol = 1e-5, ...)

Arguments

y	item response object that can be coerced (via as.matrix) to a numeric matrix with scores 0, 1, ... Typically, either already a matrix, data frame, or dedicated object of class itemresp.
weights	an optional vector of weights (interpreted as case weights)

.

impact	an optional factor allowing for grouping the subjects (rows). If specified, a multiple-group model is fitted to account for impact (see details below). By default, no impact is modelled, i.e., a single-group model is used.
type	character string, specifying the type of model to be estimated. In addition to the default GPCM (generalized partial credit model) it is also possible to estimate a standard PCM (partial credit model) by marginal maximum likelihood (MML).
grouppars	logical. Should the estimated distributional group parameters of a multiple group model be included in the model parameters?
vcov	logical or character specifying the type of variance-covariance matrix (if any) computed for the final model. The default vcov = TRUE corresponds to vcov = "Oakes", see mirt for further options. If set to vcov = FALSE (or vcov = "none"), vcov() will return a matrix of NAs only.
nullcats	character string, specifying how items with null categories (i.e., categories not observed) should be treated. Currently only "downcode" is available, i.e., all categories above a null category are shifted down to close the observed gap(s).
start	an optional vector or list of starting values (see examples below).
method, maxit, reltol	control parameters for the optimizer employed by mirt for the EM algorithm.
...	further arguments passed to mirt or multipleGroup, respectively.

Details

gpcmodel provides a basic fitting function for generalized partial credit models (GPCMs) providing a wrapper around mirt (and multipleGroup, respectively) relying on MML estimation via the standard EM algorithm (Bock & Aitkin, 1981). Models are estimated under the slope/intercept parametrization, see e.g. Chalmers (2012). The probability of person i falling into category x_{ij} of item j out of all categories p_{j} is modelled as:

P(X_{ij} = x_{ij}|\theta_{i},a_{j},\boldsymbol{d_{j}}) = \frac{\exp{(x_{ij}a_{j}\theta_{i} + d_{jx_{ij}})}}{\displaystyle\sum_{k = 0} ^ {p_{j}}\exp{(ka_{j}\theta_{i} + d_{jk})}}

Note that all d_{j0} are fixed at 0. A reparametrization of the intercepts to the classical IRT parametrization, see e.g. Muraki (1992), is provided via threshpar.

If an optional impact variable is supplied, a multiple-group model of the following form is being fitted: Item parameters are fixed to be equal across the whole sample. For the first group of the impact variable the person parameters are fixed to follow the standard normal distribution. In the remaining impact groups, the distributional parameters (mean and variance of a normal distribution) of the person parameters are estimated freely. See e.g. Baker & Kim (2004, Chapter 11), Debelak & Strobl (2019), or Schneider et al. (2022) for further details. To improve convergence of the model fitting algorithm, the first level of the impact variable should always correspond to the largest group. If this is not the case, levels are re-ordered internally.

If grouppars is set to TRUE the freely estimated distributional group parameters (if any) are returned as part of the model parameters.

Instead of the default GPCM, a standard partial credit model (PCM) can also be estimated via MML by setting type = "PCM". In this case all slopes are restricted to be equal across all items.

gpcmodel returns an object of class "gpcmodel" for which several basic methods are available, including print, plot, summary, coef, vcov, logLik, estfun, discrpar, itempar, threshpar, and personpar.

Value

gpcmodel returns an S3 object of class "gpcmodel", i.e., a list of the following components:

coefficients	estimated model parameters in slope/intercept parametrization,
vcov	covariance matrix of the model parameters,
data	modified data, used for model-fitting, i.e., centralized so that the first category is zero for all items, treated null categories as specified via argument "nullcats" and without observations with zero weight,
items	logical vector of length ncol(y), indicating which items were used during estimation,
categories	list of length ncol(y), containing integer vectors starting from one to the number of categories minus one per item,
n	number of observations (with non-zero weights),
n_org	original number of observations in y,
weights	the weights used (if any),
na	logical indicating whether the data contain NAs,
nullcats	currently always NULL as eventual items with null categories are handled via "downcode",
impact	either NULL or the supplied impact variable with the levels reordered in decreasing order (if this has not been the case prior to fitting the model),
loglik	log-likelihood of the fitted model,
df	number of estimated (more precisely, returned) model parameters,
code	convergence code from mirt,
iterations	number of iterations used by mirt,
reltol	convergence threshold passed to mirt,
grouppars	the logical grouppars value,
type	the type of model restriction specified,
mirt	the mirt object fitted internally,
call	original function call.

References

Baker FB, Kim SH (2004). Item Response Theory: Parameter Estimation Techniques. Chapman & Hall/CRC, Boca Raton.

Bock RD, Aitkin M (1981). Marginal Maximum Likelihood Estimation of Item Parameters: Application of an EM Algorithm. Psychometrika, 46(4), 443–459.

Chalmers RP (2012). mirt: A Multidimensional Item Response Theory Package for the R Environment. Journal of Statistical Software, 48(6), 1–29. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v048.i06")}

Debelak R, Strobl C (2019). Investigating Measurement Invariance by Means of Parameter Instability Tests for 2PL and 3PL Models. Educational and Psychological Measurement, 79(2), 385–398. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/0013164418777784")}

Muraki E (1992). A Generalized Partial Credit Model: Application of an EM Algorithm. Applied Psychological Measurement, 16(2), 159–176.

Schneider L, Strobl C, Zeileis A, Debelak R (2022). An R Toolbox for Score-Based Measurement Invariance Tests in IRT Models. Behavior Research Methods, forthcoming. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3758/s13428-021-01689-0")}

See Also

pcmodel, rsmodel, nplmodel, raschmodel, btmodel

Examples

if(requireNamespace("mirt")) {

o <- options(digits = 4)

## mathematics 101 exam results
data("MathExam14W", package = "psychotools")

## generalized partial credit model
gpcm <- gpcmodel(y = MathExam14W$credit)
summary(gpcm)

## how to specify starting values as a vector of model parameters
st <- coef(gpcm)
gpcm <- gpcmodel(y = MathExam14W$credit, start = st)
## or a list containing a vector of slopes and a list of intercept vectors
## itemwise
set.seed(0)
st <- list(a = rlnorm(13, 0, 0.0625), d = replicate(13, rnorm(2, 0, 1), FALSE))
gpcm <- gpcmodel(y = MathExam14W$credit, start = st)

## visualizations
plot(gpcm, type = "profile")
plot(gpcm, type = "regions")
plot(gpcm, type = "piplot")
plot(gpcm, type = "curves", xlim = c(-6, 6))
plot(gpcm, type = "information", xlim = c(-6, 6))
## visualizing the IRT parametrization
plot(gpcm, type = "curves", xlim = c(-6, 6), items = 1)
abline(v = threshpar(gpcm)[[1]])
abline(v = itempar(gpcm)[1], lty = 2)

options(digits = o$digits)
}

psychotools documentation built on May 29, 2024, 8:12 a.m.