Build a bias-interaction plot-data bundle (preferred alias)

Usage

bias_interaction_report(
  x,
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001,
  top_n = 50,
  abs_t_warn = 2,
  abs_bias_warn = 0.5,
  p_max = 0.05,
  sort_by = c("abs_t", "abs_bias", "prob")
)

Arguments

x: Output from estimate_bias() or fit_mfrm().
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.
max_abs: Bound for absolute bias size when estimating from fit.
omit_extreme: Omit extreme-only elements when estimating from fit.
max_iter: Iteration cap for bias estimation when x is fit.
tol: Convergence tolerance for bias estimation when x is fit.
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".

Value

A named list with bias-interaction plotting/report components. Class: mfrm_bias_interaction.

Details

Preferred bundle API for interaction-bias diagnostics. The function can:

use a precomputed bias object from estimate_bias(), or
estimate internally from mfrm_fit + facet specification.

Interpreting output

Focus on ranked rows where multiple screening criteria converge:

large absolute t statistic
large absolute bias size
small screening tail area

The bundle is optimized for downstream summary() and plot_bias_interaction() views.

Typical workflow

Run estimate_bias() (or provide mfrm_fit here).
Build bias_interaction_report(...).
Review summary(out) and visualize with plot_bias_interaction().

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias <- estimate_bias(fit, diag, facet_a = "Rater", facet_b = "Criterion", max_iter = 2)
out <- bias_interaction_report(bias, top_n = 10)
summary(out)
#> mfrmr Bias Interaction Summary 
#>   Class: mfrm_bias_interaction
#>   Components (14): ranked_table, scatter_data, facet_profile, summary, thresholds, facet_a, facet_b, interaction_facets, interaction_order, interaction_mode, orientation_audit, mixed_sign, direction_note, recommended_action
#> 
#> Interaction summary
#>  InteractionFacets InteractionOrder InteractionMode FacetA    FacetB Cells
#>  Rater x Criterion                2        pairwise  Rater Criterion    16
#>  Flagged FlaggedPercent MeanAbsT MeanAbsBias
#>        3          18.75      NaN        0.31
#> 
#> Ranked interaction rows: facet_profile
#>      Facet        Level Cells MeanAbsBias MeanAbsT Flagged FlagRate
#>      Rater          R01     4       0.400      NaN       1       25
#>      Rater          R02     4       0.127      NaN       0        0
#>      Rater          R03     4       0.192      NaN       0        0
#>      Rater          R04     4       0.520      NaN       2       50
#>  Criterion     Accuracy     4       0.545      NaN       2       50
#>  Criterion      Content     4       0.154      NaN       0        0
#>  Criterion     Language     4       0.195      NaN       0        0
#>  Criterion Organization     4       0.346      NaN       1       25
#> 
#> Settings
#>        Setting Value
#>     abs_t_warn     2
#>  abs_bias_warn   0.5
#>          p_max  0.05
#>        sort_by abs_t
#>          top_n    10
#> 
#> Notes
#>  - Bias interaction report with ranked cells and facet-level profiles.
p_bi <- plot(out, draw = FALSE)
class(p_bi)
#> [1] "mfrm_plot_data" "list"