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, ...)

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.
...	Additional graphical parameters passed to graphics::image().

Value

Invisibly, the matrix used for plotting.

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 = 25)
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)

mfrmr documentation built on March 31, 2026, 1:06 a.m.