plot_displacement: Plot displacement diagnostics using base R

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

Plot displacement diagnostics using base R

Description

Plot displacement diagnostics using base R

Usage

plot_displacement(
  x,
  diagnostics = NULL,
  anchored_only = FALSE,
  facets = NULL,
  plot_type = c("lollipop", "hist"),
  top_n = 40,
  preset = c("standard", "publication", "compact"),
  draw = TRUE,
  ...
)

Arguments

x	Output from fit_mfrm() or displacement_table().
diagnostics	Optional output from diagnose_mfrm() when x is mfrm_fit.
anchored_only	Keep only anchored/group-anchored levels.
facets	Optional subset of facets.
plot_type	"lollipop" or "hist".
top_n	Maximum levels shown in "lollipop" mode.
preset	Visual preset ("standard", "publication", or "compact").
draw	If TRUE, draw with base graphics.
...	Additional arguments passed to displacement_table() when x is mfrm_fit.

Details

Displacement quantifies how much a single element's calibration would shift the overall model if it were allowed to move freely. It is computed as:

\mathrm{Displacement}_j = \frac{\sum_i (X_{ij} - E_{ij})} {\sum_i \mathrm{Var}_{ij}}

where the sums run over all observations involving element j. The standard error is 1 / \sqrt{\sum_i \mathrm{Var}_{ij}}, and a t-statistic t = \mathrm{Displacement} / \mathrm{SE} flags elements whose observed residual pattern is inconsistent with the current anchor structure.

Displacement is most informative after anchoring: large values suggest that anchored values may be drifting from the current sample. For non-anchored analyses, displacement reflects residual calibration tension.

Value

A plotting-data object of class mfrm_plot_data.

Plot types

"lollipop" (default)

Dot-and-line chart of displacement values. X-axis: displacement (logits). Y-axis: element labels. Points colored red when flagged (default: |\mathrm{Disp.}| > 0.5 logits). Dashed lines at \pm threshold. Ordered by absolute displacement.

"hist"

Histogram of displacement values with Freedman-Diaconis breaks. Dashed reference lines at \pm threshold. Use for inspecting the overall distribution shape.

Interpreting output

Lollipop: top absolute displacement levels; flagged points indicate larger movement from anchor expectations.

Histogram: overall displacement distribution and threshold lines. A symmetric distribution centred near zero indicates good anchor stability; heavy tails or skew suggest systematic drift.

Use anchored_only = TRUE when your main question is anchor robustness.

Typical workflow

1. Run with plot_type = "lollipop" and anchored_only = TRUE.

2. Inspect distribution with plot_type = "hist".

3. Drill into flagged rows via displacement_table().

Further guidance

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

See Also

displacement_table(), plot_unexpected(), plot_fair_average(), plot_qc_dashboard(), mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
p <- plot_displacement(fit, anchored_only = FALSE, draw = FALSE)
if (interactive()) {
  plot_displacement(
    fit,
    anchored_only = FALSE,
    plot_type = "lollipop",
    preset = "publication"
  )
}

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