plot_distractor_icc {irt}

Plot Empirical Item or Test characteristic curve

Description

plot_empirical_icc plots empirical item or test characteristic curve.

Usage

plot_distractor_icc(
  raw_resp,
  item,
  key = NULL,
  ip = NULL,
  criterion = NULL,
  bins = 10,
  x_axis_scale = NULL,
  add_icc = FALSE,
  title = "",
  n_dodge = 1,
  x_lim = NULL,
  base_r_graph = FALSE,
  suppress_plot = FALSE,
  ...
)

Arguments

raw_resp

Raw response matrix.

item

The column number, column name or the 'ID' of the the item that should be plotted.

key

A vector of answer key. If key = NULL, the function will check whether the item pool has keys by checking ip$key and raise an error if ip$key is not valid.

ip

An Itempool-class object that is needed for some plots. If ip provided and criterion is not provided, then ability will be estimated using EAP method with prior mean 0 and prior standard deviation of 1. This is a slower method depending on the size of the data. Also, the key for items can be provided via ip$key.

criterion

A vector of examinee abilities. If criterion values provided the bins are formed using them instead of sum scores.

bins

An integer larger than 2 representing of ability groups examinees should be grouped into. The default is 10. The maximum value of bins + 1 is the number of possible total scores.

x_axis_scale

Set the scale of the x-axis. The default value is NULL. For if sum score is used scale will be defaulted to "percent", Otherwise if valid criterion or ip arguments provided the scale defaults to "criterion".

"percent"

Percent interval.

"number"

Numbers between 1 and bins.

"criterion"

Criterion values equally divided into bins. the middle value of the bin is shown in the x-axis. For example, if bins = 10, the first tick of the x-axis will be the mean of minimum criterion value and tenth percentile criterion value.

add_icc

If TRUE, adds item characteristic curve to the plot. Only available if a valid item pool object (ip) is provided and x_axis_scale = "criterion". The default value is FALSE.

title

Title of the plot. If the value is NULL, the plot title will be suppressed.

n_dodge

The number of lines the x-axis tick labels should be written to. This is especially useful if the x-axis tick labels overlap with each other. The default value is 1, which means all of the labels are written on the same line.

x_lim

The limits of x axis in the form c(-4, 4). Only available when x_axis_scale = "criterion". The default value is NULL where the limits will be the minimum and maximum 'criterion' values.

base_r_graph

If TRUE function will plot graphs using base R graphics. If FALSE the function will check whether 'ggplot2' package is installed. If it is installed, it will use 'ggplot2' package for the plot. The default value is FALSE.

suppress_plot

If FALSE the function will print the plot. If TRUE, function will return the plot object. Default value is FALSE.

...

Extra parameters that will pass to geom_line.

Value

Depending on the value of suppress_plot function either prints the proportion of examinees in each bin respond to each distractor or returns the plot object.

Author(s)

Emre Gonulates

Examples

n_item <- 10 # sample(8:12, 1)
n_theta <- 10000 # sample(100:200, 1)
raw_resp <- matrix(sample(LETTERS[1:4], n_item * n_theta, replace = TRUE),
                   nrow = n_theta, ncol = n_item,
                   dimnames = list(paste0("Examinee-", 1:n_theta),
                                   paste0("Item_", 1:n_item)))
key <- sample(LETTERS[1:4], n_item, replace = TRUE)
plot_distractor_icc(raw_resp, 3, key)
# Change the number of bins
plot_distractor_icc(raw_resp, 3, key, bins = 15)