% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting.R
\name{plot_qc_dashboard}
\alias{plot_qc_dashboard}
\title{Plot a base-R QC dashboard}
\usage{
plot_qc_dashboard(
  fit,
  diagnostics = NULL,
  threshold_profile = "standard",
  thresholds = NULL,
  abs_z_min = 2,
  prob_max = 0.3,
  rater_facet = NULL,
  interrater_exact_warn = 0.5,
  interrater_corr_warn = 0.3,
  fixed_p_max = 0.05,
  random_p_max = 0.05,
  top_n = 20,
  draw = TRUE,
  preset = c("standard", "publication", "compact", "monochrome")
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{threshold_profile}{Threshold profile name (\code{strict}, \code{standard}, \code{lenient}).}

\item{thresholds}{Optional named threshold overrides.}

\item{abs_z_min}{Absolute standardized-residual cutoff for unexpected panel.}

\item{prob_max}{Maximum observed-category probability cutoff for unexpected panel.}

\item{rater_facet}{Optional rater facet used in inter-rater panel.}

\item{interrater_exact_warn}{Warning threshold for inter-rater exact agreement.}

\item{interrater_corr_warn}{Warning threshold for inter-rater correlation.}

\item{fixed_p_max}{Warning cutoff for fixed-effect facet chi-square p-values.}

\item{random_p_max}{Warning cutoff for random-effect facet chi-square p-values.}

\item{top_n}{Maximum elements displayed in displacement panel.}

\item{draw}{If \code{TRUE}, draw with base graphics.}

\item{preset}{Visual preset (\code{"standard"}, \code{"publication"}, \code{"compact"}, or \code{"monochrome"}).}
}
\value{
A plotting-data object of class \code{mfrm_plot_data}.
}
\description{
Plot a base-R QC dashboard
}
\details{
The dashboard draws nine QC panels in a 3\eqn{\times}3 grid:\tabular{lll}{
   Panel \tab What it shows \tab Key reference lines \cr
   1. Category counts \tab Observed (bars) vs model-expected counts (line) \tab -- \cr
   2. Infit vs Outfit \tab Scatter of element MnSq values \tab heuristic 0.5, 1.0, 1.5 bands \cr
   3. |ZSTD| histogram \tab Distribution of absolute standardised residuals \tab |ZSTD| = 2 \cr
   4. Unexpected responses \tab Standardised residual vs \eqn{-\log_{10} P_{\mathrm{obs}}} \tab \code{abs_z_min}, \code{prob_max} \cr
   5. Fair-average gaps \tab Boxplots of (Observed - FairM) per facet \tab zero line \cr
   6. Displacement \tab Top absolute displacement values \tab \eqn{\pm 0.5} logits \cr
   7. Inter-rater agreement \tab Exact agreement with expected overlay per pair \tab \code{interrater_exact_warn} \cr
   8. Fixed chi-square \tab Fixed-effect \eqn{\chi^2} per facet \tab \code{fixed_p_max} \cr
   9. Separation & Reliability \tab Bar chart of separation index per facet \tab -- \cr
}


\code{threshold_profile} controls warning overlays.  Three built-in profiles
are available: \code{"strict"}, \code{"standard"} (default), and \code{"lenient"}.
Use \code{thresholds} to override any profile value with named entries.

For bounded \code{GPCM}, the dashboard now reuses the residual-based
diagnostics stack and marks the fair-average panel unavailable rather
than silently reusing the Rasch-only compatibility calculation.
}
\section{Plot types}{

This function draws a fixed 3\eqn{\times}3 panel grid (no \code{plot_type}
argument).  For individual panel control, use the dedicated helpers:
\code{\link[=plot_unexpected]{plot_unexpected()}}, \code{\link[=plot_fair_average]{plot_fair_average()}}, \code{\link[=plot_displacement]{plot_displacement()}},
\code{\link[=plot_interrater_agreement]{plot_interrater_agreement()}}, \code{\link[=plot_facets_chisq]{plot_facets_chisq()}}.
}

\section{Interpreting output}{

Recommended panel order for fast review:
\enumerate{
\item \strong{Category counts + Infit/Outfit} (row 1): first-pass model screening.
Category bars should roughly track the expected line; Infit/Outfit points
are often reviewed against the heuristic 0.5--1.5 band.
\item \strong{Unexpected responses + Displacement} (row 2): element-level
outliers.  Sparse points and small displacements are desirable.
\item \strong{Inter-rater + Chi-square} (row 3): facet-level comparability.
Read these as screening panels: higher agreement suggests stronger
scoring consistency, and significant fixed chi-square indicates
detectable facet spread under the current model.
\item \strong{Separation/Reliability} (row 3): approximate screening precision.
Higher separation indicates more statistically distinct strata under the
current SE approximation.
}

Treat this dashboard as a screening layer; follow up with dedicated helpers
(\code{plot_unexpected()}, \code{plot_displacement()}, \code{plot_interrater_agreement()},
\code{plot_facets_chisq()}) for detailed diagnosis.
}

\section{Typical workflow}{

\enumerate{
\item Fit and diagnose model.
\item Run \code{plot_qc_dashboard()} for one-page triage.
\item Drill into flagged panels using dedicated functions.
}
}

\examples{
# Fast smoke run: build the plot data only (no graphics device).
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:3], ]
fit_quick <- suppressWarnings(
  fit_mfrm(toy_small, "Person", c("Rater", "Criterion"), "Score",
           method = "JML", maxit = 3)
)
qc_quick <- plot_qc_dashboard(fit_quick, draw = FALSE)
names(qc_quick$data)

\donttest{
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
qc <- plot_qc_dashboard(fit, draw = FALSE)
qc$data$panels$Status
# Look for: a row whose `Status` is "OK" for each panel that
#   the run should support. "WARN" / "REVIEW" rows tell you which
#   downstream helper to run next (e.g. `plot_unexpected()`,
#   `plot_residual_pca()`); the dashboard is a triage screen, not
#   a publication figure on its own.
if (interactive()) {
  plot_qc_dashboard(fit, rater_facet = "Rater")
}
}
}
\seealso{
\code{\link[=plot_unexpected]{plot_unexpected()}}, \code{\link[=plot_fair_average]{plot_fair_average()}}, \code{\link[=plot_displacement]{plot_displacement()}}, \code{\link[=plot_interrater_agreement]{plot_interrater_agreement()}}, \code{\link[=plot_facets_chisq]{plot_facets_chisq()}}, \code{\link[=build_visual_summaries]{build_visual_summaries()}}
}
