Package 'eirm' reference manual

Package 'eirm'

Title:	Explanatory Item Response Modeling for Dichotomous and Polytomous Items
Description:	Analysis of dichotomous and polytomous response data using the explanatory item response modeling framework, as described in Bulut, Gorgun, & Yildirim-Erbasli (2021) <doi:10.3390/psych3030023>, Stanke & Bulut (2019) <doi:10.21449/ijate.515085>, and De Boeck & Wilson (2004) <doi:10.1007/978-1-4757-3990-9>. Generalized linear mixed modeling is used for estimating the effects of item-related and person-related variables on dichotomous and polytomous item responses.
Authors:	Okan Bulut [aut, cre]
Maintainer:	Okan Bulut <[email protected]>
License:	GPL (>= 3)
Version:	0.5
Built:	2025-02-22 06:11:42 UTC
Source:	https://github.com/okanbulut/eirm

Title:

Explanatory Item Response Modeling for Dichotomous and Polytomous Items

Description:

Analysis of dichotomous and polytomous response data using the explanatory item response modeling framework, as described in Bulut, Gorgun, & Yildirim-Erbasli (2021) <doi:10.3390/psych3030023>, Stanke & Bulut (2019) <doi:10.21449/ijate.515085>, and De Boeck & Wilson (2004) <doi:10.1007/978-1-4757-3990-9>. Generalized linear mixed modeling is used for estimating the effects of item-related and person-related variables on dichotomous and polytomous item responses.

Authors:

Okan Bulut [aut, cre]

Maintainer:

Okan Bulut <[email protected]>

License:

GPL (>= 3)

Version:

0.5

Built:

2025-02-22 06:11:42 UTC

Source:

https://github.com/okanbulut/eirm

Help Index

Profile Analysis of Multivariate Data in R

Description

The package eirm provides a set of tools to analyze and visualize dichotomous and polytomous item responses using the explanatory item response modeling (EIRM). The generalized linear mixed modeling (GLMM) framework is used for examining the impact of item-related and person-related variables on responses. The items are repeated measures that are nested underpersons. The model details can be found at de Boeck and Wilson's (2004) Explanatory Item Response Models - A Generalized Linear and Nonlinear Approach <DOI: 10.1007/978-1-4757-3990-9>.

Author(s)

Okan Bulut [email protected]

References

De Boeck, P., & Wilson, M. (2004). Explanatory item response models: A generalized linear and nonlinear approach. New York: Springer-Verlag.

Estimating explanatory item response modeling using the GLMM framework

Description

The eirm function estimates explanatory item response models with item-related and person-related covariates. The function requires the data to be in a long format where items are nested within persons. If item responses are polytomous, then the data has to be reformatted using the polyreformat function.

Usage

eirm(
  formula,
  data,
  engine = "lme4",
  na.action = "na.omit",
  weights = NULL,
  mustart = NULL,
  etastart = NULL,
  cov.prior = "wishart",
  fixef.prior = NULL,
  control = glmerControl(optimizer = "optimx", calc.derivs = FALSE, optCtrl =
    list(method = "nlminb", starttests = FALSE, kkt = FALSE))
)
eirm(
  formula,
  data,
  engine = "lme4",
  na.action = "na.omit",
  weights = NULL,
  mustart = NULL,
  etastart = NULL,
  cov.prior = "wishart",
  fixef.prior = NULL,
  control = glmerControl(optimizer = "optimx", calc.derivs = FALSE, optCtrl =
    list(method = "nlminb", starttests = FALSE, kkt = FALSE))
)

Arguments

`formula`	A regression-like formula that defines item responses as a dependent variable and explanatory predictors as independent predictors. For example, "response ~ -1 + predictor1 + predictor2". Use -1 in the formula to avoid the estimation of an intercept parameter.
`data`	A data frame in a long format where there are multiple rows for each person (i.e., nested data). The data should involve a variable that represents item responses, a variable that represents persons, and additional predictors to be used for 'explaining' item responses.
`engine`	Estimation engine with the options of either "lme4" (default) or "blme".
`na.action`	How missing data should be handled (default: "na.omit").
`weights`	Weights to be used in the estimation.
`mustart`, `etastart`	Model specification arguments for glmer. See `glmer` for details. Not used when engine = "lme4".
`cov.prior`	A BLME prior or list of priors with the options of "wishart" (default), "invwishart", "gamma", "invgamma", or NULL to impose a prior over the covariance of the random effects. Not used when engine = "lme4".
`fixef.prior`	A BLME prior of family "normal", "t", "horseshoe", or NULL (default) to impose a prior over the fixed effects. Not used when engine = "lme4".
`control`	Control settings for the glmer function in lme4. Note that the optimx package is used by default to speed up the estimation. For higher accuracy in the results, the default lme4 optimizers can be used.

