plotlsirm (version 0.1.3)

lsirmicc: Latent-Space Item Characteristic Curve (ICC)

Description

Plots the LSIRM ICC for one item on a user-defined grid of ability values (alpha_grid). The function supports two ways of supplying inputs:

Usage

lsirmicc(
  item_id,
  posterior = NULL,
  beta = NULL,
  gamma = NULL,
  w_pos = NULL,
  z_pos = NULL,
  alpha_grid = seq(-4, 4, length.out = 201),
  person_id = NULL,
  compare = TRUE,
  credibleRibbon = FALSE,
  cred_level = 0.95,
  reference = c("item", "person-global", "origin"),
  ref_col = "grey40",
  person_cols = NULL
)

Value

(Invisibly) a ggplot2 object; the plot is displayed as a side-effect.

Arguments

item_id

Scalar index of the item to plot.

posterior

Optional list of draws with components

beta

\(M \times I\) matrix of item intercepts.

gamma

Length-M vector of distance weights.

w

Either an \(M \times I \times D\) array or a length-M list of \(I \times D\) matrices of item coordinates.

z

Optional array/list of person coordinates (same format as w). Only needed if you request person_id or reference = "person-global".

beta, gamma

Numeric point estimates used only when posterior = NULL. beta may be scalar or length-I.

w_pos, z_pos

Matrices of point estimates for item (\(I \times D\)) and person (\(N \times D\)) coordinates, used only when posterior = NULL.

alpha_grid

Numeric vector of ability values (default seq(-4, 4, length.out = 201)).

person_id

NULL (no person curves) or integer vector of respondent indices to overlay.

compare

Logical. If TRUE (default) the reference curve is drawn in addition to any person curves; if FALSE only person curves appear.

credibleRibbon

Logical. Draw the credible ribbon for draws-based inputs? Ignored (forced FALSE) when posterior = NULL. Default FALSE to keep plots uncluttered.

cred_level

Width of the credible ribbon (e.g., 0.95).

reference

One of "item", "origin", or "person-global"; see Details.

ref_col

Colour for the reference curve.

person_cols

Optional vector of colours for person curves; recycled or auto-generated as needed.

Curve types

• Reference curve - distance is computed from the chosen reference position to the item for every posterior draw (or once with point-estimate inputs). Shown unless compare = FALSE.

• Person curve(s) - distance is computed from the latent position(s) of respondent(s) listed in person_id. Requires z (posterior draws or point estimates).

Details

• Point-estimate inputs (default) - leave posterior = NULL and supply deterministic beta, gamma, w_pos, and (if needed) z_pos. A single curve per requested group is drawn (no ribbon).

• Draws-based inputs - supply a posterior list with draws of beta, gamma, w, and optionally z. The plotted curve is the posterior-predictive mean probability at each \(\theta\) (i.e., average over draws). Optionally add a credible ribbon via credibleRibbon = TRUE with width cred_level.

The probability model is

$$P(Y_{ij}=1 \mid \theta_{j}, d_{ij}) = \operatorname{logit}^{-1}\!\bigl(\theta_{j} + \beta_{i} - \gamma\,d_{ij}\bigr)$$

where \(d_{ij} = \lVert z_{j} - w_{i} \rVert\). Choice of the reference position (reference = "item", "origin", or "person-global") determines how \(d_{ij}\) is computed for the baseline (grey) curve.

Examples

## ---- reproducible demonstration ------------------------------------
set.seed(1)
I <- 6; N <- 40; D <- 2; M <- 300           # toy dimensions

## 1. Point-estimate inputs (default) ---------------------------------
beta_hat  <- 0.3
gamma_hat <- 1.2
w_hat     <- matrix(rnorm(I * D), I, D)
z_hat     <- matrix(rnorm(N * D), N, D)

# population curve + one person (no ribbon in point-estimate usage)
lsirmicc(item_id  = 4,
         beta     = beta_hat,
         gamma    = gamma_hat,
         w_pos    = w_hat,
         z_pos    = z_hat,
         person_id = 7)

## 2. Draws-based inputs (posterior list) ------------------------------
w_base <- matrix(0, I, D); w_base[, 1] <- seq(-1.2, 1.2, length.out = I)
z_base <- matrix(0, N, D); z_base[, 1] <- rep(c(-0.6, 0.6), length.out = N)

posterior <- list(
  beta  = matrix(rnorm(M * I, 0, 0.25), M, I),
  gamma = rgamma(M, shape = 300, rate = 300),
  w     = array(rep(w_base, each = M), c(M, I, D)) +
          array(rnorm(M * I * D, sd = 0.12), c(M, I, D)),
  z     = array(rep(z_base, each = M), c(M, N, D)) +
          array(rnorm(M * N * D, sd = 0.12), c(M, N, D))
)

# posterior-predictive mean curve with ribbon and two people
lsirmicc(item_id   = 2,
         posterior = posterior,
         person_id = c(22, 31),
         credibleRibbon = TRUE,
         cred_level = 0.95,
         person_cols = c("red", "blue"))