plot_rs_heatmap: Plot Item-Level Response Shift Heatmap

In grmtree: Recursive Partitioning for Graded Response Models

Plot Item-Level Response Shift Heatmap

Description

Creates a standalone heatmap showing RS type for each item across all terminal nodes. Significant items are filled with RS-type colors; non-significant items are white/light gray.

Usage

plot_rs_heatmap(
  rs,
  item_labels = NULL,
  node_labels = NULL,
  show_chi2 = FALSE,
  title = NULL,
  ...
)

Arguments

rs	An rs_characterization object from rs_characterize.
item_labels	Optional character vector of item labels. If NULL, uses "Item 1", "Item 2", etc.
node_labels	Optional character vector of node labels. If NULL, uses "Node X (n=Y)" from the global results.
show_chi2	Logical. If TRUE, display chi-squared values inside cells. Default is FALSE.
title	Optional plot title. If NULL, uses a default title.
...	Additional arguments (unused).

Details

The heatmap uses the following color coding:

Blue

Recalibration (threshold change)

Red/Orange

Reprioritization (discrimination change)

Purple

Both recalibration and reprioritization

Light orange

Significant but small effect

White

Not significant or not tested

Cells with significant RS (after p-value adjustment) are marked with an asterisk (*). The omnibus RS result for each node is displayed at the top of each column.

Value

Invisibly returns the rs object. Called for its side effect of producing a plot.

Examples

library(grmtree)

# Load the synthetic longitudinal data
data("grmtree_long_data", package = "grmtree")

  # Prepare the wide-format response matrix
  items_t1 <- c("MOS_Listen", "MOS_Info", "MOS_Advice_Crisis", "MOS_Confide",
                "MOS_Advice_Want", "MOS_Fears", "MOS_Personal", "MOS_Understand")
  ld <- prepare_longitudinal_data(
    data = grmtree_long_data,
    items_t1 = items_t1,
    items_t2 = paste0(items_t1, "_year1"),
    covariates = c("sex", "age", "residency", "job",
                   "education", "comorbidity_count", "ever_smoker")
  )

  # Phase 1: fit the longitudinal GRM tree
  ltree <- longitudinal_grmtree(
    resp_wide ~ sex + age + residency + job +
      education + comorbidity_count + ever_smoker,
    data = ld, n_items = 8,
    control = grmtree.control(minbucket = 200)
  )

  # Phase 2: characterize response shift within each subgroup
  rs <- rs_characterize(ltree, p_adjust = "fdr",
    global_p_adjust = "bonferroni")

  # Basic heatmap
  plot_rs_heatmap(rs)

  # With custom labels
  plot_rs_heatmap(rs,
    item_labels = c("Listen", "Info", "Crisis", "Confide",
      "Advice", "Fears", "Personal", "Understand"))

  # Show chi-squared values
  plot_rs_heatmap(rs, show_chi2 = TRUE)

grmtree documentation built on Sept. 2, 2026, 1:07 a.m.