plot.traceline: Plot ICC and TCC

Description

This function plots item or test characteristic curve using the ggplot2 package. The item characteristic (or category) curve (ICC) or item score curve is drawn for an individual item. The test characteristic curve (TCC) is drawn based on a total test form.

Usage

# S3 method for traceline
plot(
  x,
  item.loc = NULL,
  score.curve = FALSE,
  overlap = FALSE,
  layout.col = 2,
  xlab.text,
  ylab.text,
  main.text,
  lab.size = 15,
  main.size = 15,
  axis.size = 15,
  line.color,
  line.size = 1,
  strip.size = 12,
  ...
)

Arguments

x: An object of class traceline.
item.loc: A numeric value indicating that the nth item (or the location of item) is plotted. If NULL, the TCC based on a total test form is drawn. Default is NULL.
score.curve: Logical value. If TRUE, item score curve (i.e., a weighted sum of item category probabilities over the item scores) is plotted in a panel. Otherwise, ICCs for all score categories are plotted in separate panels. For a dichotomous item, the item score curve is the same as the ICC of score category 1. Ignored when item.loc = NULL. Default is FALSE.
overlap: Logical value indicating whether multiple item score curves are plotted in one panel. If FALSE, the multiple item score curves are displayed with multiple panels, one for each.
layout.col: An integer value indicating the number of columns in the panel when displaying ICCs for an item or when displaying multiple item scores with multiple panels.
xlab.text, ylab.text: A title for the x and y axes.
main.text: An overall title for the plot.
lab.size: The size of xlab and ylab. Default is 15.
main.size: The size of main.text. Default is 15.
axis.size: The size of labels along the x and y axes. Default is 15.
line.color: A character string specifying the color for a line. See http://www.cookbook-r.com/Graphs/Colors_(ggplot2)/ for more details about colors used in ggplot2.
line.size: The size of lines. Default is 1.
strip.size: The size of facet labels when ICCs for an item are plotted.
...: Further arguments passed from the function geom_line() in the ggplot2 package.

Author

Hwanggyu Lim hglim83@gmail.com

Details

All of the plots are drawn using the ggplot2 package. If item.loc = NULL, the TCC based on the total test form is plotted. In the argument item.loc, a vector of positive integer values should be specified to indicate the nth items among the total test form. For example, if there are ten items in the test form and the score curves of the 1st, 2nd, and 3rd items should be plotted, then item.loc = 1:3.

Examples

Run this code

## example
## using a "-prm.txt" file obtained from a flexMIRT
# import the "-prm.txt" output file from flexMIRT
flex_prm <- system.file("extdata", "flexmirt_sample-prm.txt", package = "irtplay")

# read item parameters and transform them to item metadata
test_flex <- bring.flexmirt(file=flex_prm, "par")$Group1$full_df

# set theta values
theta <- seq(-3, 3, 0.1)

# compute the item category probabilities and item/test
# characteristic functions given the theta values
x <- traceline(x=test_flex, theta, D=1)

# plot TCC based on the total test form
plot(x, item.loc=NULL)

# plot ICCs for the first item (dichotomous item)
plot(x, item.loc=1, score.curve=FALSE, layout.col=2)

# plot item score curve for the first item (dichotomous item)
plot(x, item.loc=1, score.curve=TRUE)

# plot item score curves for the first six dichotomous items
# with multiple panels 
plot(x, item.loc=1:6, score.curve=TRUE, overlap=FALSE)

# plot item score curve for the first six dichotomous items
# in one panel
plot(x, item.loc=1:6, score.curve=TRUE, overlap=TRUE)

# plot ICCs for the last item (polytomous item)
plot(x, item.loc=55, score.curve=FALSE, layout.col=2)

# plot item score curve for the last item (polytomous item)
plot(x, item.loc=55, score.curve=TRUE)

# plot item score curves for the last three polytomous items
# with multiple panels
plot(x, item.loc=53:55, score.curve=TRUE, overlap=FALSE)

# plot item score curves for the last three poltyomous items
# in one panel
plot(x, item.loc=53:55, score.curve=TRUE, overlap=TRUE)