Value

An eirm-class list that includes the EIRM formula used for the estimation, estimated parameters in the model, ability estimates for persons and other random effects (if any), and the complete set of results returned from the glmer function. These results can be used for further analysis and graphics based on lme4.

Examples


data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
print(mod0) # To get easiness parameters
print(mod0, difficulty = TRUE) # To get difficulty parameters
plot(mod0)
mod1 <- eirm(formula = "r2 ~ -1 + situ + btype + mode + (1|id)", data = VerbAgg)
print(mod1) # To get easiness parameters
print(mod1, difficulty = TRUE) # To get difficulty parameters
plot(mod1)

data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
print(mod0) # To get easiness parameters
print(mod0, difficulty = TRUE) # To get difficulty parameters
plot(mod0)
mod1 <- eirm(formula = "r2 ~ -1 + situ + btype + mode + (1|id)", data = VerbAgg)
print(mod1) # To get easiness parameters
print(mod1, difficulty = TRUE) # To get difficulty parameters
plot(mod1)

Graphical user interface (GUI) of the eirm function

Description

An interactive Shiny application for running the eirm function. The application allows users to import the (long-format) response data, define the response variable and predictors, and run the estimation, and produce the output, as well as the item-person plot, on the screen.

Usage

eirmShiny()
eirmShiny()

Examples

## Not run: 
eirmShiny()

## End(Not run)
## Not run: 
eirmShiny()

## End(Not run)

Plots of Estimated Marginal Effects in Explanatory IRT Models

Description

This function uses ggpredict to calculate marginal effects for explanatory variables in an explanatory IRT model estimated with the eirm function. It returns a plot of estimated probabilities generated by the explanatory IRT model while holding some predictors constant.

Usage

marginalplot(x, predictors, conf.int = 0.95, plot.title = NULL)
marginalplot(x, predictors, conf.int = 0.95, plot.title = NULL)

Arguments

`x`	An eirm object returned from the `eirm` function.
`predictors`	Character vector with the names of up to three categorical predictors from the eirm model. The first predictor is plotted on the x-axis; the second predictor is used as a group variable; the third predictor is used as a facet in the plot.
`conf.int`	Confidence interval to be used in the plot (default = 0.95 for 95% confidence intervals).
`plot.title`	A title to be used in the plot.

Value

A ggplot2 object.

Examples

data("VerbAgg")
mod <- eirm(formula = "r2 ~ -1 + situ + btype + mode + (1|id)", data = VerbAgg)

# Only one predictor
p1 <- marginalplot(mod, predictors = c("situ"))

# Two predictors
p2 <- marginalplot(mod, predictors = c("situ", "btype"))

# All three predictors
p3 <- marginalplot(mod, predictors = c("situ", "btype", "mode"))
data("VerbAgg")
mod <- eirm(formula = "r2 ~ -1 + situ + btype + mode + (1|id)", data = VerbAgg)

# Only one predictor
p1 <- marginalplot(mod, predictors = c("situ"))

# Two predictors
p2 <- marginalplot(mod, predictors = c("situ", "btype"))

# All three predictors
p3 <- marginalplot(mod, predictors = c("situ", "btype", "mode"))

Person-Item Map for Explanatory IRT Models

Description

This function creates a person-item map for an object returned from the eirm function. The function was modified from plotPImap in package eRm.

Usage

## S3 method for class 'eirm'
plot(
  x,
  difficulty = FALSE,
  sorted = TRUE,
  theta = NULL,
  main = "Person-Item Map",
  latdim = "Latent Dimension",
  pplabel = "Person\nParameter\nDistribution",
  cex.gen = 0.7,
  ...
)
## S3 method for class 'eirm'
plot(
  x,
  difficulty = FALSE,
  sorted = TRUE,
  theta = NULL,
  main = "Person-Item Map",
  latdim = "Latent Dimension",
  pplabel = "Person\nParameter\nDistribution",
  cex.gen = 0.7,
  ...
)

Arguments

