itemresp: Data Structure for Item Response Data

Description

A class for representing data from questionnaires along with methods for many generic functions.

Usage

itemresp(data, mscale = NULL, labels = NULL, names = NULL)

Value

itemresp returns an object of class "itemresp" which is a matrix (data transformed to integers 0, 1, ...) plus an attribute "mscale" as a named list for each item (after being checked and potentially suitably coerced or transformed to all integer or all character).

Arguments

data: matrix or data frame. A matrix or data frame with integer values or factors where the rows correspond to subjects and the columns to items. See below for details.
mscale: integer or character. A list of vectors (either integer or character) giving the measurement scale. See below for details. By default guessed from data.
labels: character. A vector of character labels for the items. By default, the column names of data are used or, if these are not available, the string "item" along with numbers 1, 2, ... is used.
names: character. A vector of names (or IDs) for the subjects. By default, no subject names are used.

Details

itemresp is designed for item response data of \(n\) subjects for \(k\) items.

The item responses should be coded in a matrix data with \(n\) rows (subjects) and \(k\) columns (items). Alternatively, data can be a data frame with \(n\) rows (subjects) and \(k\) variables (items), which can be either factors or integer valued vectors.

mscale provides the underlying measurement scale either as integer or character vector(s). If all items are measured on the same scale, mscale can be a vector. Alternatively, it can be provided as a named list of vectors for each item. If the list contains one unnamed element, this element will be used as the measurement scale for items that have not been named. Integers or characters not present in mscale but in data will be replaced by NA. All items must be measured with at least 2 categories. By default, mscale is set to the full range of observed values for all integer items (see example below) and the corresponding levels for all factor items in data.

Methods to standard generic functions include: str, length (number of subjects), dim (number of subjects and items), is.na (only TRUE if all item responses are NA for a subject), print (see print.itemresp for details), summary and plot (see summary.itemresp for details), subsetting via [ and subset (see subset.itemresp for details), is.itemresp and various coercion functions to other classes (see as.list.itemresp for details).

Extracting/replacing properties is available through: labels for the item labels, mscale for the measurement scale, names for subject names/IDs.

Examples

Run this code

## binary responses to three items, coded as matrix
x <- cbind(c(1, 0, 1, 0), c(1, 0, 0, 0), c(0, 1, 1, 1))
## transformed to itemresp object
xi <- itemresp(x)

## printing (see also ?print.itemresp)
print(xi)
print(xi, labels = TRUE)

## subsetting/indexing (see also ?subset.itemresp)
xi[2]
xi[c(TRUE, TRUE, FALSE, FALSE)]
subset(xi, items = 1:2)
dim(xi)
length(xi)

## summary/visualization (see also ?summary.itemresp)
summary(xi)
plot(xi)

## query/set measurement scale labels
## extract mscale (tries to collapse to vector)
mscale(xi)
## extract as list
mscale(xi, simplify = FALSE)
## replacement by list
mscale(xi) <- list(item1 = c("no", "yes"),
  item2 = c("nay", "yae"), item3 = c("-", "+"))
xi
mscale(xi)
## replacement with partially named list plus default
mscale(xi) <- list(item1 = c("n", "y"), 0:1)
mscale(xi)
## replacement by vector (if number of categories constant)
mscale(xi) <- c("-", "+")
mscale(xi, simplify = FALSE)

## query/set item labels and subject names
labels(xi)
labels(xi) <- c("i1", "i2", "i3")
names(xi)
names(xi) <- c("John", "Joan", "Jen", "Jim")
print(xi, labels = TRUE)

## coercion (see also ?as.list.itemresp)
## to integer matrix
as.matrix(xi)
## to data frame with single itemresp column
as.data.frame(xi)
## to list of factors
as.list(xi)
## to data frame with factors
as.list(xi, df = TRUE)


## polytomous responses with missing values and unequal number of
## categories in a data frame
d <- data.frame(
  q1 = c(-2, 1, -1, 0, NA, 1, NA),
  q2 = c(3, 5, 2, 5, NA, 2, 3),
  q3 = factor(c(1, 2, 1, 2, NA, 3, 2), levels = 1:3,
    labels = c("disagree", "neutral", "agree")))
di <- itemresp(d)
di

## auto-completion of mscale: full range (-2, ..., 2) for q1, starting
## from smallest observed (negative) value (-2) to the same (positive)
## value (2), full (positive) range for q2, starting from smallest
## observed value (2) to largest observed value (5), missing category of
## 4 is detected, for q3 given factor levels are used
mscale(di)

## set mscale for q2 and add category 1, q1 and q3 are auto-completed:
di <- itemresp(d, mscale = list(q2 = 1:5))

## is.na.itemresp - only true for observation 5 (all missing)
is.na(di)

## illustration for larger data set
data("VerbalAggression", package = "psychotools")
r <- itemresp(VerbalAggression$resp[, 1:12])
str(r)
head(r)
plot(r)
summary(r)
prop.table(summary(r), 1)

## dichotomize response
r2 <- r
mscale(r2) <- c(0, 1, 1)
plot(r2)

## transform to "likert" package
if(require("likert")) {
lik <- likert(as.data.frame(as.list(r)))
lik
plot(lik)
}