% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{bias_interaction_report}
\alias{bias_interaction_report}
\title{Build a bias-interaction plot-data bundle (FACETS Table 13: ranked bias list)}
\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{
\item{x}{Output from \code{\link[=estimate_bias]{estimate_bias()}} or \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} (used when \code{x} is fit).}

\item{facet_a}{First facet name (required when \code{x} is fit and
\code{interaction_facets} is not supplied).}

\item{facet_b}{Second facet name (required when \code{x} is fit and
\code{interaction_facets} is not supplied).}

\item{interaction_facets}{Character vector of two or more facets.}

\item{max_abs}{Bound for absolute bias size when estimating from fit.}

\item{omit_extreme}{Omit extreme-only elements when estimating from fit.}

\item{max_iter}{Iteration cap for bias estimation when \code{x} is fit.}

\item{tol}{Convergence tolerance for bias estimation when \code{x} is fit.}

\item{top_n}{Maximum number of ranked rows to keep.}

\item{abs_t_warn}{Warning cutoff for absolute t statistics.}

\item{abs_bias_warn}{Warning cutoff for absolute bias size.}

\item{p_max}{Warning cutoff for p-values.}

\item{sort_by}{Ranking key: \code{"abs_t"}, \code{"abs_bias"}, or \code{"prob"}.}
}
\value{
A named list with bias-interaction plotting/report components. Class:
\code{mfrm_bias_interaction}.
}
\description{
Bundles the \strong{ranked flagged-cells} view of a bias-interaction run for
downstream printing and plotting. The three sibling reports in this
family are intentionally distinct:
\itemize{
\item \code{\link[=bias_interaction_report]{bias_interaction_report()}} (this one) = FACETS Table 13: a ranked
list of interaction cells with \code{t}, \verb{bias size}, and screening tail
area -- use when reviewing which \verb{(facet_a, facet_b)} cells deserve
follow-up.
\item \code{\link[=bias_iteration_report]{bias_iteration_report()}} = iteration history / convergence trace
for the bias recalibration (FACETS Table 9 territory) -- use when
diagnosing whether the bias run itself stabilised.
\item \code{\link[=bias_pairwise_report]{bias_pairwise_report()}} = pairwise contrast table for a target
facet (FACETS Table 14 territory) -- use when comparing levels
within a facet while controlling for the other.
}
}
\details{
Preferred bundle API for interaction-bias diagnostics. The function can:
\itemize{
\item use a precomputed bias object from \code{\link[=estimate_bias]{estimate_bias()}}, or
\item estimate internally from \code{mfrm_fit} + facet specification.
}
}
\section{Interpreting output}{

Focus on ranked rows where multiple screening criteria converge:
\itemize{
\item large absolute t statistic
\item large absolute bias size
\item small screening tail area
}

The bundle is optimized for downstream \code{summary()} and
\code{\link[=plot_bias_interaction]{plot_bias_interaction()}} views.
}

\section{Typical workflow}{

\enumerate{
\item Run \code{\link[=estimate_bias]{estimate_bias()}} (or provide \code{mfrm_fit} here).
\item Build \code{bias_interaction_report(...)}.
\item Review \code{summary(out)} and visualize with \code{\link[=plot_bias_interaction]{plot_bias_interaction()}}.
}
}

\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)
out <- bias_interaction_report(bias, top_n = 10)
summary(out)
p_bi <- plot(out, draw = FALSE)
p_bi$data$plot
}
\seealso{
\code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=build_fixed_reports]{build_fixed_reports()}}, \code{\link[=plot_bias_interaction]{plot_bias_interaction()}}
}
