% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting-screening.R
\name{plot_guttman_scalogram}
\alias{plot_guttman_scalogram}
\title{Guttman-style scalogram of person x item observed responses}
\usage{
plot_guttman_scalogram(
  fit,
  diagnostics = NULL,
  column_facet = NULL,
  top_n_persons = 40L,
  highlight_unexpected = TRUE,
  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; used to pick
up unexpected-response flags when available.}

\item{column_facet}{Facet name used for the columns. Default
\code{"Criterion"} when the fit contains it, otherwise the last entry
of \code{fit$config$facet_names}.}

\item{top_n_persons}{Maximum number of persons shown (default
\code{40}). Persons closest to the median measure are retained when
the population exceeds this cap.}

\item{highlight_unexpected}{Logical. When \code{TRUE} (default), draw a
heavy border around cells flagged as unexpected by
\code{\link[=unexpected_response_table]{unexpected_response_table()}}.}

\item{preset}{Visual preset.}

\item{draw}{If \code{TRUE}, draw with base graphics.}
}
\value{
An \code{mfrm_plot_data} object whose \code{data} slot bundles the
scalogram matrix and the optional unexpected-response overlay.
}
\description{
Draws a person x item (or person x facet-level) matrix coloured by
observed category, with rows ordered by person measure and columns
ordered by location measure. Unexpected responses (those that fall
far from the expected category at a given theta) are highlighted
with a heavy border so the visual reads as a Rasch-convention
Guttman scalogram.
}
\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
p <- plot_guttman_scalogram(fit, draw = FALSE)
dim(p$data$matrix)
# Look for: a clean monotone "staircase" of higher scores in the
#   upper-right triangle and lower scores in the lower-left, once
#   rows are sorted by person ability. Cells circled by the
#   unexpected-response overlay break the staircase and warrant
#   case-level review with `unexpected_response_table()`.
}
\seealso{
\code{\link[=unexpected_response_table]{unexpected_response_table()}} for the case-level review of
the cells flagged in the overlay;
\code{\link[=plot_rater_agreement_heatmap]{plot_rater_agreement_heatmap()}} for a complementary rater-pair
view of the same residual structure;
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}} for the underlying diagnostics bundle.
}
