% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{plot_dif_heatmap}
\alias{plot_dif_heatmap}
\title{Plot a differential-functioning heatmap}
\usage{
plot_dif_heatmap(
  x,
  metric = c("obs_exp", "t", "contrast"),
  draw = TRUE,
  show_values = TRUE,
  value_digits = 2L,
  flag_threshold = NULL,
  scale_limit = NULL,
  flag_color = "black",
  ...
)
}
\arguments{
\item{x}{Output from \code{\link[=dif_interaction_table]{dif_interaction_table()}}, \code{\link[=analyze_dff]{analyze_dff()}}, or
\code{\link[=analyze_dif]{analyze_dif()}}. When an \code{mfrm_dff}/\code{mfrm_dif} object is passed,
the \code{cell_table} element
is used (requires \code{method = "residual"}).}

\item{metric}{Which metric to plot: \code{"obs_exp"} for observed-minus-expected
average (default), \code{"t"} for the standardized residual / t-statistic,
or \code{"contrast"} for pairwise differential-functioning contrast (only for \code{mfrm_dff}
objects with \code{dif_table}).}

\item{draw}{If \code{TRUE} (default), draw the plot.}

\item{show_values}{Logical. If \code{TRUE} (default), print rounded cell values
on top of the heatmap.}

\item{value_digits}{Non-negative integer number of digits after the decimal
point for cell labels.}

\item{flag_threshold}{Optional non-negative absolute-value threshold. When
supplied, cells with \code{abs(value) >= flag_threshold} are recorded in
\verb{$data$flag_matrix} and outlined on the drawn heatmap.}

\item{scale_limit}{Optional positive scalar for a symmetric color scale
from \code{-scale_limit} to \code{+scale_limit}. Use this to make several heatmaps
visually comparable.}

\item{flag_color}{Border color for cells meeting \code{flag_threshold}.}

\item{...}{Additional graphical parameters passed to \code{\link[graphics:image]{graphics::image()}}.}
}
\value{
Invisibly, an \code{mfrm_plot_data} object whose \code{data} slot bundles
the row x column metric matrix (\verb{$matrix}), the source long table
(\verb{$pairs}), and the metric label. Earlier 0.1.x releases returned the
bare matrix; consume \verb{$data$matrix} to keep code forward-compatible.
}
\description{
Visualizes the interaction between a facet and a grouping variable
as a heatmap. Rows represent facet levels, columns represent group
values, and cell color indicates the selected metric.
}
\section{Interpreting output}{

\itemize{
\item Warm colors (red) indicate positive Obs-Exp values (the model
underestimates the facet level for that group).
\item Cool colors (blue) indicate negative Obs-Exp values (the model
overestimates).
\item White/neutral indicates no systematic difference.
\item The \code{"contrast"} view is best for pairwise differential-functioning
summaries, whereas
\code{"obs_exp"} and \code{"t"} are best for cell-level diagnostics.
}
}

\section{Typical workflow}{

\enumerate{
\item Compute interaction with \code{\link[=dif_interaction_table]{dif_interaction_table()}} or differential-
functioning contrasts with \code{\link[=analyze_dff]{analyze_dff()}}.
\item Plot with \code{plot_dif_heatmap(...)}.
\item Identify extreme cells or contrasts for follow-up.
}
}

\examples{
toy <- load_mfrmr_data("example_bias")

fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
int <- dif_interaction_table(fit, diag, facet = "Rater",
                             group = "Group", data = toy, min_obs = 2)
heat <- plot_dif_heatmap(int, metric = "obs_exp", draw = FALSE)
dim(heat$data$matrix)
# Look for (`metric = "obs_exp"`): cells near 0 are aligned with
#   model expectation; |Obs - Exp| > 0.5 logits is a substantive
#   gap. With `metric = "t"` the cell scale becomes a standardized
#   residual where |t| > 2 is a screening flag, not a standalone
#   hypothesis test. With `metric = "contrast"` the layout switches
#   to Level x GroupPair and reads as the pairwise differential-
#   functioning contrast (use `analyze_dff()`).
}
\seealso{
\code{\link[=dif_interaction_table]{dif_interaction_table()}}, \code{\link[=analyze_dff]{analyze_dff()}}, \code{\link[=analyze_dif]{analyze_dif()}}, \code{\link[=dif_report]{dif_report()}}
}
