Plot bias interaction diagnostics (preferred alias)

Usage

plot_bias_interaction(
  x,
  plot = c("scatter", "ranked", "abs_t_hist", "facet_profile"),
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  top_n = 40,
  abs_t_warn = 2,
  abs_bias_warn = 0.5,
  p_max = 0.05,
  sort_by = c("abs_t", "abs_bias", "prob"),
  main = NULL,
  palette = NULL,
  label_angle = 45,
  preset = c("standard", "publication", "compact"),
  draw = TRUE
)

Arguments

x: Output from estimate_bias() or fit_mfrm().
plot: Plot type: "scatter", "ranked", "abs_t_hist", or "facet_profile".
diagnostics: Optional output from diagnose_mfrm() (used when x is fit).
facet_a: First facet name (required when x is fit and interaction_facets is not supplied).
facet_b: Second facet name (required when x is fit and interaction_facets is not supplied).
interaction_facets: Character vector of two or more facets.
top_n: Maximum number of ranked rows to keep.
abs_t_warn: Warning cutoff for absolute t statistics.
abs_bias_warn: Warning cutoff for absolute bias size.
p_max: Warning cutoff for p-values.
sort_by: Ranking key: "abs_t", "abs_bias", or "prob".
main: Optional plot title override.
palette: Optional named color overrides (normal, flag, hist, profile).
label_angle: Label angle hint for ranked/profile labels.
preset: Visual preset ("standard", "publication", or "compact").
draw: If TRUE, draw with base graphics.

Value

A plotting-data object of class mfrm_plot_data.

Details

Visualization front-end for bias_interaction_report() with multiple views.

Plot types

"scatter" (default): Scatter plot of bias size (x) vs screening t-statistic (y). Points colored by flag status. Dashed reference lines at abs_bias_warn and abs_t_warn. Use for overall triage of interaction effects.
"ranked": Ranked bar chart of top top_n interactions sorted by sort_by criterion (absolute t, absolute bias, or probability). Bars colored red for flagged cells.
"abs_t_hist": Histogram of absolute screening t-statistics across all interaction cells. Dashed reference line at abs_t_warn. Use for assessing the overall distribution of interaction effect sizes.
"facet_profile": Per-facet-level aggregation showing mean absolute bias and flag rate. Useful for identifying which individual facet levels drive systematic interaction patterns.

Interpreting output

Start with "scatter" or "ranked" for triage, then confirm pattern shape using "abs_t_hist" and "facet_profile".

Consistent flags across multiple views are stronger screening signals of systematic interaction bias than a single extreme row, but they do not by themselves establish formal inferential evidence.

Typical workflow

Estimate bias with estimate_bias() or pass mfrm_fit directly.
Plot with plot = "ranked" for top interactions.
Cross-check using plot = "scatter" and plot = "facet_profile".

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
p <- plot_bias_interaction(
  fit,
  diagnostics = diagnose_mfrm(fit, residual_pca = "none"),
  facet_a = "Rater",
  facet_b = "Criterion",
  preset = "publication",
  draw = FALSE
)