plotlsirm (version 0.1.3)

strengthplot: Item-strength profile for a single person

Description

For a chosen respondent (person_index) this function plots the strength (likelihood of endorsement) for every item, defined as $$\exp(-\gamma d_{ij})$$, where \(d_{ij}\) is the Euclidean distance between the person's latent position \(z_j\) and each item position \(w_i\). When z and w are supplied as lists of matrices (posterior draws), the function summarizes the distribution of strengths with medians and a ci_level credible interval. Bars can be colored by an item grouping factor, reordered by decreasing strength, and displayed either vertically or horizontally.

Usage

strengthplot(
  z,
  w,
  person_index,
  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 containing the bar plot. The plot is also printed.

Arguments

z

A numeric matrix (\(N \times d\)) of person coordinates or a list of such matrices representing posterior draws.

w

A numeric matrix (\(I \times d\)) of item coordinates or a list of such matrices, matching the structure of z.

person_index

Integer giving the row of z (or each draw in z) corresponding to the focal respondent.

gamma

Positive numeric scalar controlling the decay of strength with distance; default is 1.

item_group

Optional character/factor vector of length I assigning each item to a group for color coding and legend.

item_names

Optional character vector of item labels. If NULL defaults to "I1", "I2",...

ci_level

Width of the credible interval (between 0 and 1) when posterior draws are given. Ignored for a single point estimate.

reorder

Logical. Reorder items on the axis by decreasing strength? Default FALSE.

vertical

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

title

Optional character string to appear as the plot title.

use_gradient

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

gradient_low, gradient_high

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

show_gradient_legend

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

single_fill_color

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

Details

When no item_group is provided, bars are color-mapped by a similarity gradient (low -> high) by default. You can disable this behavior and use a single fill color instead via use_gradient = FALSE.

Examples

set.seed(1)
z  <- matrix(rnorm(40), ncol = 2)   # 20 persons
w  <- matrix(rnorm(30), ncol = 2)   # 15 items

## 1) Point-estimate strengths for person 5 (default gradient, ungrouped)
strengthplot(z, w, person_index = 5, gamma = 2,
             title = "Strengths for person 5 (gradient)")

## 2) Turn off gradient and use a single color
strengthplot(z, w, person_index = 5, gamma = 2,
             use_gradient = FALSE, single_fill_color = "tomato",
             title = "Strengths for person 5 (single color)")

## 3) Posterior example with credible intervals and item groups
draws_z <- replicate(50, z + matrix(rnorm(length(z), sd = 0.1),
                                    nrow(z), ncol(z)), simplify = FALSE)
draws_w <- replicate(50, w + matrix(rnorm(length(w), sd = 0.1),
                                    nrow(w), ncol(w)), simplify = FALSE)
grp <- rep(c("Core", "Peripheral"), length.out = nrow(w))
strengthplot(draws_z, draws_w, person_index = 3,
             item_group = grp, ci_level = 0.9, vertical = FALSE,
             title = "Posterior strength profile for respondent 3")