% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{run_qc_pipeline}
\alias{run_qc_pipeline}
\title{Run automated quality control pipeline}
\usage{
run_qc_pipeline(
  fit,
  diagnostics = NULL,
  threshold_profile = "standard",
  thresholds = NULL,
  rater_facet = NULL,
  include_bias = TRUE,
  bias_results = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. Computed automatically if NULL.}

\item{threshold_profile}{Threshold preset: \code{"strict"}, \code{"standard"} (default),
or \code{"lenient"}.}

\item{thresholds}{Named list to override individual thresholds.}

\item{rater_facet}{Character name of the rater facet for inter-rater check
(auto-detected if NULL).}

\item{include_bias}{If \code{TRUE} and bias available in diagnostics, check DIF/bias.}

\item{bias_results}{Optional pre-computed bias results from \code{\link[=estimate_bias]{estimate_bias()}}.}
}
\value{
Object of class \code{mfrm_qc_pipeline} with verdicts, overall status,
details, and recommendations.
}
\description{
Integrates convergence, model fit, reliability, separation, element misfit,
unexpected responses, category structure, connectivity, inter-rater agreement,
and DIF/bias into a single pass/warn/fail report.
}
\details{
The pipeline evaluates 10 quality checks and assigns a verdict
(Pass / Warn / Fail) to each.  The overall status is the most severe
verdict across all checks.  Diagnostics are computed automatically via
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}} if not supplied.

Reliability and separation are used here as QC signals. In \code{mfrmr},
\code{Reliability} / \code{Separation} are model-based facet indices and
\code{RealReliability} / \code{RealSeparation} provide more conservative lower bounds.
For \code{MML}, these rely on model-based \code{ModelSE} values for non-person facets;
for \code{JML}, they remain exploratory approximations.

Three threshold presets are available via \code{threshold_profile}:\tabular{llll}{
   Aspect \tab strict \tab standard \tab lenient \cr
   Global fit warn \tab 1.3 \tab 1.5 \tab 1.7 \cr
   Global fit fail \tab 1.5 \tab 2.0 \tab 2.5 \cr
   Reliability pass \tab 0.90 \tab 0.80 \tab 0.70 \cr
   Separation pass \tab 3.0 \tab 2.0 \tab 1.5 \cr
   Misfit warn (pct) \tab 3 \tab 5 \tab 10 \cr
   Unexpected fail \tab 3 \tab 5 \tab 10 \cr
   Min cat count \tab 15 \tab 10 \tab 5 \cr
   Agreement pass \tab 60 \tab 50 \tab 40 \cr
   Bias fail (pct) \tab 5 \tab 10 \tab 15 \cr
}


Individual thresholds can be overridden via the \code{thresholds} argument
(a named list keyed by the internal threshold names shown above).

For bounded \code{GPCM}, this pipeline is available as caveated operational
triage over supported diagnostics. Its pass/warn/fail labels remain package
QC policy overlays; they are not FACETS score-side equivalence, operational
scoring decisions, design-forecasting evidence, or automatic fairness /
validity decisions.
}
\section{QC checks}{

The 10 checks are:
\enumerate{
\item \strong{Convergence}: Did the model converge?
\item \strong{Global fit}: Infit/Outfit MnSq within the current review band.
\item \strong{Reliability}: Minimum non-person facet model reliability index.
\item \strong{Separation}: Minimum non-person facet model separation index.
\item \strong{Element misfit}: Percentage of elements with Infit/Outfit
outside the current review band.
\item \strong{Unexpected responses}: Percentage of observations with
large standardized residuals.
\item \strong{Category structure}: Minimum category count and threshold
ordering.
\item \strong{Connectivity}: All observations in a single connected subset.
\item \strong{Inter-rater agreement}: Exact agreement percentage for the
rater facet (if applicable).
\item \strong{Functioning/Bias screen}: Percentage of interaction cells that
cross the screening threshold (if interaction results are available).
}
}

\section{Interpreting output}{

\itemize{
\item \verb{$overall}: character string \code{"Pass"}, \code{"Warn"}, or \code{"Fail"}.
\item \verb{$verdicts}: tibble with columns \code{Check}, \code{Verdict}, \code{Value}, and
\code{Threshold} for each of the 10 checks.
\item \verb{$details}: character vector of human-readable detail strings.
\item \verb{$raw_details}: named list of per-check numeric details for
programmatic access.
\item \verb{$recommendations}: character vector of actionable suggestions for
checks that did not pass.
\item \verb{$config}: records the threshold profile and effective thresholds.
}
}

\section{Typical workflow}{

\enumerate{
\item Fit a model: \code{fit <- fit_mfrm(...)}.
\item Optionally compute diagnostics and bias:
\code{diag <- diagnose_mfrm(fit)};
\code{bias <- estimate_bias(fit, diag, ...)}.
\item Run the pipeline: \code{qc <- run_qc_pipeline(fit, diag, bias_results = bias)}.
\item Check \code{qc$overall} for the headline verdict.
\item Review \code{qc$verdicts} for per-check details.
\item Follow \code{qc$recommendations} for remediation.
\item Visualize with \code{\link[=plot_qc_pipeline]{plot_qc_pipeline()}}.
}
}

\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)
qc
summary(qc)
qc$verdicts
}
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=estimate_bias]{estimate_bias()}},
\code{\link[=mfrm_threshold_profiles]{mfrm_threshold_profiles()}}, \code{\link[=plot_qc_pipeline]{plot_qc_pipeline()}},
\code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}, \code{\link[=build_visual_summaries]{build_visual_summaries()}}
}
