% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting.R
\name{plot_fair_average}
\alias{plot_fair_average}
\title{Plot fair-average diagnostics using base R}
\usage{
plot_fair_average(
  x,
  diagnostics = NULL,
  facet = NULL,
  metric = c("AdjustedAverage", "StandardizedAdjustedAverage", "FairM", "FairZ"),
  plot_type = c("difference", "scatter"),
  top_n = 40,
  show_ci = FALSE,
  ci_level = 0.95,
  draw = TRUE,
  preset = c("standard", "publication", "compact", "monochrome"),
  ...
)
}
\arguments{
\item{x}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=fair_average_table]{fair_average_table()}}.}

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

\item{facet}{Optional facet name for level-wise lollipop plots.}

\item{metric}{Adjusted-score metric. Accepts legacy names (\code{"FairM"},
\code{"FairZ"}) and package-native names (\code{"AdjustedAverage"},
\code{"StandardizedAdjustedAverage"}).}

\item{plot_type}{\code{"difference"} or \code{"scatter"}.}

\item{top_n}{Maximum levels shown for \code{"difference"} plot.}

\item{show_ci}{Logical. When \code{TRUE}, draw approximate
confidence-interval whiskers on the fair metric using a
delta-method propagation from the logit \code{Measure} standard error
to the observed-score scale. The derivative equals the implied
score variance \code{Var(X | Measure)}, so the fair-scale standard
error is \code{Var(X) * ModelSE}. CI bounds are clipped to the rating
range. Rows where the score variance is effectively zero (levels
whose measure sits near the rating boundary, so the delta-method
approximation becomes uninformative) are drawn with an open
circle and excluded from the whiskers; the excluded count is
reported in the subtitle. For bounded \code{GPCM} fits, this option requests
\code{fair_average_table(fair_se = TRUE)} when \code{x} is a fit object and uses the
structural delta-method fair-average CI columns when they are available.
If \code{x} is a precomputed fair-average bundle without those columns, the
plot records an unavailable-CI note.}

\item{ci_level}{Confidence level used when \code{show_ci = TRUE};
default \code{0.95}. The returned plot-data object gains \code{CI_Lower},
\code{CI_Upper}, and \code{CI_Level} columns for downstream reuse.}

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

\item{preset}{Visual preset (\code{"standard"}, \code{"publication"}, \code{"compact"}, or \code{"monochrome"}).}

\item{...}{Additional arguments passed to \code{\link[=fair_average_table]{fair_average_table()}} when \code{x} is \code{mfrm_fit}.}
}
\value{
A plotting-data object of class \code{mfrm_plot_data}.
With \code{draw = FALSE}, the returned plot data includes \code{title}, \code{subtitle},
\code{legend}, \code{reference_lines}, and the stacked fair-average data.
}
\description{
Plot fair-average diagnostics using base R
}
\details{
Fair-average plots compare observed scoring tendency against model-based
fair metrics.

\strong{FairM} is the model-predicted mean score for each element, adjusting
for the ability distribution of persons actually encountered.  It
answers: "What average score would this rater/criterion produce if all
raters/criteria saw the same mix of persons?"

\strong{FairZ} standardises FairM to a z-score across elements within each
facet, making it easier to compare relative severity across facets
with different raw-score scales.

Use FairM when the raw-score metric is meaningful (e.g., reporting
average ratings on the original 1--4 scale).
Use FairZ when comparing standardised severity ranks across facets.
}
\section{Plot types}{

\describe{
\item{\code{"difference"} (default)}{Lollipop chart showing the gap between
observed and fair-average score for each element.  X-axis:
Observed - Fair metric.  Y-axis: element labels.  Points colored
teal (lenient, gap >= 0) or orange (severe, gap < 0).  Ordered by
absolute gap.}
\item{\code{"scatter"}}{Scatter plot of fair metric (x) vs observed average
(y) with an identity line.  Points colored by facet.  Useful for
checking overall alignment between observed and model-adjusted
scores.}
}
}

\section{Interpreting output}{

Difference plot: ranked element-level gaps (\code{Observed - Fair}), useful
for triage of potentially lenient/severe levels.

Scatter plot: global agreement pattern relative to the identity line.

Larger absolute gaps suggest stronger divergence between observed and
model-adjusted scoring.
}

\section{Typical workflow}{

\enumerate{
\item Start with \code{plot_type = "difference"} to find largest discrepancies.
\item Use \code{plot_type = "scatter"} to check overall alignment pattern.
\item Follow up with facet-level diagnostics for flagged levels.
}
}

\section{Further guidance}{

For a plot-selection guide and a longer walkthrough, see
\link{mfrmr_visual_diagnostics} and
\code{vignette("mfrmr-visual-diagnostics", package = "mfrmr")}.
}

\examples{
toy_full <- load_mfrmr_data("example_core")
toy_people <- unique(toy_full$Person)[1:12]
toy <- toy_full[toy_full$Person \%in\% toy_people, , drop = FALSE]
fit <- suppressWarnings(
  fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
)
p <- plot_fair_average(fit, metric = "AdjustedAverage", draw = FALSE)
if (interactive()) {
  plot_fair_average(fit, metric = "AdjustedAverage", plot_type = "difference")
}
}
\seealso{
\code{\link[=fair_average_table]{fair_average_table()}}, \code{\link[=plot_unexpected]{plot_unexpected()}}, \code{\link[=plot_displacement]{plot_displacement()}},
\code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}, \link{mfrmr_visual_diagnostics}
}
\concept{confidence intervals}
\concept{fair averages}
\concept{visual diagnostics}
