% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-dashboards.R
\name{facet_quality_dashboard}
\alias{facet_quality_dashboard}
\title{Facet-quality dashboard for facet-level screening}
\usage{
facet_quality_dashboard(
  fit,
  diagnostics = NULL,
  facet = NULL,
  bias_results = NULL,
  severity_warn = 1,
  misfit_warn = NULL,
  central_tendency_max = 0.25,
  bias_count_warn = 1L,
  bias_abs_t_warn = 2,
  bias_abs_size_warn = 0.5,
  bias_p_max = 0.05
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{facet}{Optional facet name. When \code{NULL}, the function tries to infer
a rater-like facet and otherwise falls back to the first modeled facet.}

\item{bias_results}{Optional output from \code{\link[=estimate_bias]{estimate_bias()}} or a named list
of such outputs. Non-matching bundles are skipped quietly.}

\item{severity_warn}{Absolute estimate cutoff used to flag severity
outliers.}

\item{misfit_warn}{Mean-square cutoff used to flag misfit. Values above
this cutoff or below its reciprocal are flagged.}

\item{central_tendency_max}{Absolute estimate cutoff used to flag central
tendency. Levels near zero are marked.}

\item{bias_count_warn}{Minimum flagged-bias row count required to flag a
level.}

\item{bias_abs_t_warn}{Absolute \code{t} cutoff used when deriving bias-row
flags from a raw bias bundle.}

\item{bias_abs_size_warn}{Absolute bias-size cutoff used when deriving
bias-row flags from a raw bias bundle.}

\item{bias_p_max}{Probability cutoff used when deriving bias-row flags
from a raw bias bundle.}
}
\value{
An object of class \code{mfrm_facet_dashboard} (also inheriting from
\code{mfrm_bundle} and \code{list}). The object summarizes one target facet:
\code{overview} reports the facet-level screening totals, \code{summary} provides
aggregate estimates and flag counts, \code{detail} contains one row per facet
level with the computed screening indicators, \code{ranked} orders levels by
review priority, \code{flagged} keeps only levels requiring follow-up,
\code{bias_sources} records which bias-result bundles contributed to the
counts, \code{settings} stores the resolved thresholds, and \code{notes} gives short
interpretation messages about how to read the dashboard.
}
\description{
Build a compact dashboard for one facet at a time, combining facet
severity, misfit, central-tendency screening, and optional bias counts.
}
\details{
The dashboard screens individual facet elements across four
complementary criteria:
\itemize{
\item \strong{Severity}: elements with \eqn{|\mathrm{Estimate}| >}
\code{severity_warn} logits are flagged as unusually harsh or lenient.
\item \strong{Misfit}: elements with Infit or Outfit MnSq outside the
acceptance band are flagged. The band defaults to the package
pair returned by \code{\link[=mfrm_misfit_thresholds]{mfrm_misfit_thresholds()}} (Linacre 0.5-1.5);
pass \code{misfit_warn = 1.5} to keep the older symmetric
\eqn{[1/}\code{misfit_warn}\eqn{,\;}\code{misfit_warn}\eqn{]}
form (0.67-1.5).
\item \strong{Central tendency}: elements with
\eqn{|\mathrm{Estimate}| <} \code{central_tendency_max} logits
are flagged.  Near-zero estimates may indicate a rater who avoids
extreme categories, producing artificially narrow score ranges.
\item \strong{Bias}: elements involved in \eqn{\ge} \code{bias_count_warn}
screen-positive interaction cells (from \code{\link[=estimate_bias]{estimate_bias()}}) are flagged.
}

A \strong{flag density} score counts how many of the four criteria each
element triggers.  Elements flagged on multiple criteria warrant
priority review (e.g., rater retraining, data exclusion).

Default thresholds are designed for moderate-stakes rating contexts.
Adjust for your application: stricter thresholds for high-stakes
certification, more lenient for formative assessment.
}
\section{Output}{

The returned object is a bundle-like list with class
\code{mfrm_facet_dashboard} and components:
\itemize{
\item \code{facet}: character scalar naming the dashboard's target facet
\item \code{facet_source}: character scalar describing whether the target
facet was inferred from the fit configuration or supplied
explicitly
\item \code{overview}: one-row structural overview
\item \code{summary}: one-row screening summary
\item \code{detail}: level-level detail table
\item \code{ranked}: detail ordered by flag density / severity
\item \code{flagged}: flagged levels only
\item \code{bias_sources}: per-bundle bias aggregation metadata
\item \code{settings}: resolved threshold settings
\item \code{notes}: short interpretation notes
\item \code{diagnostics}: the \code{mfrm_diagnostics} bundle the dashboard was
built from (echoed for downstream helpers that need to traverse
the same diagnostics object)
\item \code{bias_results}: the \code{mfrm_bias} bundle (or list of bundles)
when \code{bias_results} was supplied; \code{NULL} otherwise
}
}

\examples{
toy <- load_mfrmr_data("example_core")
toy <- toy[toy$Person \%in\% unique(toy$Person)[1:8], ]
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
dash <- facet_quality_dashboard(fit, diagnostics = diag)
summary(dash)
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}
}
