plot_residual_matrix: Person x facet-level standardized-residual matrix

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

Person x facet-level standardized-residual matrix

Description

Visualizes the person x element matrix of standardized residuals from diagnose_mfrm() as a heatmap. Complements plot_guttman_scalogram() (which shows raw responses) by exposing the residual structure directly: large positive cells show under-prediction, negative cells over-prediction.

Usage

plot_residual_matrix(
  fit,
  diagnostics = NULL,
  facet = "Rater",
  top_n_persons = 40L,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)

Arguments

fit	An mfrm_fit from fit_mfrm().
diagnostics	Optional diagnose_mfrm() output. Computed on demand when omitted.
facet	Facet whose levels become the column axis (default "Rater").
top_n_persons	Cap on the number of rows. Defaults to 40 to keep the figure legible; persons are kept by largest absolute residual mean.
preset	Visual preset.
draw	If TRUE, draw with base graphics.

Value

An mfrm_plot_data whose data slot bundles the residual matrix (rows = Person, columns = facet level) and the long-form obs table.

See Also

plot_guttman_scalogram(), plot_unexpected(), mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 30)
p <- plot_residual_matrix(fit, top_n_persons = 12, draw = FALSE)
dim(p$data$matrix)
# Look for: cell values within ~|2| are routine; |residual| > 2 is
#   misfit at the 5% level and |residual| > 3 at the 1% level
#   (Wright & Linacre 1994). Persons with multiple high-magnitude
#   cells across the same facet level point at scoring drift.

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