displacement_table: Compute displacement diagnostics for facet levels
In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

displacement_table

R Documentation

Compute displacement diagnostics for facet levels

Description

Compute displacement diagnostics for facet levels

Usage

displacement_table(
  fit,
  diagnostics = NULL,
  facets = NULL,
  anchored_only = FALSE,
  abs_displacement_warn = 0.5,
  abs_t_warn = 2,
  top_n = NULL
)

Arguments

`fit`	Output from `fit_mfrm()`.
`diagnostics`	Optional output from `diagnose_mfrm()`.
`facets`	Optional subset of facets.
`anchored_only`	If `TRUE`, keep only directly/group anchored levels.
`abs_displacement_warn`	Absolute displacement warning threshold.
`abs_t_warn`	Absolute displacement t-value warning threshold.
`top_n`	Optional maximum number of rows to keep after sorting.

Details

Displacement is computed as a one-step Newton update: sum(residual) / sum(information) for each facet level. This approximates how much a level would move if constraints were relaxed.

Value

A named list with:

table: displacement diagnostics by level
summary: one-row summary
thresholds: applied thresholds

Interpreting output

table: level-wise displacement and flag indicators.
summary: count/share of flagged levels.
thresholds: displacement and t-value cutoffs.

Large absolute displacement in anchored levels suggests potential instability in anchor assumptions.

Typical workflow

Run displacement_table(fit, anchored_only = TRUE) for anchor checks.
Inspect summary(disp) then detailed rows.
Visualize with plot_displacement().

Output columns

The table data.frame contains:

Facet, Level: Facet name and element label.
Displacement: One-step Newton displacement estimate (logits).
DisplacementSE: Standard error of the displacement.
DisplacementT: Displacement / SE ratio.
Estimate, SE: Current measure estimate and its standard error.
N: Number of observations involving this level.
AnchorValue, AnchorStatus, AnchorType: Anchor metadata.
Flag: Logical; TRUE when displacement exceeds thresholds.

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
disp <- displacement_table(fit, anchored_only = FALSE)
summary(disp)
p_disp <- plot(disp, draw = FALSE)
class(p_disp)

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