Build a bias-cell count report

Usage

bias_count_table(
  bias_results,
  min_count_warn = 10,
  branch = c("original", "facets"),
  fit = NULL
)

Arguments

bias_results: Output from estimate_bias().
min_count_warn: Minimum count threshold for flagging sparse bias cells.
branch: Output branch: "facets" keeps legacy manual-aligned naming, "original" returns compact QC-oriented names.
fit: Optional fit_mfrm() result used to attach run context metadata.

Value

A named list with:

table: cell-level counts with low-count flags
by_facet: named list of counts aggregated by each interaction facet
by_facet_a, by_facet_b: first two facet summaries (legacy compatibility)
summary: one-row summary
thresholds: applied thresholds
branch, style: output branch metadata
fit_overview: optional one-row fit metadata when fit is supplied

Details

This helper summarizes how many observations contribute to each bias-cell estimate and flags sparse cells.

Branch behavior:

"facets": keeps legacy manual-aligned column labels (Sq, Observd Count, Obs-Exp Average, Model S.E.) for side-by-side comparison with external workflows.
"original": keeps compact field names (Count, BiasSize, SE) for custom QC workflows and scripting.

Interpreting output

table: cell-level contribution counts and low-count flags.
by_facet: sparse-cell structure by each interaction facet.
summary: overall low-count prevalence.
fit_overview: optional run context (when fit is supplied).

Low-count cells should be interpreted cautiously because bias-size estimates can become unstable with sparse support.

Typical workflow

Estimate bias with estimate_bias().
Build bias_count_table(...) in desired branch.
Review low-count flags before interpreting bias magnitudes.

Further guidance

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

Output columns

The table data.frame contains, in the legacy-compatible branch:

FacetA, FacetB: Interaction facet level identifiers; placeholder names for the two interaction facets.
Sq: Sequential row number.
Observd Count: Number of observations for this cell.
Obs-Exp Average: Observed minus expected average for this cell.
Model S.E.: Standard error of the bias estimate.
Infit, Outfit: Fit statistics for this cell.
LowCountFlag: Logical; TRUE when count < min_count_warn.

The summary data.frame contains:

InteractionFacets: Names of the interaction facets.
Cells, TotalCount: Number of cells and total observations.
LowCountCells, LowCountPercent: Number and share of low-count cells.

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)
t11 <- bias_count_table(bias)
t11_facets <- bias_count_table(bias, branch = "facets", fit = fit)
summary(t11)
#> mfrmr Bias Count Summary
#> 
#> Overview
#>  InteractionFacets InteractionOrder InteractionMode   Branch    Style FacetA
#>  Rater x Criterion                2        pairwise original original  Rater
#>     FacetB Cells TotalCount MeanCount MedianCount MinCount MaxCount
#>  Criterion    16        384        24          24       24       24
#>  LowCountCells LowCountPercent
#>              0               0
#> 
#> Count distribution
#>  Min Q1 Median Mean Q3 Max
#>   24 24     24   24 24  24
#> 
#> Thresholds
#>         Setting Value
#>  min_count_warn    10
#> 
#> Notes
#>  - Original branch: compact count/bias columns for QC screening.
p <- plot(t11, draw = FALSE)
p2 <- plot(t11, type = "lowcount_by_facet", draw = FALSE)
if (interactive()) {
  plot(
    t11,
    type = "cell_counts",
    draw = TRUE,
    main = "Bias Cell Counts (Customized)",
    palette = c(count = "#2b8cbe", low = "#cb181d"),
    label_angle = 45
  )
}