shape_df: Create a data frame of item metadata

Description

This function creates a data frame which includes item meta (e.g., item parameter, categories, models ...) to be used for the IRT model-data fit analysis as well as other analyses.

Usage

shape_df(par.dc = list(a = NULL, b = NULL, g = NULL), par.py = list(a =
  NULL, d = NULL), item.id = NULL, cats, model, empty.par = FALSE)

Arguments

par.dc

A list containing three vectors of dichotomous item parameters. Namely, the item discrimination (a), item difficulty (b), and item guessing parameters.

par.py

A list containing a vector of polytomous item discrimination (or slope) parameters and a list of polytomous item threshold (or step) parameters. In the list, the argument a should have a vector of slope parameters and the argument d should include a list of threshold (or step) parameters. See below for more details.

item.id

A character vector of item IDs. If NULL, an ID is automatically given to each item.

cats

A vector containing the number of score categories for items.

model

A character vector of IRT models corresponding to items. The available IRT models are "1PLM", "2PLM", "3PLM", and "DRM" for dichotomous items, and "GRM" and "GPCM" for polytomous items. Note that "DRM" covers all dichotomous IRT models (i.e, "1PLM", "2PLM", and "3PLM") and "GRM" and "GPCM" represent the graded response model and (generalized) partial credit model, respectively.

empty.par

A logical value to create an empty item meta. If TRUE, the number of score categories and corresponding IRT models should be specified in the arguments of cats and model, respectively. In the empty item meta, the item slope parameter has a fixed value of 1, the item difficulty (or threshold) parameter has a fixed value of 0, and the item guessing parameter has a fixed value of .2. Default is FALSE.

Value

This function returns a data frame.

Details

For any item where "1PLM" or "2PLM" is specified in model, the item guessing parameter will be NA. If model is a vector of \(length = 1\), the specified model is replicated across all items. As in the function simdat, it is important to clearly specify cats according to the order of items in the test form when a data frame for a mixed-format test needs to be created. See simdat for more details about how to specify cats.

When specifying item parameters in par.dc and par.dc, keep the order of item parameter types. For example, in the list of par.dc, the order of items parameters should be the slope, the difficulty, and the guessing parameters.

When specifying item parameters in par.dc, note that in the list of the threshold (or step) parameters, each vector should contain the threshold (or step) parameters for each item. When an item follows the (generalized) partial credit model, the item step parameters are the overall item difficulty (or location) parameter subtracted by the difficulty (or threshold) parameter for each category. Thus, the number of step parameters for item with m categories is m-1 because a step parameter for the first category does not affect the category probabilities.

Examples

Run this code

# NOT RUN {
## a mixed-item format test form
## with five dichotomous and two polytomous items
# create a list containing the dichotomous item parameters
par.dc <- list(a=c(1.1, 1.2, 0.9, 1.8, 1.4),
               b=c(0.1, -1.6, -0.2, 1.0, 1.2),
               g=rep(0.2, 5))

# create a list containing the polytomous item parameters
par.py <- list(a=c(1.4, 0.6),
               d=list(c(0.0, -1.9, 1.2), c(0.4, -1.1, 1.5, 0.2)))

# create a numeric vector of score categories for the items
cats <- c(2, 4, 2, 2, 5, 2, 2)

# create a character vector of IRT models for the items
model <- c("DRM", "GRM", "DRM", "DRM", "GPCM", "DRM", "DRM")

# create an item meta set
shape_df(par.dc=par.dc, par.py=par.py, cats=cats, model=model)

## an empty item meta with five dichotomous and two polytomous items
# create a numeric vector of score categories for the items
cats <- c(2, 4, 3, 2, 5, 2, 2)

# create a character vector of IRT models for the items
model <- c("1PLM", "GRM", "GRM", "2PLM", "GPCM", "DRM", "3PLM")

# create an empty item meta set
shape_df(cats=cats, model=model, empty.par=TRUE)

## an item meta for a single-item format test form with five dichotomous
shape_df(par.dc=par.dc, cats=rep(2, 5), model="DRM")


# }