Package {GPCMlasso}

GPCMlasso: Regularized Explanatory Generalized Partial Credit Models

Description

The GPCMlasso package fits generalized partial credit models and related ordinal item response models with explanatory variables. It supports models with global covariate effects, item-specific covariate effects, and regularization terms for variable selection and the clustering of item-specific effects by fusion penalties.

Details

The original functionality of the package focuses on the detection of differential item functioning (DIF) in generalized partial credit models. In this framework, DIF effects are explicitly parametrized and selected by penalized marginal maximum likelihood estimation. The package additionally provides tools for fitting explanatory generalized partial credit models with global and item-specific covariate effects, including full-fusion penalties to identify clusters of items with equal covariate effects.

Several variables can be considered simultaneously, and both continuous and categorical covariates can be included. The package covers generalized partial credit models and special cases such as partial credit models, rating scale models, and models for binary item responses.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

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. doi:10.3758/s13428-019-01224-2

See Also

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

Examples

data(tenseness_small)

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

## Not run: 
## ------------------------------------------------------------
## Classical DIF analysis
## ------------------------------------------------------------
fit_dif <- GPCMlasso(
  formula = form_cov,
  data = tenseness_small,
  model = "GPCM",
  control = ctrl_GPCMlasso(
    cores = 1,
    l.lambda = 10,
    trace = FALSE
  )
)

summary(fit_dif)
plot(
  fit_dif,
  type = "DIF",
  panels_per_page = 2,
  columns = 2,
  ask_new = FALSE
)

## ------------------------------------------------------------
## Explanatory GPCM-X with global and item-specific effects
## and fusion penalty
## ------------------------------------------------------------
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
  )
)

summary(
  fit_fusion,
  effect.scale = "effect"
)

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

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)

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

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:

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

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

Control function for GPCMlasso

Description

Control parameters for penalty terms and for tuning the fitting algorithm.

Usage

ctrl_GPCMlasso(
  log.lambda = TRUE,
  lambda = NULL,
  l.lambda = 50,
  lambda.min = 0.1,
  penalize.main.effects = FALSE,
  fuse.per.variable = FALSE,
  scale.covariate.effects = TRUE,
  include.item.effects = TRUE,
  adaptive = TRUE,
  weight.penalties = TRUE,
  ada.lambda = 1e-04,
  ada.power = 1,
  Q = 15,
  lambda2 = 1e-04,
  cvalue = 1e-05,
  trace = TRUE,
  folds = 10,
  cores = 25,
  null_thresh = 0.01,
  gradtol = 1e-06,
  steptol = 1e-06,
  iterlim = 500,
  precision = 3,
  all.dummies = FALSE,
  ctrl.gpcm = list()
)

Arguments

Value

A list of control parameters used by GPCMlasso.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

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. doi:10.3758/s13428-019-01224-2

See Also

GPCMlasso, plot.GPCMlasso

Examples

ctrl <- ctrl_GPCMlasso()
str(ctrl)

ctrl_small <- ctrl_GPCMlasso(
  l.lambda = 5,
  cores = 1,
  trace = FALSE
)

ctrl_fusion <- ctrl_GPCMlasso(
  l.lambda = 5,
  cores = 1,
  penalize.main.effects = TRUE,
  include.item.effects = TRUE,
  fuse.per.variable = TRUE,
  scale.covariate.effects = FALSE,
  trace = FALSE
)

Plot function for GPCMlasso

Description

Plot function for a GPCMlasso object. Plots coefficient paths along the tuning parameter lambda.

Usage

## S3 method for class 'GPCMlasso'
plot(x, select = c("BIC", "AIC", "cAIC", "cv"),
type = c("DIF", "Variable"), variable.scale = c("effect", "internal"),
log.lambda = TRUE, panels_per_page = 1, panels = "all",
columns = NULL, ask_new = TRUE, lambda.lines = TRUE,
equal_range = TRUE, add.to.lambda = 0, items_per_page = NULL,
items = NULL, plots = NULL, ...)

Arguments

Details

For type = "DIF", one plot panel per item is created and the internal item-specific parameters are shown. The argument panels can be used to restrict the output to selected item panels.

For type = "Variable", one plot panel per covariate is created. The argument panels can be used to restrict the output to selected covariate panels. By default, the paths are shown on the response-effect scale, i.e. global effect minus item-specific DIF parameter. This corresponds to the interpretable effect of a covariate on the local logit under the internal DIF parameterization.

For type = "Variable", effect-scale plots are recommended for interpretation.

Predict function for GPCMlasso

Description

Predict category probabilities or linear predictors from a fitted GPCMlasso model.

Usage

## S3 method for class 'GPCMlasso'
predict(
  object,
  coefs = NULL,
  newdata = NULL,
  theta = NULL,
  type = c("link", "response"),
  trait.cores = 1,
  ...
)

Arguments

Details

Predictions are based on a selected coefficient vector. If no coefficient vector is supplied, the cross-validation optimal coefficient vector is used when cross-validation was performed; otherwise, the BIC-optimal coefficient vector is used.

For predictions on the original data, posterior trait estimates are obtained from trait.posterior(). For predictions on newdata, trait values must be supplied via the argument theta, because posterior trait estimation for new persons requires response data and is not inferred automatically from covariates alone.

