item.distract: Distractor Analysis for Multiple-Choice Items

In misty: Miscellaneous Functions 'T. Yanagida'

Distractor Analysis for Multiple-Choice Items

Description

This function conducts distractor analysis for multiple-choice test items, i.e., computes attractor-distractor selection frequency, percentage, and total point-biserial or biserial correlation.

Usage

item.distract(data, ..., key, exclude = NULL, na.keep = FALSE, correct = TRUE,
              method = c("pbiser", "biser"), ml = FALSE,
              print = c("all", "nUQ", "key", "n", "perc", "r"),
              color = "default", style = c("regular", "bold", "italic"),
              na.omit = FALSE, digits = 1, r.digits = 3, as.na = NULL,
              write = NULL, append = TRUE, check = TRUE, output = TRUE)

Arguments

data	a data frame. Note that missing values should be represented with NA and not with a valid code. The argument as.na can be used to convert values to NA before conducting the analysis.
...	an expression indicating the variable names in data e.g., item.distract(dat, x1, x2, x3). Note that the operators +, -, ~, :, ::, and ! can also be used to select variables, see 'Details' in the df.subset function.
key	a numeric or character vector of the answer key with a length matching the number of variables specified in the argument data or selected using the argument ....
exclude	a character vector indicating items to be excluded from the analysis.
na.keep	logical: if FALSE (default), missing values are coded as 0 when scoring items (i.e., item not solved) and creating groups (i.e., answer option not selected).
correct	logical: if TRUE (default), the corrected distractor-total correlation is computed.
method	a character string indicating which correlation coefficient is used for the item-total correlation, i.e., "pbiser" for the point-biserial correlation coefficient when data are dichotomous, "biser" for the biserial correlation coefficient.
ml	logical: if FALSE (default), a two-step approximation is used to compute the biserial correlation coefficient (method = "biser"), while the maximum-likelihood (ML) estimate is computed if TRUE. Note that ML estimation is computationally expensive, i.e., takes a lot of time.
print	a character vector indicating which results to print, i.e., "all" for all results, "nUQ" for the number of unique elements after omitting missing values, "key" for the answer key, "n" for the distractor selection frequency, "perc" for the distractor selection percentage, and "r" for the (corrected) distractor-total correlation.
color	a character string indicating the text color for highlighting the attractor frequency, percentage, and attractor-total correlation, , i.e., "default" (default) for the default text color without color coding and various text colors for highlighting like "red", "b.red", "green", "b.green", "blue", or "b.blue", see the help page of the chr.color function. Note that this option is not supported when using R Markdown and when writing the output into a text file (.txt).
style	a character vector indicating the font style, i.e., "regular" (default) for regular text, "bold" for bold text, and "italic" for italic text. Note that the font style "bold" and "italic" can be combined, i.e., style = c("bold", "italic") provides a bold and italic text. Note that the argument color needs to be specified to change the style of the text, e.g. color = "black" and style = "bold" to for bold text.
na.omit	logical: if TRUE, incomplete cases are removed before conducting the analysis (i.e., listwise deletion).
digits	an integer value indicating the number of decimal places to be used to display descriptive statistics, e.g., mean, median, and standard deviation.
r.digits	an integer value indicating the number of decimal places to be used to display the item difficulty, item-total correlation, and the coefficient alpha if the item is deleted.
as.na	a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis.
write	a character string naming a file for writing the output into either a text file with file extension ".txt" (e.g., "Output.txt") or Excel file with file extension ".xlsx" (e.g., "Output.xlsx"). If the file name does not contain any file extension, an Excel file will be written.
append	logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check	logical: if TRUE (default), argument specification is checked.
output	logical: if TRUE (default), output is shown.

Value

Returns an object of class misty.object, which is a list with following entries:

call	function call
type	type of analysis
data	data frame including all variables used in the analysis
key	list with the answer key and the position of the answer key for each item
args	specification of function arguments
result	result table

Note

This function uses a modified copy of the polyserial() function in the polycor package by John Fox when requesting distractor-total biserial correlation.

Author(s)

Takuya Yanagida

References

Fox, J. (2025). polycor: Polychoric and polyserial correlations. R package version 0.8-2. https://doi.org/10.32614/CRAN.package.polycor

See Also

item.stats, item.alpha, item.omega, item.cfa, item.reverse, item.scores

Examples

## Not run: 

#————————————————————————————————————————————————————————————————————————————
# Multiple-Choice Items

# Answer key
key <- c("D", "B", "C", "C", "B", "B", "B", "A", "A", "D")

# Example 1a: Corrected distractor-total point-biserial correlation
item.distract(data.items, +mitem, key = key)

# Example 1b: Corrected distractor-total biserial correlation
item.distract(data.items, +mitem, key = key, method = "biser")

# Example 1c: Keep missing values, i.e., do not convert NA into 0
item.distract(data.items, +mitem, key = key, na.keep = TRUE)

# Example 1d: Print corrected distractor-total point-biserial correlation only
item.distract(data.items, +mitem, key = key, print = "r")

# Example 1e: Highlight attractor frequency, percentage, and correlation in bright red
item.distract(data.items, +mitem, key = key, na.keep = TRUE, color = "b.red")

# Example 1f: Highlight attractor frequency, percentage, and correlation in boldface
item.distract(data.items, +mitem, key = key, na.keep = TRUE, color = "black",
              style = "bold")

#————————————————————————————————————————————————————————————————————————————
# Write Results

# Example 2a: Write Results into a text file
item.distract(data.items, +mitem, key = key, write = "Item-Distract.txt", output = FALSE)

# Example 2b: Write Results into an Excel file
item.distract(data.items, +mitem, key = key, write = "Item-Distracts.xlsx", output = FALSE)

## End(Not run)

misty documentation built on Aug. 2, 2026, 9:06 a.m.