Plot a base-R QC dashboard

Usage

plot_qc_dashboard(
  fit,
  diagnostics = NULL,
  threshold_profile = "standard",
  thresholds = NULL,
  abs_z_min = 2,
  prob_max = 0.3,
  rater_facet = NULL,
  interrater_exact_warn = 0.5,
  interrater_corr_warn = 0.3,
  fixed_p_max = 0.05,
  random_p_max = 0.05,
  top_n = 20,
  draw = TRUE,
  preset = c("standard", "publication", "compact")
)

Arguments

fit: Output from fit_mfrm().
diagnostics: Optional output from diagnose_mfrm().
threshold_profile: Threshold profile name (strict, standard, lenient).
thresholds: Optional named threshold overrides.
abs_z_min: Absolute standardized-residual cutoff for unexpected panel.
prob_max: Maximum observed-category probability cutoff for unexpected panel.
rater_facet: Optional rater facet used in inter-rater panel.
interrater_exact_warn: Warning threshold for inter-rater exact agreement.
interrater_corr_warn: Warning threshold for inter-rater correlation.
fixed_p_max: Warning cutoff for fixed-effect facet chi-square p-values.
random_p_max: Warning cutoff for random-effect facet chi-square p-values.
top_n: Maximum elements displayed in displacement panel.
draw: If TRUE, draw with base graphics.
preset: Visual preset ("standard", "publication", or "compact").

Value

A plotting-data object of class mfrm_plot_data.

Details

The dashboard draws nine QC panels in a 3\(\times\)3 grid:

Panel	What it shows	Key reference lines
1. Category counts	Observed (bars) vs model-expected counts (line)	–
2. Infit vs Outfit	Scatter of element MnSq values	heuristic 0.5, 1.0, 1.5 bands
3. \|ZSTD\| histogram	Distribution of absolute standardised residuals	\|ZSTD\| = 2
4. Unexpected responses	Standardised residual vs \(-\log_{10} P_{\mathrm{obs}}\)	`abs_z_min`, `prob_max`
5. Fair-average gaps	Boxplots of (Observed - FairM) per facet	zero line
6. Displacement	Top absolute displacement values	\(\pm 0.5\) logits
7. Inter-rater agreement	Exact agreement with expected overlay per pair	`interrater_exact_warn`
8. Fixed chi-square	Fixed-effect \(\chi^2\) per facet	`fixed_p_max`
9. Separation & Reliability	Bar chart of separation index per facet	–

threshold_profile controls warning overlays. Three built-in profiles are available: "strict", "standard" (default), and "lenient". Use thresholds to override any profile value with named entries.

Plot types

This function draws a fixed 3\(\times\)3 panel grid (no plot_type argument). For individual panel control, use the dedicated helpers: plot_unexpected(), plot_fair_average(), plot_displacement(), plot_interrater_agreement(), plot_facets_chisq().

Interpreting output

Recommended panel order for fast review:

Category counts + Infit/Outfit (row 1): first-pass model screening. Category bars should roughly track the expected line; Infit/Outfit points are often reviewed against the heuristic 0.5–1.5 band.
Unexpected responses + Displacement (row 2): element-level outliers. Sparse points and small displacements are desirable.
Inter-rater + Chi-square (row 3): facet-level comparability. Read these as screening panels: higher agreement suggests stronger scoring consistency, and significant fixed chi-square indicates detectable facet spread under the current model.
Separation/Reliability (row 3): approximate screening precision. Higher separation indicates more statistically distinct strata under the current SE approximation.

Treat this dashboard as a screening layer; follow up with dedicated helpers (plot_unexpected(), plot_displacement(), plot_interrater_agreement(), plot_facets_chisq()) for detailed diagnosis.

Typical workflow

Fit and diagnose model.
Run plot_qc_dashboard() for one-page triage.
Drill into flagged panels using dedicated functions.

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
qc <- plot_qc_dashboard(fit, draw = FALSE)
if (interactive()) {
  plot_qc_dashboard(fit, rater_facet = "Rater")
}