# gpcmodel

##### Generalized Partial Credit Model Fitting Function

`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.

- Keywords
- regression

##### 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`NA`

s 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) or Debelak & Strobl
(2018) 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:

estimated model parameters in slope/intercept parametrization,

covariance matrix of the model parameters,

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,

logical vector of length `ncol(y)`

, indicating
which items were used during estimation,

list of length `ncol(y)`

, containing integer
vectors starting from one to the number of categories minus one per
item,

number of observations (with non-zero weights),

original number of observations in `y`

,

the weights used (if any),

logical indicating whether the data contain `NA`

s,

currently always `NULL`

as eventual items with null
categories are handled via `"downcode"`

,

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),

log-likelihood of the fitted model,

number of estimated (more precisely, returned) model parameters,

convergence code from `mirt`

,

number of iterations used by `mirt`

,

convergence threshold passed to `mirt`

,

the logical `grouppars`

value,

the `type`

of model restriction specified,

the `mirt`

object fitted internally.

##### 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.
10.18637/jss.v048.i06

Debelak R, Strobl C (2018).
Investigating Measurement Invariance by Means of Parameter Instability Tests
for 2PL and 3PL Models.
*Educational and Psychological Measurement*, forthcoming.
10.1177/0013164418777784

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

##### See Also

##### Examples

```
# NOT RUN {
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)
}
# }
```

*Documentation reproduced from package psychotools, version 0.5-1, License: GPL-2 | GPL-3*