% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rs_characterize_plots.R
\name{plot_rs_heatmap}
\alias{plot_rs_heatmap}
\title{Plot Item-Level Response Shift Heatmap}
\usage{
plot_rs_heatmap(
  rs,
  item_labels = NULL,
  node_labels = NULL,
  show_chi2 = FALSE,
  title = NULL,
  ...
)
}
\arguments{
\item{rs}{An \code{rs_characterization} object from
\code{\link{rs_characterize}}.}

\item{item_labels}{Optional character vector of item labels.
If NULL, uses "Item 1", "Item 2", etc.}

\item{node_labels}{Optional character vector of node labels.
If NULL, uses "Node X (n=Y)" from the global results.}

\item{show_chi2}{Logical. If TRUE, display chi-squared values inside
cells. Default is FALSE.}

\item{title}{Optional plot title. If NULL, uses a default title.}

\item{...}{Additional arguments (unused).}
}
\value{
Invisibly returns the rs object. Called for its side effect of
producing a plot.
}
\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.
}
\details{
The heatmap uses the following color coding:
\describe{
\item{Blue}{Recalibration (threshold change)}
\item{Red/Orange}{Reprioritization (discrimination change)}
\item{Purple}{Both recalibration and reprioritization}
\item{Light orange}{Significant but small effect}
\item{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.
}
\examples{
\dontshow{if (interactive()) withAutoprint(\{ # examplesIf}
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)
\dontshow{\}) # examplesIf}
}
