% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-bias-collection.R
\name{estimate_all_bias}
\alias{estimate_all_bias}
\title{Estimate bias across multiple facet pairs}
\usage{
estimate_all_bias(
  fit,
  diagnostics = NULL,
  pairs = NULL,
  include_person = FALSE,
  drop_empty = TRUE,
  keep_errors = TRUE,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. When \code{NULL},
diagnostics are computed with \code{residual_pca = "none"}.}

\item{pairs}{Optional list of facet specifications. Each element should be a
character vector of length 2 or more, for example
\code{list(c("Rater", "Criterion"), c("Task", "Criterion"))}.
When \code{NULL}, all 2-way combinations of modeled facets are used.}

\item{include_person}{If \code{TRUE} and \code{pairs = NULL}, include \code{"Person"} in the
automatically generated pair set.}

\item{drop_empty}{If \code{TRUE}, omit empty bias tables from \code{by_pair} while still
recording them in the summary table.}

\item{keep_errors}{If \code{TRUE}, retain per-pair error rows in the returned
\code{errors} table instead of failing the whole batch.}

\item{max_abs}{Passed to \code{\link[=estimate_bias]{estimate_bias()}}.}

\item{omit_extreme}{Passed to \code{\link[=estimate_bias]{estimate_bias()}}.}

\item{max_iter}{Passed to \code{\link[=estimate_bias]{estimate_bias()}}.}

\item{tol}{Passed to \code{\link[=estimate_bias]{estimate_bias()}}.}
}
\value{
A named list with class \code{mfrm_bias_collection}.
}
\description{
Estimate bias across multiple facet pairs
}
\details{
This function orchestrates repeated calls to \code{\link[=estimate_bias]{estimate_bias()}} across
multiple facet pairs and returns a consolidated bundle.

\strong{Bias/interaction} in MFRM refers to a systematic departure from
the additive model for a specific combination of facet elements
(e.g., a particular rater is unexpectedly harsh on a particular
criterion).  See \code{\link[=estimate_bias]{estimate_bias()}} for the mathematical formulation.

When \code{pairs = NULL}, the function builds all 2-way combinations of
modelled facets automatically.  For a model with facets Rater,
Criterion, and Task, this yields Rater\eqn{\times}Criterion,
Rater\eqn{\times}Task, and Criterion\eqn{\times}Task.

The \code{summary} table aggregates results across pairs:
\itemize{
\item \code{Rows}: number of interaction cells estimated
\item \code{Significant}: count of cells with \eqn{|t| \ge 2}
\item \code{MeanAbsBias}: average absolute bias magnitude (logits)
}

Per-pair failures (e.g., insufficient data for a sparse pair) are
captured in \code{errors} rather than stopping the entire batch.
}
\section{Output}{

The returned object is a bundle-like list with class
\code{mfrm_bias_collection} and components such as:
\itemize{
\item \code{summary}: one row per requested interaction
\item \code{by_pair}: named list of successful \code{\link[=estimate_bias]{estimate_bias()}} outputs
\item \code{errors}: per-pair error log
\item \code{settings}: resolved execution settings
\item \code{primary}: first successful bias bundle, useful for downstream helpers
}
}

\section{Typical workflow}{

\enumerate{
\item Fit with \code{\link[=fit_mfrm]{fit_mfrm()}} and diagnose with \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. For
\code{RSM} / \code{PCM} reporting runs, prefer \code{method = "MML"} plus
\code{diagnostic_mode = "both"} in the diagnostics call.
\item Run \code{estimate_all_bias()} to compute app-style multi-pair interactions.
\item Pass the resulting \code{by_pair} list into \code{\link[=reporting_checklist]{reporting_checklist()}} or
\code{\link[=facet_quality_dashboard]{facet_quality_dashboard()}}.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "MML", quad_points = 7, maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none", diagnostic_mode = "both")
bias_all <- estimate_all_bias(fit, diagnostics = diag)
bias_all$summary[, c("Interaction", "Rows", "Significant")]
}
}
\seealso{
\code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=facet_quality_dashboard]{facet_quality_dashboard()}}
}
