plot_dif_heatmap: Plot a differential-functioning heatmap

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Plot a differential-functioning heatmap

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.

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

x	Output from dif_interaction_table(), analyze_dff(), or analyze_dif(). When an mfrm_dff/mfrm_dif object is passed, the cell_table element is used (requires method = "residual").
metric	Which metric to plot: "obs_exp" for observed-minus-expected average (default), "t" for the standardized residual / t-statistic, or "contrast" for pairwise differential-functioning contrast (only for mfrm_dff objects with dif_table).
draw	If TRUE (default), draw the plot.
show_values	Logical. If TRUE (default), print rounded cell values on top of the heatmap.
value_digits	Non-negative integer number of digits after the decimal point for cell labels.
flag_threshold	Optional non-negative absolute-value threshold. When supplied, cells with abs(value) >= flag_threshold are recorded in ⁠$data$flag_matrix⁠ and outlined on the drawn heatmap.
scale_limit	Optional positive scalar for a symmetric color scale from -scale_limit to +scale_limit. Use this to make several heatmaps visually comparable.
flag_color	Border color for cells meeting flag_threshold.
...	Additional graphical parameters passed to graphics::image().

Value

Invisibly, an mfrm_plot_data object whose data slot bundles the row x column metric matrix (⁠$matrix⁠), the source long table (⁠$pairs⁠), and the metric label. Earlier 0.1.x releases returned the bare matrix; consume ⁠$data$matrix⁠ to keep code forward-compatible.

Interpreting output

• Warm colors (red) indicate positive Obs-Exp values (the model underestimates the facet level for that group).

• Cool colors (blue) indicate negative Obs-Exp values (the model overestimates).

• White/neutral indicates no systematic difference.

• The "contrast" view is best for pairwise differential-functioning summaries, whereas "obs_exp" and "t" are best for cell-level diagnostics.

Typical workflow

1. Compute interaction with dif_interaction_table() or differential- functioning contrasts with analyze_dff().

2. Plot with plot_dif_heatmap(...).

3. Identify extreme cells or contrasts for follow-up.

See Also

dif_interaction_table(), analyze_dff(), analyze_dif(), dif_report()

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()`).

mfrmr documentation built on June 13, 2026, 1:07 a.m.