`x`	An object returned from the `eirm` function.
`difficulty`	Whether difficulty should be used instead of easiness (default: FALSE).
`sorted`	Whether the parameters should be sorted in the plot (default: TRUE).
`theta`	A vector of estimated theta values. If NULL, then theta values are obtained from the estimated eirm model. It might be better to save the theta values from a baseline model (e.g., Rasch) and use them when creating a person-item map.
`main`	Main title for the person-item map.
`latdim`	Label of the x-axis, i.e., the latent dimension.
`pplabel`	Title for the upper panel displaying the person parameter distribution.
`cex.gen`	A numerical value giving the amount by which plotting text and symbols should be magnified relative to the default. Here cex.gen applies to all text labels. The default is 0.7.
`...`	Other plot-related arguments.

Value

A person-item map.

Examples

data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
plot(mod0)
plot(mod0, difficulty = TRUE) # Plot difficulty instead of easiness
data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
plot(mod0)
plot(mod0, difficulty = TRUE) # Plot difficulty instead of easiness

Reformat polytomous item responses in a long format for explanatory item response modeling

Description

This function prepares the data with polytomous item responses for explanatory item response modeling. If the data is already in a long format (i.e., items by person), it only recodes the polytomous responses and creates a new variable to be used for the estimation. If the data is not in the long format, then both reshaping the data into the long format and recoding items can be done simultaneously.

Usage

polyreformat(
  data,
  id.var,
  long.format = FALSE,
  var.name = "item",
  val.name = "resp"
)
polyreformat(
  data,
  id.var,
  long.format = FALSE,
  var.name = "item",
  val.name = "resp"
)

Arguments

`data`	A data frame – either in a wide format where the rows represent persons and columns represent items explanatory variables or in a long format where there are multiple rows for each person (i.e., nested data)
`id.var`	The variable that represents examinee IDs.
`long.format`	Whether the data follow a wide format and thus need to be transformed into a long format first (default is FALSE)
`var.name`	The variable that represents item IDs if the data is already in long format; otherwise this is the of the variable that represents item IDs once the data is transformed into long format.
`val.name`	The variable that represents item responses if the data is already in long format; otherwise this is the of the variable that represents item responses once the data is transformed into long format.

Value

Reformatted data for explanatory item response modeling.

Examples

data("VerbAgg")
VerbAgg2 <- polyreformat(data=VerbAgg, id.var = "id", long.format = FALSE,
var.name = "item", val.name = "resp")
head(VerbAgg2)
data("VerbAgg")
VerbAgg2 <- polyreformat(data=VerbAgg, id.var = "id", long.format = FALSE,
var.name = "item", val.name = "resp")
head(VerbAgg2)

Printing Estimated Parameters for Explanatory IRT Models

Description

This generic function prints estimated parameters from an eirm object returned from the eirm function.

Usage

## S3 method for class 'eirm'
print(x, difficulty = FALSE, ...)
## S3 method for class 'eirm'
print(x, difficulty = FALSE, ...)

Arguments

`x`	An object returned from the `eirm` function.
`difficulty`	Whether difficulty should be used instead of easiness (default: FALSE)
`...`	Other print-related arguments.

Value

Estimated parameters from an eirm object.

Examples

data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
print(mod0) # or, just mod0
print(mod0, difficulty = TRUE)
data("VerbAgg")
mod0 <- eirm(formula = "r2 ~ -1 + situ + btype + (1|id)", data = VerbAgg)
print(mod0) # or, just mod0
print(mod0, difficulty = TRUE)

Fabricated Short Quiz with Explanatory Variables

Description

This dataset contains examinees' responses to a short quiz with 10 items.The data set has been fabricated to demonstrate Explanatory Item Response Modeling.

Usage

testdata
testdata

Format

A long format data frame containing 1000 examinees' responses to 10 items and additional variables.

person: Examinee ID
item: Item ID
response: Dichotomous item responses
gender: Examinees' gender where F is female and M is male
itemtype: A variable to define whether the items on the quiz have a visual component

Verbal Aggression Data in a Wide Format

Description

The Verbal Aggression data set is a wide-format version of the VerbAgg data set in the lme4 package (Bates, Maechler, Bolker, & Walker, 2015) in R.

Usage

VerbAggWide
VerbAggWide

Format

A data frame with 316 participants and 27 variables.

The original Verbal Agression data set was in a long format where items are nested within respondents. VerbAggWide is a wide-format version of the original data set. The first three variables are 'id' as the respondent ID, 'Anger' as the respondents' anger scores, and 'Gender' is the respondents' gender (M: male; F: Female). The remaining columns are the respondents' responses to the Verbal aggression items (0: No; 1: Perhaps; 2: Yes). For more information about the data set, see http://bear.soe.berkeley.edu/EIRM/.

Source

Bates, D., Maechler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1-48. doi:10.18637/jss.v067.i01.