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", "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,
...
)Arguments
- x
Output from
fit_mfrm()orfair_average_table().- diagnostics
Optional output from
diagnose_mfrm()whenxismfrm_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_EligibleisFALSE;CI_ReportingUsedistinguishes diagnostic-only and unavailable intervals, including stored bundles.- ci_level
Confidence level used when
show_ci = TRUE; default0.95. The returned plot-data object gainsCI_Lower,CI_Upper, andCI_Levelcolumns for downstream reuse.- draw
If
TRUE, draw with base graphics.- 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
data$notesand the ggplotmfrmr_notesattribute.- ...
Additional arguments passed to
fair_average_table()whenxismfrm_fit.
Value
A plotting-data object of class mfrm_plot_data.
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").
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.
Session plot defaults
Set options(mfrmr.plot_preset = "publication") to choose a session default
for plotting functions that expose the common preset argument. The
supported values are "standard", "publication", "compact" and
"monochrome". Precedence is an explicit call argument, then the session
option, then "standard". For example, preset = "standard" overrides
a session set to "monochrome". Explicit preset = NULL retains the
earlier package-default behavior; it does not read the session option.
Invalid session values cause an error only when that option is needed.
The category-curve, data-quality, fit-review, connectivity and network
routes of plot() for report bundles use the same option through ....
Plots without a common preset argument, including extended-model plots
with their own palette controls, keep their own settings. This option
selects a preset, not a universal theme or a guarantee that all renderers
implement every appearance control identically.
New plot payloads retain the resolved preset for supported saved-data
rendering. Converting an existing payload with as_ggplot() uses its saved
appearance, even after the session option changes. A call that creates a
new plot from a fit or statistical result uses the current default.
For a reproducible script, supply preset explicitly or set the option in
that script. Saving only the fitted model does not save a session option.
No global ggplot theme is changed.
Restore previous settings with old <- options(mfrmr.plot_preset = "monochrome") followed by options(old). Use
options(mfrmr.plot_preset = NULL) to remove the option. The preset changes
appearance, not estimates, confidence levels or diagnostic thresholds.
Examples
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
