plotlsirm (version 0.1.3)

itemsimilarity: Similarity profile for a focal item

Description

Plots the similarity between one focal item and every other item in latent space, optionally including posterior uncertainty bands when a list of draws is supplied. Similarity is defined as $$\exp(-\gamma\,d_{ij})$$ where \(d_{ij}\) is the Euclidean distance between items i and j. Bars can be color-coded by a grouping factor, reordered by decreasing similarity, displayed horizontally or vertically, and annotated with credible intervals.

Usage

itemsimilarity(
  w,
  focal_item,
  gamma = 1,
  item_group = NULL,
  item_names = NULL,
  ci_level = 0.95,
  reorder = FALSE,
  vertical = TRUE,
  title = NULL,
  use_gradient = TRUE,
  gradient_low = "#d9f0d3",
  gradient_high = "#1b7837",
  show_gradient_legend = TRUE,
  single_fill_color = "steelblue"
)

Value

(Invisibly) a ggplot object. The plot is also drawn as a side effect.

Arguments

w

Numeric matrix (\(I \times d\)) of item coordinates or a list of such matrices (posterior draws). When a list is given the function summarises similarity across draws and plots medians with ci_level credible intervals.

focal_item

Index (integer) or name (character) of the item whose similarity profile is to be displayed.

gamma

Positive numeric scalar controlling how quickly similarity decays with distance. Default is 1.

item_group

Optional character/factor vector of length I indicating group membership for each item. Used for bar colors and legend.

item_names

Optional character vector of item labels (length I). Defaults to "I1", "I2", ... if NULL.

ci_level

Numeric between 0 and 1 giving the width of the credible interval when w is a posterior list. Ignored for a single draw.

reorder

Logical. Reorder items on the axis by decreasing similarity to the focal item? Default FALSE.

vertical

Logical. TRUE (default) plots vertical bars; FALSE flips the axes for a horizontal layout.

title

Optional character string added as the plot title.

use_gradient

Logical. When item_group is NULL, color bars by a similarity gradient (low->high). Default TRUE.

gradient_low, gradient_high

Colors for the similarity gradient when use_gradient = TRUE. Defaults "#d9f0d3" (low) to "#1b7837" (high).

show_gradient_legend

Logical. Show legend for the similarity gradient (only when item_group is NULL and use_gradient = TRUE)? Default TRUE.

single_fill_color

Single fill color when use_gradient = FALSE and item_group is NULL. Default "steelblue".

Examples

set.seed(1)
w  <- matrix(rnorm(40), ncol = 2)   # 20 items
gp <- sample(c("Math", "Verbal"), nrow(w), replace = TRUE)

## 1) Single estimate, default gradient (ungrouped)
itemsimilarity(w, focal_item = 3, gamma = 2,
               title = "Similarity to item 3 (gradient)")

## 2) Single estimate, turn off gradient and use one color (ungrouped)
itemsimilarity(w, focal_item = 3, gamma = 2,
               use_gradient = FALSE, single_fill_color = "tomato",
               title = "Similarity to item 3 (single color)")

## 3) Grouped bars (gradient ignored because groups are used)
itemsimilarity(w, focal_item = 3, gamma = 2, item_group = gp,
               title = "Similarity to item 3 (grouped)")

## 4) Posterior list with credible intervals (ungrouped, gradient)
draws <- replicate(100, w + matrix(rnorm(length(w), sd = 0.1),
                                   nrow(w), ncol(w)), simplify = FALSE)
itemsimilarity(draws, focal_item = "I10", ci_level = 0.9,
               vertical = FALSE, show_gradient_legend = FALSE)