pcmodel: Partial Credit Model Fitting Function

In psychotools: Psychometric Modeling Infrastructure

Partial Credit Model Fitting Function

Description

pcmodel is a basic fitting function for partial credit models.

Usage

pcmodel(y, weights = NULL, nullcats = c("keep", "downcode", "ignore"),
  start = NULL, reltol = 1e-10, deriv = c("sum", "diff"),
  hessian = TRUE, maxit = 100L, full = TRUE, ...)

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).
deriv	character. If "sum" (the default), the first derivatives of the elementary symmetric functions are calculated with the sum algorithm. Otherwise ("diff") the difference algorithm (faster but numerically unstable) is used.
nullcats	character string, specifying how items with null categories (i.e., categories not observed) should be treated (see details below).
start	an optional vector of starting values.
hessian	logical. Should the Hessian of the final model be computed? If set to FALSE, the vcov method can only return NAs and consequently no standard errors or tests are available in the summary.
reltol, maxit, ...	further arguments passed to optim.
full	logical. Should a full model object be returned? If set to FALSE, no variance-covariance matrix and no matrix of estimating functions are computed.

Details

pcmodel provides a basic fitting function for partial credit models, intended as a building block for fitting partial credit trees. It estimates the partial credit model suggested by Masters (1982) under the cumulative threshold parameterization, i.e., the item-category parameters \eta_{jk} = \sum_{\ell = 1}^{k}\delta_{jk} are estimated by the the function pcmodel.

Null categories, i.e., categories which have not been used, can be problematic when estimating a partial credit model. Several strategies have been suggested to cope with null categories. pcmodel allows to select from three possible strategies via the argument nullcats. If nullcats is set to "keep" (the default), the strategy suggested by Wilson & Masters (1993) is used to handle null categories. That basically means that the integrity of the response framework is maintained, i.e., no category scores are changed. This is not the case, when nullcats is set to "downcode". Then all categories above a null category are shifted down to close the existing gap. In both cases ("keep" and "downcode") the number of estimated parameters is reduced by the number of null categories. When nullcats is set to "ignore", these are literally ignored and a threshold parameter is estimated during the optimization nevertheless. This strategy is used by the related package eRm when fitting partial credit models via eRm::PCM.

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

Value

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

coefficients	a named vector of estimated item-category parameters (without the first item-category parameter which is constrained to 0),
vcov	covariance matrix of the parameters in the model,
data	modified data, used for model-fitting, i.e., cleaned for items without variance, 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. Be careful, this is different than for objects of class "raschmodel" or "btmodel", where data contains the original data,
items	logical vector of length ncol(dat), indicating which items have variance (TRUE), i.e., are identified and have been used for the estimation or not (FALSE),
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	either NULL or, if there have been null categories, a list of length ncol(y) with logical vectors specifying which categories are null categories (TRUE) or not (FALSE),
esf	list of elementary symmetric functions and their derivatives for estimated parameters,
loglik	log-likelihood of the fitted model,
df	number of estimated parameters,
code	convergence code from optim,
iterations	number of iterations used by optim,
reltol	tolerance passed to optim,
call	original function call.

References

Masters GN (1992). A Rasch Model for Partial Credit Scoring. Psychometrika, 47(2), 149–174.

Wilson M, Masters GN (1993). The Partial Credit Model and Null Categories. Psychometrika, 58(1), 87–99.

See Also

gpcmodel, rsmodel, raschmodel, nplmodel, btmodel

Examples

o <- options(digits = 4)

## Verbal aggression data
data("VerbalAggression", package = "psychotools")

## Partial credit model for the other-to-blame situations
pcm <- pcmodel(VerbalAggression$resp[, 1:12])
summary(pcm)

## visualizations
plot(pcm, type = "profile")
plot(pcm, type = "regions")
plot(pcm, type = "piplot")
plot(pcm, type = "curves")
plot(pcm, type = "information")

## Get data of situation 1 ('A bus fails to
## stop for me') and induce a null category in item 2.
pcd <- VerbalAggression$resp[, 1:6, drop = FALSE]
pcd[pcd[, 2] == 1, 2] <- NA

## fit pcm to these data, comparing downcoding and keeping strategy
pcm_va_keep  <- pcmodel(pcd, nullcats = "keep")
pcm_va_down  <- pcmodel(pcd, nullcats = "downcode")

plot(x = coef(pcm_va_keep), y = coef(pcm_va_down),
     xlab = "Threshold Parameters (Keeping)",
     ylab = "Threshold Parameters (Downcoding)",
     main = "Comparison of two null category strategies (I2 with null category)", 
     pch = rep(as.character(1:6), each = 2)[-3])
abline(b = 1, a = 0)

options(digits = o$digits)

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