% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting-anchor-qc.R
\name{plot_qc_pipeline}
\alias{plot_qc_pipeline}
\title{Plot QC pipeline results}
\usage{
plot_qc_pipeline(x, type = c("traffic_light", "detail"), draw = TRUE, ...)
}
\arguments{
\item{x}{Output from \code{\link[=run_qc_pipeline]{run_qc_pipeline()}}.}

\item{type}{Plot type: \code{"traffic_light"} (default) or \code{"detail"}.}

\item{draw}{If \code{FALSE}, return plot data invisibly without drawing.}

\item{...}{Additional graphical parameters passed to plotting functions.}
}
\value{
Invisible verdicts tibble from the QC pipeline.
}
\description{
Visualizes the output from \code{\link[=run_qc_pipeline]{run_qc_pipeline()}} as either a traffic-light
bar chart or a detail panel showing values versus thresholds.
}
\details{
Two plot types are provided for visual triage of QC results:
\itemize{
\item \strong{\code{"traffic_light"}} (default): A horizontal bar chart with one row
per QC check.  Bars are coloured green (Pass), amber (Warn), or red
(Fail).  Provides an at-a-glance summary of the current QC review state.
\item \strong{\code{"detail"}}: A panel showing each check's observed value and its
pass/warn/fail thresholds.  Useful for understanding how close a
borderline result is to the next verdict level.
}
}
\section{QC checks performed}{

The pipeline evaluates up to 10 checks (depending on available
diagnostics):
\enumerate{
\item \strong{Convergence}: did the optimizer converge?
\item \strong{Overall Infit}: global information-weighted mean-square
\item \strong{Overall Outfit}: global unweighted mean-square
\item \strong{Misfit rate}: proportion of elements with \eqn{|\mathrm{ZSTD}| > 2}
\item \strong{Category usage}: minimum observations per score category
\item \strong{Disordered steps}: whether threshold estimates are monotonic
\item \strong{Separation} (per facet): element discrimination adequacy
\item \strong{Residual PCA eigenvalue}: first-component eigenvalue (if computed)
\item \strong{Displacement}: maximum absolute displacement across elements
\item \strong{Inter-rater agreement}: minimum pairwise exact agreement
}
}

\section{Interpreting plots}{

\itemize{
\item \strong{Green} (Pass): the check meets the current threshold-profile criteria.
\item \strong{Amber} (Warn): borderline---monitor but not necessarily
disqualifying.  Review the detail panel to see how close the value
is to the fail threshold.
\item \strong{Red} (Fail): requires investigation before strong operational or
interpretive claims are made from the current run. Common remedies include collapsing categories
(for disordered steps), removing outlier raters (for misfit), or
increasing sample size (for low separation).
\item The detail view shows numeric values, making it easy to communicate
exact results to stakeholders.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("study1")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
qc <- run_qc_pipeline(fit)
plot_qc_pipeline(qc, draw = FALSE)
}
}
\seealso{
\code{\link[=run_qc_pipeline]{run_qc_pipeline()}}, \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}},
\code{\link[=build_visual_summaries]{build_visual_summaries()}}, \link{mfrmr_visual_diagnostics}
}
