PCModel.fit: Partial Credit Model Fitting Function

Description

PCModel.fit is a basic fitting function for partial credit models.

Usage

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

Arguments

object that can be coerced (via as.matrix). Typically either already a matrix or a data.frame

weights

an optional vector of weights, interpreted as case
    weights (integer only).

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 vector of length one, specifying how items with
  null categories, i.e., categories not used, 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.

`Value`

PCModel.fit returns an S3 object of class "PCModel", 
  i.e., a list with components as follows.
coefficientsa nemd vector of estimated item-category
    parameters (without first item-category parameter which is
    constrained to 0),
vcovcovariance matrix of the parameters in the model,
datamodified 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 "btReg", where data contains
    the original data,
itemslogical 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),
categorieslist of length ncol(y), containing integer
    vectors starting from one to the number of categories minus one per
    item,
nnumber of observations (with non-zero weights),
n_orgoriginal number of observations in y,
weightsthe weights used (if any),
nalogical indicating whether the data contain NAs,
nullcatseither 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),
esflist of elementary symmetric functions and their
    derivatives for estimated parameters,
logliklog-likelihood of the fitted model,
dfnumber of estimated parameters,
codeconvergence code from optim,
iterationsnumber of iterations used by optim,
reltoltolerance passed to optim.

`Details`

PCModel.fit provides a basic fitting function for partial credit models,
  intended as a building block for fitting partial credit trees.
  
  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.fit
  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 PCM.
  PCModel.fit returns an object of class "PCModel" for
  which several basic methods are available, including print,
  plot, summary, coef, vcov, and logLik.

`References`

Wilson, M. & Masters, G. N. (1993). The partial credit model
  and null categories. Psychometrika, 58(1), 87-99.

`See Also`

RSModel.fit, RaschModel.fit, btReg.fit

`Examples`

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

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

## 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.fit(pcd, nullcats = "keep")
pcm_va_down  <- PCModel.fit(pcd, nullcats = "downcode")

plot(x = coef(pcm_va_keep), y = coef(pcm_va_down),
     xlab = "Threshold Parameters (Downcoding)",
     ylab = "Threshold Parameters (Keeping)",
     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)
Run the code above in your browser using DataLab