% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting-secondary.R
\name{plot_residual_matrix}
\alias{plot_residual_matrix}
\title{Person x facet-level standardized-residual matrix}
\usage{
plot_residual_matrix(
  fit,
  diagnostics = NULL,
  facet = "Rater",
  top_n_persons = 40L,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)
}
\arguments{
\item{fit}{An \code{mfrm_fit} from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} output. Computed on
demand when omitted.}

\item{facet}{Facet whose levels become the column axis (default
\code{"Rater"}).}

\item{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.}

\item{preset}{Visual preset.}

\item{draw}{If \code{TRUE}, draw with base graphics.}
}
\value{
An \code{mfrm_plot_data} whose \code{data} slot bundles the residual
\code{matrix} (rows = Person, columns = facet level) and the long-form
\code{obs} table.
}
\description{
Visualizes the person x element matrix of standardized residuals
from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} as a heatmap. Complements
\code{\link[=plot_guttman_scalogram]{plot_guttman_scalogram()}} (which shows raw responses) by exposing
the residual structure directly: large positive cells show
under-prediction, negative cells over-prediction.
}
\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.
}
\seealso{
\code{\link[=plot_guttman_scalogram]{plot_guttman_scalogram()}}, \code{\link[=plot_unexpected]{plot_unexpected()}},
\link{mfrmr_visual_diagnostics}
}
