plotlsirm (version 0.1.3)

pip_fountain: Posterior Interaction Profile - Fountain style

Description

Generates the fountain variant of a Posterior Interaction Profile (PIP) plot. The layout is identical to pip_waterfall() on the left (posterior density for the focal respondent's ability) but inverts the right-hand panel: each item dot is placed at - \(\beta_i\) (the "fountain base") and an arrow rises to the personalized easiness $$\delta_{ij} = \beta_i - d_{ij}$$. Distance is 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 that extend above the base indicate the item is easier for the respondent than average; arrows that fall short indicate it is harder.

Usage

pip_fountain(
  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 the combined left- and right-hand ggplot2 panels. The plot is automatically displayed; the value is returned invisibly for further tweaking.

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_{ij}\) 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) providing lower/upper posterior intervals (e.g., 95% HDI) for each respondent's \(\alpha_j\). The focal respondent's band is shaded.

distance_low, distance_up

Optional matrices matching distance_mat that give lower/upper HDI bounds for each distance. When both are supplied, dotted vertical lines depict the uncertainty in every personalized easiness.

item_group

Optional character/factor vector of length I defining item groupings. Enables color coding and a legend.

focal_id

Integer (1 \(\le\) focal_id \(\le\) \(N\)) selecting the respondent to highlight. Defaults to the first row.

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_waterfall() for the alternative "waterfall" framing, and interprofile() for a wrapper that switches between the two.

Examples

# Small simulated example -----------------------------------------
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

# Plain fountain plot for respondent 2
pip_fountain(alpha, beta, gamma = 1.5, dist, focal_id = 2)

# Fountain plot with item groups and uncertainty intervals
grp <- rep(c("MCQ", "Essay"), length.out = I)
d_lo <- pmax(dist - 0.2, 0);  d_up <- dist + 0.2
a_lo <- alpha - 0.3; a_up <- alpha + 0.3
pip_fountain(alpha, beta, gamma = 1, dist,
             alpha_lower = a_lo, alpha_upper = a_up,
             distance_low = d_lo, distance_up = d_up,
             item_group = grp, focal_id = 4)