plot_qc_dashboard: Plot a base-R QC dashboard

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Plot a base-R QC dashboard

Description

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").

Details

The dashboard draws nine QC panels in a 3\times3 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.

Value

A plotting-data object of class mfrm_plot_data.

Plot types

This function draws a fixed 3\times3 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:

1. 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.

2. Unexpected responses + Displacement (row 2): element-level outliers. Sparse points and small displacements are desirable.

3. 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.

4. 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

1. Fit and diagnose model.

2. Run plot_qc_dashboard() for one-page triage.

3. Drill into flagged panels using dedicated functions.

See Also

plot_unexpected(), plot_fair_average(), plot_displacement(), plot_interrater_agreement(), plot_facets_chisq(), build_visual_summaries()

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")
}

mfrmr documentation built on March 31, 2026, 1:06 a.m.