plotlsirm (version 0.1.3)

pip_waterfall: Posterior Interaction Profile - Waterfall style

Description

Creates the waterfall flavour of a Posterior Interaction Profile (PIP) plot, visualizing how a single respondent's latent position (\(\alpha_p\)) interacts with every item. The left panel shows the posterior density (and optional HDI) of the chosen respondent's ability. The right panel ("waterfall") plots each item's easiness \(\beta_i\) as the starting point of a vertical arrow whose tip marks the personalized easiness \(\delta_{ij} = \beta_i - d_{ij}\), where \(d_{ij}\) is the latent distance taken from distance_mat. If gamma is supplied, distances are scaled before computing deltas, i.e. \(\delta_{ij} = \beta_i - \gamma d_{ij}\). Uncertainty bounds in distance_low/distance_up are scaled by the same \(\gamma\). Arrows pointing up indicate the Arrows pointing up indicate the item is easier for the focal respondent than for the average person, whereas arrows pointing down indicate it is harder.

Usage

pip_waterfall(
  alpha,
  beta,
  distance_mat,
  gamma = NULL,
  alpha_lower = NULL,
  alpha_upper = NULL,
  distance_low = NULL,
  distance_up = NULL,
  item_group = NULL,
  focal_id = 1,
  density_adjust = 2,
  y_limits = NULL
)

Value

A patchwork object containing two ggplot2 panels. The plot is also displayed as a side effect, so the returned object is mainly for further customization.

Arguments

alpha

Numeric vector of length N. Posterior means (or draws) of person ability parameters.

beta

Numeric vector of length I. Posterior means of item easiness parameters.

distance_mat

Numeric matrix \(N \times I\) containing the latent distances \(d_{pi}\) between persons and items.

gamma

Optional numeric scalar used to multiplicatively rescale all distances (and distance_low/distance_up, if provided) before computing personalized easiness. Defaults to NULL (no rescaling).

alpha_lower, alpha_upper

Optional numeric vectors (length N) giving lower/upper bounds (e.g., 95% HDI) for each person's \(\alpha_j\). If provided, the focal respondent's interval is shaded in pink.

distance_low, distance_up

Optional matrices the same size as distance_mat providing lower/upper HDI bounds for the distances. When both are supplied, dotted lines visualize the uncertainty in each personalised easiness.

item_group

Optional character/factor vector of length I assigning

focal_id

Integer index (1 \(\le\) focal_id \(\le\) \(N\)) of the respondent to highlight. Default is 1.

density_adjust

Positive numeric scalar passed to ggplot2::geom_density(adjust = ...) to control the smoothness of the left-panel density estimate. Values > 1 increase the bandwidth (smoother curve); values < 1 decrease it (more detail). Default is 2.

y_limits

Optional numeric length-2 vector c(min, max) that fixes the y-axis range for both panels.

See Also

pip_fountain() for the complementary "fountain" layout, and interprofile() for a thin wrapper that chooses between the two styles.

Examples

set.seed(42)
N <- 6; I <- 10
alpha <- rnorm(N)
beta  <- rnorm(I, sd = 0.7)
dist  <- abs(matrix(rnorm(N * I, sd = 0.8), N, I))  # fake distances

# Basic waterfall plot for the first respondent
pip_waterfall(alpha, beta, gamma = 1.5, dist, focal_id = 2)

# Add grouping and uncertainty bands
groups <- rep(c("A", "B"), length.out = I)
d_low  <- dist * 0.9; d_up <- dist * 1.1
a_l   <- alpha - 0.25; a_u <- alpha + 0.25
pip_waterfall(alpha, beta, gamma = 1, dist,
              alpha_lower = a_l, alpha_upper = a_u,
              distance_low = d_low, distance_up = d_up,
              item_group = groups, focal_id = 3)