plotlsirm (version 0.1.3)

iccsurface: Latent-Space Item Characteristic Surface

Description

Evaluates the LSIRM probability $$P(Y_{pi}=1)=\operatorname{logit}^{-1}\!\bigl(\alpha+\beta-\gamma\,d\bigr)$$ on a rectangular grid of ability (\(\alpha\)) and person-item distance (\(d\)) values and, by default, renders the resulting surface interactively with plotly.

Usage

iccsurface(
  beta,
  alpha_lim = c(-4, 4),
  n_alpha = 60,
  dist_lim = c(0, 4),
  n_dist = 60,
  gamma = 1,
  colour_mode = c("uniform", "gradient"),
  surface_col = "steelblue",
  palette = "Viridis",
  dark_high = TRUE,
  surface_opacity = NULL,
  show_grid = TRUE,
  grid_step = 5,
  plot = TRUE
)

Value

• plot = TRUE - a plotly htmlwidget (prints automatically).

• plot = FALSE - a list with components alpha, distance, and prob (an \(n_{\alpha} \times n_{\mathrm{dist}}\) matrix of probabilities).

Arguments

beta

Numeric scalar \(\beta_i\) shifting the surface along the probability axis (item "easiness").

alpha_lim, n_alpha

Numeric. Range c(min, max) and grid size for the ability axis. Default is \(\alpha\in[-4,4]\) with 60 points.

dist_lim, n_dist

Numeric. Range c(min, max) and grid size for the distance axis. Default is \(d\in[0,4]\) with 60 points.

gamma

Positive scalar controlling how strongly the probability decays with distance.

colour_mode

"uniform" (default) or "gradient".

surface_col

Single colour used when colour_mode = "uniform".

palette

Character name of a plotly continuous palette (e.g. "Viridis", "Hot", "Blues"); only used when colour_mode = "gradient".

dark_high

Logical. If TRUE (default) reverses the palette so high probabilities map to darker shades.

surface_opacity

Numeric in (0, 1]. By default the function chooses 1 for uniform and 0.9 for gradient surfaces so the wire-frame remains visible.

show_grid

Logical. Overlay a wire-frame? Default TRUE.

grid_step

Positive integer: draw every grid_step-th row/column when show_grid = TRUE.

plot

Logical. If TRUE (default) return an interactive plotly surface; if FALSE return the raw numeric grid.

Dependencies

Rendering the surface requires the plotly package (install.packages("plotly")). No external packages are needed when plot = FALSE.

Details

Colour options

• Uniform - a single-colour surface (colour_mode = "uniform", default). The colour is set by surface_col.

• Gradient - a continuous plotly palette (colour_mode = "gradient"); the palette is chosen via palette, and dark_high = TRUE reverses the scale so higher probabilities appear darker.

Wire-frame

Setting show_grid = TRUE overlays a black wire-frame every grid_step rows/columns to emphasise the surface curvature.

The scene's aspect is fixed to a cube, and bold zero-lines are drawn on the \(\alpha\)- and distance axes so their origins align visually.

Examples

## Numeric output only
surf <- iccsurface(beta = 0, n_alpha = 21, n_dist = 21, plot = FALSE)
str(surf)

# \donttest{
## Interactive surfaces
## 1. Uniform single-colour
iccsurface(beta = -0.5)

## 2. Gradient "Hot" palette, darker = high P
iccsurface(beta = 0.3,
           colour_mode = "gradient",
           palette     = "Hot")
# }