% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{bias_count_table}
\alias{bias_count_table}
\title{Build a bias-cell count report}
\usage{
bias_count_table(
  bias_results,
  min_count_warn = 10,
  branch = c("original", "facets"),
  fit = NULL
)
}
\arguments{
\item{bias_results}{Output from \code{\link[=estimate_bias]{estimate_bias()}}.}

\item{min_count_warn}{Minimum count threshold for flagging sparse bias cells.}

\item{branch}{Output branch:
\code{"facets"} keeps legacy manual-aligned naming, \code{"original"} returns compact QC-oriented names.}

\item{fit}{Optional \code{\link[=fit_mfrm]{fit_mfrm()}} result used to attach run context metadata.}
}
\value{
A named list with:
\itemize{
\item \code{table}: cell-level counts with low-count flags
\item \code{by_facet}: named list of counts aggregated by each interaction facet
\item \code{by_facet_a}, \code{by_facet_b}: first two facet summaries (legacy compatibility)
\item \code{summary}: one-row summary
\item \code{thresholds}: applied thresholds
\item \code{branch}, \code{style}: output branch metadata
\item \code{fit_overview}: optional one-row fit metadata when \code{fit} is supplied
}
}
\description{
Build a bias-cell count report
}
\details{
This helper summarizes how many observations contribute to each
bias-cell estimate and flags sparse cells.

Branch behavior:
\itemize{
\item \code{"facets"}: keeps legacy manual-aligned column labels (\code{Sq},
\verb{Observd Count}, \verb{Obs-Exp Average}, \verb{Model S.E.}) for side-by-side
comparison with external workflows.
\item \code{"original"}: keeps compact field names (\code{Count}, \code{BiasSize}, \code{SE}) for
custom QC workflows and scripting.
}
}
\section{Interpreting output}{

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

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

\section{Typical workflow}{

\enumerate{
\item Estimate bias with \code{\link[=estimate_bias]{estimate_bias()}}.
\item Build \code{bias_count_table(...)} in desired branch.
\item Review low-count flags before interpreting bias magnitudes.
}
}

\section{Further guidance}{

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

\section{Output columns}{

The \code{table} data.frame contains, in the legacy-compatible branch:
\describe{
\item{FacetA, FacetB}{Interaction facet level identifiers; generic
names for the two interaction facets.}
\item{Sq}{Sequential row number.}
\item{Observd Count}{Number of observations for this cell.}
\item{Obs-Exp Average}{Observed minus expected average for this cell.}
\item{Model S.E.}{Standard error of the bias estimate.}
\item{Infit, Outfit}{Fit statistics for this cell.}
\item{LowCountFlag}{Logical; \code{TRUE} when count < \code{min_count_warn}.}
}

The \code{summary} data.frame contains:
\describe{
\item{InteractionFacets}{Names of the interaction facets.}
\item{Cells, TotalCount}{Number of cells and total observations.}
\item{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 = 30)
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)
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
  )
}
}
\seealso{
\code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=unexpected_after_bias_table]{unexpected_after_bias_table()}}, \code{\link[=build_fixed_reports]{build_fixed_reports()}},
\link{mfrmr_visual_diagnostics}
}
