item.side: Wright Map Item Sides

Description

Draw the item side of a Wright Map in a variety of styles. Intended to be primarily called by wrightMap, but also available for use on their own.

Usage

itemModern(thr, yRange = NULL, axis.items = "Items", show.thr.sym = TRUE
, thr.sym.cex = 0.8, thr.sym.lwd = 1, thr.sym.pch = 23
, thr.sym.col.fg = rgb(0, 0, 0, 0.3), thr.sym.col.bg = rgb(0, 0, 0, 0.3)
, show.thr.lab = TRUE, thr.lab.pos = c(2, 4), thr.lab.text = NULL
, thr.lab.type = NULL, thr.lab.col = "black", thr.lab.cex = 0.5
, thr.lab.font = 2, label.items.rows = 1
, label.items.srt = 0, label.items = NULL, label.items.cex = 0.6
, label.items.ticks = TRUE, axis.logits = "Logits", show.axis.logits = "R"
, axis.logits.cex = 0.7, oma = c(0, 0, 0, 3), cutpoints = NULL
, vertLines = FALSE, vertLines.par = list(), cutpoints.par = list()
, thr.sym.par = list(), thr.lab.par = list(), label.items.par = list()
, axis.logits.par = list(), logits.text.par = list(), ...)
itemClassic(thr, yRange = NULL, axis.items = "Items", axis.logits = "Logits"
, show.axis.logits = "R", axis.logits.cex = 0.7, oma = c(0, 0, 0, 3)
, cutpoints = NULL, cutpoints.par = list(), label.items = NULL, label.steps = NULL
, label.steps.type = NULL, label.sep = ".", thr.lab.sep = " | "
, thr.lab.par = list(), axis.logits.par = list()
, logits.text.par = list(), pad.char = "_", font.family = "mono", ...)
itemHist(thr, yRange = NULL, axis.items = "Items", axis.logits = "Logits"
, show.axis.logits = "R", axis.logits.cex = 0.7, oma = c(0, 0, 0, 3)
, cutpoints = NULL, axis.logits.par = list(), logits.text.par = list()
, cutpoints.par = list(), ...)

Arguments

General arguments:

thr: A vector or matrix of threshold parameters. If a matrix, items should be in rows and steps in columns.
yRange: A vector with 2 elements specifying the lower and upper limits of the plot's y-axis.
label.items: A vector of strings representing the item labels used in itemModern and itemClassic
axis.items: The title of the x-axis.
axis.logits: The title of the y-axis.
axis.logits.cex: The size of the logit values on the y-axis.
show.axis.logits: If set to "R" or "L", draws a logit axis on the right or left. Will also draw an axis on the right if the value is TRUE. If any other value, the axis is not drawn.
oma: Values to use for the oma parameter (see par).
cutpoints: Values at which to draw horizontal lines (see cutLines).
label.items.par: A list of parameters to further customize item labels.
axis.logits.par: A list of parameters for customizing the logit axis.
logits.text.par: A list of parameters for customizing the logit axis text.
...: Additional arguments passed to cutLines.

Specific to itemModern:

show.thr.sym: Logical. If TRUE (default), the plot will show symbols for the item thresholds.
thr.sym.cex: An integer, vector, or matrix of numerical values indicating the magnification of the threshold symbols.
thr.sym.lwd: An integer, vector, or matrix of positive numbers specifying the width of the lines used in the threshold symbols.
thr.sym.pch: An integer, vector, or matrix specifying a symbol or single character used to represent item thresholds.
thr.sym.col.fg: An integer, vector, or matrix of numerical values indicating the foreground color for the threshold symbols.
thr.sym.col.bg: An integer, vector, or matrix of numerical values indicating the background color for the threshold symbols.
show.thr.lab: Logical. If TRUE (default), the plot will show labels for the item thresholds.
thr.lab.pos: An integer, vector, or matrix indicating the position for displaying the threshold labels. Values 1, 2, 3, and 4 indicate below, left, above, and right, respectively.
thr.lab.text: A matrix containing the text labels for the item thresholds, where each row represents an item, and each column represents a level. If not provided, defaults to the column names of thr if they exist, or simple numeric labels (1, 2, 3, etc.) otherwise. Use thr.lab.type = "transition" for category transition labels when no column names exist.
thr.lab.type: Optional string to control default threshold label format when thr.lab.text is not provided and the threshold matrix has no column names. Set to "transition" to use category transition labels (0/1, 1/2, 2/3, etc.). Default is NULL which uses simple numeric labels (1, 2, 3, etc.). Note: Column names take precedence over thr.lab.type.
thr.lab.col: A matrix specifying the color for each threshold label.
thr.lab.cex: A numerical value indicating the magnification factor for the threshold labels.
thr.lab.font: An integer or matrix specifying the font type for the threshold labels. 1 = plain, 2 = bold, 3 = italic, 4 = bold italic.
label.items.rows: An integer specifying the number of rows used to display the item labels (default: 1). Useful when item labels overlap.
label.items.srt: Angle of rotation for item labels. Only applicable if label.items.rows is set to 1.
label.items.cex: A numerical value specifying the magnification factor for the item labels.
label.items.ticks: Logical. If TRUE (default), ticks are drawn on the x-axis for the item side.
vertLines: Logical. If TRUE, vertical lines are drawn to mark all symbols associated with an item.
vertLines.par: A list of parameters (e.g., col, lwd, lty) to control the appearance of the vertical lines.
cutpoints.par: A list of parameters (e.g., col, lwd, lty) to customize the cutpoint lines.
thr.sym.par: A list of parameters to further customize threshold symbols.
thr.lab.par: A list of parameters to further customize threshold labels.

