GPCMlasso: Fit Regularized Generalized Partial Credit Models

In GPCMlasso: Regularized Explanatory Generalized Partial Credit Models

Fit Regularized Generalized Partial Credit Models

Description

Fits generalized partial credit models and related ordinal item response models with optional explanatory variables. The function can be used for differential item functioning (DIF) detection and for explanatory item response modelling with global and item-specific covariate effects.

Usage

GPCMlasso(
  formula,
  data,
  DSF = FALSE,
  model = c("PCM", "RSM", "GPCM", "GRSM", "RM", "2PL"),
  control = ctrl_GPCMlasso(),
  cv = FALSE,
  main.effects = TRUE
)

Arguments

formula	Formula specifying the item responses and optional covariates. Item responses must be supplied on the left-hand side using cbind(). Covariates are specified on the right-hand side. If the right-hand side is ~ 0, a model without covariates is fitted.
data	Data frame containing the ordinal item response data and all covariates.
DSF	Logical. Should differential step functioning (DSF) be considered? If DSF = TRUE, one parameter per step between two adjacent response categories is introduced. For binary items, DSF and DIF coincide.
model	Character string specifying the underlying item response model. Available options are "PCM", "RSM", "GPCM", "GRSM", "RM", and "2PL". Generalized models allow item-specific discrimination parameters. "RM" and "2PL" are available for binary item responses only.
control	Control object specifying algorithmic and numerical optimization options, usually created by ctrl_GPCMlasso.
cv	Logical. Should cross-validation be performed? Cross-validation can be used for tuning parameter selection.
main.effects	Logical. Should global covariate effects be included for models with covariates? Additional item-specific effects can be enabled via include.item.effects in ctrl_GPCMlasso.

Details

A joint parametric model is set up based on an item response model chosen by the user. Several covariates can be considered simultaneously. For DIF models, item-specific covariate effects are introduced and selected by a lasso-type penalty. For explanatory GPCM-X models, global covariate effects and item-specific deviations can be included, and fusion penalties can be used to cluster item-specific effects referring to the same covariate.

Value

An object of class "GPCMlasso", a list containing:

coefficients	Matrix of estimated parameters, one row per tuning parameter value.
logLik	Vector of log-likelihood values, one per tuning parameter.
cv_error	Vector of cross-validation errors. Only relevant if cv = TRUE.
call	The matched function call.
model	The selected item response model.
data	The data used for model fitting.
control	The control list used for model fitting.
DSF	Logical value indicating whether DSF was used.
formula	The model formula.
item.names	Item names.
Y	Matrix containing the item responses.
design_list	List of design matrices and auxiliary objects used internally.
AIC	Vector of AIC values, one per tuning parameter.
BIC	Vector of BIC values, one per tuning parameter.
cAIC	Vector of corrected AIC values, one per tuning parameter.
df	Vector of degrees of freedom, one per tuning parameter.
coef.rescal	Matrix of parameters rescaled to their original scales.
main.effects	Logical value indicating whether global covariate effects were included.
scale_cols	Internal indicator specifying which design columns are multiplied by item discrimination parameters.

Author(s)

Gunther Schauberger
[e-mail]

References

Schauberger, G. and Mair, P. (2020). A regularization approach for the detection of differential item functioning in generalized partial credit models. Behavior Research Methods, 52, 279–294. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3758/s13428-019-01224-2")}

See Also

GPCMlasso-package, ctrl_GPCMlasso, plot.GPCMlasso, predict.GPCMlasso, trait.posterior

Examples

data(tenseness_small)

## Response formula with five ordinal items
form_items <- as.formula(
  paste(
    "cbind(",
    paste(colnames(tenseness_small)[1:5], collapse = ","),
    ") ~ 0"
  )
)

## Formula including covariates
form_cov <- as.formula(
  paste(
    "cbind(",
    paste(colnames(tenseness_small)[1:5], collapse = ","),
    ") ~ Gender + Age"
  )
)

## Not run: 
## ------------------------------------------------------------
## Example 1: Classical DIF analysis as in Schauberger and Mair
## ------------------------------------------------------------
##
## A GPCM is fitted with item-specific covariate effects.
## Selected non-zero item-specific effects indicate DIF.

fit_dif <- GPCMlasso(
  formula = form_cov,
  data = tenseness_small,
  model = "GPCM",
  control = ctrl_GPCMlasso(
    cores = 1,
    l.lambda = 10,
    trace = FALSE
  )
)

fit_dif
summary(fit_dif)

## Plot DIF paths for selected item panels
plot(
  fit_dif,
  type = "DIF",
  panels = 1:2,
  panels_per_page = 2,
  columns = 2,
  ask_new = FALSE
)

## Predicted category probabilities and posterior trait estimates
pred_dif <- predict(fit_dif, type = "response")
theta_dif <- trait.posterior(fit_dif, cores = 1)


## ------------------------------------------------------------
## Example 2: Explanatory GPCM-X with global, item-specific,
## and fused covariate effects
## ------------------------------------------------------------
##
## This model includes global covariate effects and item-specific
## deviations from these global effects. The fusion penalty encourages
## clusters of items with equal covariate effects.
##
## Since information criteria are not uniquely defined for the fusion
## model, cross-validation is used for tuning parameter selection.

set.seed(1860)

fit_fusion <- GPCMlasso(
  formula = form_cov,
  data = tenseness_small,
  model = "GPCM",
  main.effects = TRUE,
  cv = TRUE,
  control = ctrl_GPCMlasso(
    cores = 1,
    l.lambda = 10,
    folds = 2,
    penalize.main.effects = TRUE,
    include.item.effects = TRUE,
    fuse.per.variable = TRUE,
    scale.covariate.effects = FALSE,
    trace = FALSE
  )
)

fit_fusion

## Summary on the interpretable response-effect scale
summary(
  fit_fusion,
  effect.scale = "effect"
)

## Available variable panels
fit_fusion$design_list$x.names

## Plot covariate effect paths for all available covariate panels
plot(
  fit_fusion,
  type = "Variable",
  panels = fit_fusion$design_list$x.names,
  panels_per_page = 2,
  columns = 2,
  variable.scale = "effect",
  select = "cv",
  ask_new = FALSE
)

## End(Not run)

GPCMlasso documentation built on Sept. 8, 2026, 5:08 p.m.