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.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.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.
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.
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
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
)

itemModern(thresholds)
itemClassic(thresholds)
itemHist(thresholds)