Specific to itemClassic:

label.steps: A vector specifying the labels for the threshold steps. If not provided, defaults to simple numeric labels (1, 2, 3, etc.). Set to TRUE to use column names from thr if available. Use label.steps.type = "transition" for category transition labels.
label.steps.type: Optional string to control default step label format when label.steps is not provided. Set to "transition" to use category transition labels (0/1, 1/2, 2/3, etc.). Default is NULL which uses simple numeric labels (1, 2, 3, etc.).
label.sep: A string indicating the separator used between item labels and step labels.
thr.lab.sep: A string indicating the separator used between threshold labels for different items.
pad.char: A character used to pad item labels to a fixed width.
font.family: A string specifying the font family for the item labels (default: mono).

Author

Rebecca Freund and David Torres Irribarra

Details

These functions are designed as helper functions for wrightMap to draw the item side of a map. When called outside of that function, they can be used to create more customized maps. Possible uses include:

Draw an item map on its own.
Compare two item maps in a single figure.
Draw a Wright Map with the item side on the left and the person side on the right.

Examples

Run this code


#As a call from wrightMap:

## Mock results
uni.proficiency <- rnorm(1000, mean =  -0.5, sd = 1)

items.loc <- sort(rnorm(20))
thresholds <- data.frame(
  l1 = items.loc - 0.5,
  l2 = items.loc - 0.25,
  l3 = items.loc + 0.25,
  l4 = items.loc + 0.5
)

## Setting up labels, colors, and symbols
thresholds.labels <- data.frame(
  l1 = paste('Lev', rep(1, 20), sep = ''),
  l2 = paste('Lev', rep(2, 20), sep = ''),
  l3 = paste('Lev', rep(3, 20), sep = ''),
  l4 = paste('Lev', rep(4, 20), sep = '')
)

thresholds.colors <- data.frame(
  l1 = rep('green', 20),
  l2 = rep('red', 20),
  l3 = rep('yellow', 20),
  l4 = rep('blue', 20)
)

thresholds.symbols <- data.frame(
  l1 = rep(15, 20),
  l2 = rep(16, 20),
  l3 = rep(17, 20),
  l4 = rep(18, 20)
)

wrightMap(uni.proficiency, thresholds,
  thr.lab.text = thresholds.labels,
  thr.lab.col = as.vector(as.matrix(thresholds.colors)),
  thr.sym.pch = thresholds.symbols
)

# Direct call:

## Plotting results of a unidimensional Rating Scale Model
## Default labels are 1, 2, 3, etc.
items.loc <- sort(rnorm(20))
thresholds <- cbind(
  items.loc - 0.5,
  items.loc - 0.25,
  items.loc + 0.25,
  items.loc + 0.5
)
rownames(thresholds) <- paste0("Item", 1:20)

itemModern(thresholds)  # Default: 1, 2, 3, 4
itemModern(thresholds, thr.lab.type = "transition")  # Transition: 0/1, 1/2, 2/3, 3/4

itemClassic(thresholds)  # Default: 1, 2, 3, 4
itemClassic(thresholds, label.steps.type = "transition")  # Transition: 0/1, 1/2, 2/3, 3/4

itemHist(thresholds)