% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{bias_iteration_report}
\alias{bias_iteration_report}
\title{Build a bias-iteration report (FACETS Table 9: iteration / convergence trace)}
\usage{
bias_iteration_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 = 10
)
}
\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 iteration rows to keep in preview-oriented
summaries. The full iteration table is always returned.}
}
\value{
A named list with:
\itemize{
\item \code{table}: iteration history
\item \code{summary}: one-row convergence summary
\item \code{orientation_review}: interaction-facet sign review
\item \code{settings}: resolved reporting options
\item \code{direction_note}: one-line interpretive note describing which
direction the iteration moved (carried from the bias estimator;
empty string when the underlying estimator does not emit one)
\item \code{recommended_action}: one-line recommended action label
(e.g. \code{"converged"}, \code{"increase max_iter"}); empty string when
the underlying estimator does not emit one
}
}
\description{
This report is NOT an alias of \code{\link[=bias_interaction_report]{bias_interaction_report()}} despite the
similar name. It focuses on the \strong{recalibration path} of a bias run:
iteration table, convergence summary, and orientation review. Use this
to confirm that the bias recalibration itself converged; use
\code{\link[=bias_interaction_report]{bias_interaction_report()}} to review the ranked flagged cells from
the converged run.
}
\details{
This report focuses on the recalibration path used by \code{\link[=estimate_bias]{estimate_bias()}}.
It provides a package-native counterpart to legacy iteration printouts by
exposing the iteration table, convergence summary, and orientation review in
one bundle.
}
\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")
out <- bias_iteration_report(fit, diagnostics = diag, facet_a = "Rater", facet_b = "Criterion")
summary(out)
}
\seealso{
\code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=bias_interaction_report]{bias_interaction_report()}}, \code{\link[=build_fixed_reports]{build_fixed_reports()}}
}
