Plot fair-average diagnostics with ggplot2

Usage

plot_fair_average(
  x,
  diagnostics = NULL,
  facet = NULL,
  metric = c("AdjustedAverage", "StandardizedAdjustedAverage", "FairM", "FairZ"),
  plot_type = c("difference", "scatter", "measure"),
  top_n = 40,
  show_ci = FALSE,
  ci_level = 0.95,
  draw = TRUE,
  preset = c("standard", "publication", "compact", "monochrome"),
  show_title = FALSE,
  show_notes = FALSE,
  marginal = c("auto", "histogram", "none"),
  ...
)

Arguments

x: Output from fit_mfrm() or fair_average_table().
diagnostics: Optional output from diagnose_mfrm() when x is mfrm_fit.
facet: Optional facet name or names. Use "Person" for ability-to-score relationships.
metric: Adjusted-score metric. Accepts legacy names ("FairM", "FairZ") and package-native names ("AdjustedAverage", "StandardizedAdjustedAverage").
plot_type: "difference", "scatter", or "measure" (Measure on x, fair score on y).
top_n: Maximum levels shown for "difference" plot.
show_ci: Draw approximate fair-score intervals. RSM/PCM propagate only the focal measure SE, holding thresholds, other effects and reference means fixed. This is not full calibration uncertainty. GPCM uses available structural delta-method SEs, conditioning on person EAP/reference means; person rows are unavailable. Bounds are clipped to the internal rating range. Unavailable intervals are retained as NA with status and notes. The difference view treats the observed average as fixed: its whiskers are not confidence intervals for the observed-minus-fair gap. Returned CI_Eligible is FALSE; CI_ReportingUse distinguishes diagnostic-only and unavailable intervals, including stored bundles.
ci_level: Confidence level used when show_ci = TRUE; default 0.95. The returned plot-data object gains CI_Lower, CI_Upper, and CI_Level columns for downstream reuse.
draw: If TRUE, print the ggplot object.
preset: Visual preset ("standard", "publication", "compact", or "monochrome").
show_title: Show the figure title. The title remains in the return value.
show_notes: Show short figure annotations. Full interpretation and uncertainty notes remain in plot_data(p, "notes") and the ggplot mfrmr_notes attribute.
...: Additional arguments passed to fair_average_table() when x is mfrm_fit.

Value

Invisibly, a ggplot object. Use plot_data() to retrieve its reusable plotting data and notes. With draw = FALSE, the returned plot data includes title, subtitle, legend, reference_lines, and the stacked fair-average data. plot_data contains the displayed rows and coordinates; excluded retains non-finite rows. notes explains the reference, uncertainty and row selection.

Details

FairM is an expected score at the mean measures of the other facets; for non-person rows it also uses the mean estimated person measure. FairZ uses zero reference measures instead. FairZ is not a z-score. The historical alias StandardizedAdjustedAverage refers to the reference environment, not z-standardization. Both metrics use fitted internal score coding. PCM averages expectations over the administered rating scales using the same observation weights and totalscore selection as the fair-score table. Its conditional derivative averages the within-scale score variances. In ordinary additive RSM/PCM JML, finite direct anchors remain eligible in both the fair score and its conditional derivative when totalscore = FALSE, even if their observed responses are all minimum or all maximum. GPCM uses an element's own thresholds for the step facet and the mean threshold profile for other facets, with its own slope for the slope facet and slope 1 otherwise. Person and other-facet measures remain at the chosen reference; these scores do not average over the observed person distribution.

plot_type = "measure" connects measures (person ability or facet effects) to the reported fair score. Select facet = "Person" for an ability-to-score view. Points reuse the table values, without fitting a trend across different reference profiles. This transformation is not independent validation of the fitted model. umean/uscale change Measure units, not score units; Positive xtreme disables conditional fair-score intervals. With the default xtreme_method = "display", it changes only the reported Measure. xtreme_method = "facets" also uses the extrapolated measure in that element's fair scores; its measure SE describes information at a corrected total, not uncertainty of the original infinite MLE. See fair_average_table().

"difference" ranks absolute observed-minus-fair gaps; "scatter" compares observed averages against fair scores with an identity line. These gaps also reflect assignment and person mix and do not by themselves diagnose leniency, severity or bias. Intervals are conditional approximations with full-refit coverage unverified. RSM/PCM intervals require a fitted model; a stored bundle alone lacks the calibration needed to calculate them. GPCM bundle intervals honor ci_level; older bundles without rating limits can only reuse intervals at their recorded confidence level.

Further guidance

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

Session plot defaults

See mfrmr_visual_diagnostics for options(mfrmr.plot_preset), argument precedence, and appearance when saving or reusing a plot.

Migration in 0.2.4

This renderer is internal. Use the corresponding plot() route in mfrmr_plot_migration; the former exported name is no longer available.

Examples

# Supplementary workflow: run explicitly to keep routine checks brief.
# example("plot_fair_average", run.dontrun = TRUE)
if (FALSE) { # \dontrun{
library(mfrmr)

# Saved synthetic MML/RSM analysis of example_operational.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "operational-mml.rds", package = "mfrmr"))
fit <- example_fit$fit

# Use the diagnostics saved with this fit
diagnostics <- example_fit$diagnostics

# How do the observed and reference-adjusted person averages compare?
plot(fit, type = "fair_average", diagnostics = diagnostics,
  facet = "Person", metric = "FairM", view = "scatter")

# Optional: inspect the gap (observed average minus FairM)
plot(fit, type = "fair_average", diagnostics = diagnostics,
  facet = "Person", metric = "FairM", view = "difference")
# A positive gap means the observed average is higher than the model-based FairM
} # }