Results are lists of vectors with length equal to the number of response categories in case of probabilities (type = "response") or the number of adjacent-category logits in case of linear predictors (type = "link").

Author(s)

Gunther Schauberger
gunther@stat.uni-muenchen.de

See Also

GPCMlasso

Tenseness Data from the Freiburg Complaint Checklist

Description

Data from the Freiburg Complaint Checklist. The data contain all 8 items corresponding to the scale Tenseness from the standardization sample of the Freiburg Complaint Checklist.

Format

A data frame containing data from the Freiburg Complaint Checklist. The item responses refer to the scale Tenseness and are measured on a 5-point Likert scale, where low values correspond to low frequencies or low intensities of the respective complaint and high values correspond to high frequencies or high intensities.

The data frame contains the following variables:

Clammy_hands

Do you have clammy hands?

Sweat_attacks

Do you have sudden attacks of sweating?

Clumsiness

Do you notice that you behave clumsily?

Wavering_hands

Do your hands shake frequently, for example when lighting a cigarette or when holding a cup?

Restless_hands

Do you notice that your hands are restless?

Restless_feet

Do you notice that your feet are restless?

Twitching_eyes

Do you notice involuntary twitching of your eyes?

Twitching_mouth

Do you notice involuntary twitching of your mouth?

Gender

Gender of the person.

Household

Whether the person lives alone or together with somebody else.

Income

Income, categorized from 1 (low income) to 11 (high income). For simplicity, income can be treated as a metric variable.

WestEast

Whether the person is from East Germany, the former GDR.

Abitur

Whether the person has Abitur, corresponding to A-levels.

Age

Age of the person.

Source

ZPID (2013). PsychData of the Leibniz Institute for Psychology Information ZPID. Trier: Center for Research Data in Psychology.

Fahrenberg, J. (2010). Freiburg Complaint Checklist [Freiburger Beschwerdenliste (FBL)]. Goettingen: Hogrefe.

Examples

data(tenseness)
str(tenseness)

Subset of Tenseness Data from the Freiburg Complaint Checklist

Description

A small subset of the Freiburg Complaint Checklist data. The data contain 5 items, out of the 8 items in the full data set, corresponding to the scale Tenseness, together with two covariates.

Format

A data frame containing a subset of the Freiburg Complaint Checklist data with 200 observations. The complete data set is available as tenseness. The item responses refer to the scale Tenseness and are measured on a 5-point Likert scale, where low values correspond to low frequencies or low intensities of the respective complaint and high values correspond to high frequencies or high intensities.

The data frame contains the following variables:

Clammy_hands

Do you have clammy hands?

Sweat_attacks

Do you have sudden attacks of sweating?

Clumsiness

Do you notice that you behave clumsily?

Wavering_hands

Do your hands shake frequently, for example when lighting a cigarette or when holding a cup?

Restless_hands

Do you notice that your hands are restless?

Gender

Gender of the person.

Age

Age of the person.

Source

ZPID (2013). PsychData of the Leibniz Institute for Psychology Information ZPID. Trier: Center for Research Data in Psychology.

Fahrenberg, J. (2010). Freiburg Complaint Checklist [Freiburger Beschwerdenliste (FBL)]. Goettingen: Hogrefe.

See Also

GPCMlasso, ctrl_GPCMlasso, plot.GPCMlasso, trait.posterior

Examples

data(tenseness_small)

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

## Not run: 
## ------------------------------------------------------------
## Classical DIF analysis
## ------------------------------------------------------------
fit_dif <- GPCMlasso(
  formula = form_cov,
  data = tenseness_small,
  model = "GPCM",
  control = ctrl_GPCMlasso(
    cores = 1,
    l.lambda = 10,
    trace = FALSE
  )
)

summary(fit_dif)
plot(
  fit_dif,
  type = "DIF",
  panels_per_page = 2,
  columns = 2,
  ask_new = FALSE
)

## ------------------------------------------------------------
## Explanatory GPCM-X with global and item-specific effects
## and fusion penalty
## ------------------------------------------------------------
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
  )
)

summary(
  fit_fusion,
  effect.scale = "effect"
)

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

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)

Calculate Posterior Estimates for Trait Parameters

Description

Calculates posterior estimates for trait/person parameters for a fitted GPCMlasso model using the assumed Gaussian distribution of the person parameters.

Usage

trait.posterior(model, coefs = NULL, cores = 25, tol = 1e-04)

Arguments

Details

The function computes posterior means of the latent trait parameters by Gauss-Hermite quadrature. If no coefficient vector is supplied, the cross-validation optimal coefficient vector is used when cross-validation was performed; otherwise, the BIC-optimal coefficient vector is used.

Value

Numeric vector containing posterior estimates of the trait/person parameters.

Author(s)

Gunther Schauberger
gunther.schauberger@tum.de

See Also

GPCMlasso, predict.GPCMlasso

Examples

data(tenseness_small)

form0 <- as.formula(
  paste(
    "cbind(",
    paste(colnames(tenseness_small)[1:5], collapse = ","),
    ") ~ 0"
  )
)

## Not run: 
rsm0 <- GPCMlasso(
  formula = form0,
  data = tenseness_small,
  model = "RSM",
  control = ctrl_GPCMlasso(cores = 1, trace = FALSE)
)

theta_hat <- trait.posterior(rsm0, cores = 1)
summary(theta_hat)

## End(Not run)