% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{plot_bias_interaction}
\alias{plot_bias_interaction}
\title{Plot bias interaction diagnostics (preferred alias)}
\usage{
plot_bias_interaction(
  x,
  plot = c("scatter", "ranked", "heatmap", "abs_t_hist", "facet_profile"),
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  top_n = 40,
  abs_t_warn = 2,
  abs_bias_warn = 0.5,
  p_max = 0.05,
  sort_by = c("abs_t", "abs_bias", "prob"),
  show_ci = FALSE,
  ci_level = 0.95,
  main = NULL,
  palette = NULL,
  label_angle = 45,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)
}
\arguments{
\item{x}{Output from \code{\link[=estimate_bias]{estimate_bias()}} or \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{plot}{Plot type: \code{"scatter"}, \code{"ranked"}, \code{"heatmap"},
\code{"abs_t_hist"}, or \code{"facet_profile"}.}

\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{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"}.}

\item{show_ci}{Logical. When \code{TRUE} and \code{plot} is \code{"scatter"} or
\code{"ranked"}, draw confidence-interval whiskers for \verb{Bias Size}.
Bounded \code{GPCM} rows use the conditional profile-likelihood limits
returned by \code{\link[=estimate_bias]{estimate_bias()}} when available; otherwise the interval
uses the per-cell standard error from \code{\link[=estimate_bias]{estimate_bias()}}. Ignored for
\code{"heatmap"}, \code{"abs_t_hist"}, and \code{"facet_profile"}.}

\item{ci_level}{Confidence level used when \code{show_ci = TRUE}; default
\code{0.95}. The returned plot-data object gains \code{CI_Lower} / \code{CI_Upper}
/ \code{CI_Level} columns on the \code{ranked_table} and \code{scatter_data}
elements for downstream reuse.}

\item{main}{Optional plot title override.}

\item{palette}{Optional named color overrides (\code{normal}, \code{flag}, \code{hist},
\code{profile}).}

\item{label_angle}{Label angle hint for ranked/profile labels.}

\item{preset}{Visual preset (\code{"standard"}, \code{"publication"}, \code{"compact"}, or \code{"monochrome"}).}

\item{draw}{If \code{TRUE}, draw with base graphics.}
}
\value{
A plotting-data object of class \code{mfrm_plot_data}.
}
\description{
Plot bias interaction diagnostics (preferred alias)
}
\details{
Visualization front-end for \code{\link[=bias_interaction_report]{bias_interaction_report()}} with multiple views.
With \code{draw = FALSE}, the returned plot data include \code{plot_long},
\code{plot_annotations}, \code{flag_summary}, and \code{plot_settings} in addition to the
view-specific \code{ranked_table}, \code{scatter_data}, \code{facet_profile}, and heatmap
components. Use these fields when rebuilding the same screening view in
ggplot2, plotly, Quarto, or a dashboard.
}
\section{Plot types}{

\describe{
\item{\code{"scatter"} (default)}{Scatter plot of bias size (x) vs
screening t-statistic (y). Points colored by flag status. Dashed reference
lines at \code{abs_bias_warn} and \code{abs_t_warn}.  Use for overall triage
of interaction effects.}
\item{\code{"ranked"}}{Ranked bar chart of top \code{top_n} interactions sorted
by \code{sort_by} criterion (absolute t, absolute bias, or probability).
Bars colored red for flagged cells.}
\item{\code{"heatmap"}}{Facet A by facet B matrix of signed bias size.
Cells retain reusable matrix and flag tables for dashboards. This is
a Table 13 follow-up display: it supports pattern recognition but does
not turn screening rows into confirmatory tests.}
\item{\code{"abs_t_hist"}}{Histogram of absolute screening t-statistics across all
interaction cells.  Dashed reference line at \code{abs_t_warn}.  Use for
assessing the overall distribution of interaction effect sizes.}
\item{\code{"facet_profile"}}{Per-facet-level aggregation showing mean
absolute bias and flag rate.  Useful for identifying which
individual facet levels drive systematic interaction patterns.}
}
}

\section{Interpreting output}{

Start with \code{"scatter"} or \code{"ranked"} for triage, then confirm pattern shape
using \code{"abs_t_hist"} and \code{"facet_profile"}.

Consistent flags across multiple views are stronger screening signals of
systematic interaction bias than a single extreme row, but they do not by
themselves establish formal inferential evidence.
}

\section{Typical workflow}{

\enumerate{
\item Estimate bias with \code{\link[=estimate_bias]{estimate_bias()}} or pass \code{mfrm_fit} directly.
\item Plot with \code{plot = "ranked"} for top interactions.
\item Cross-check using \code{plot = "scatter"} and \code{plot = "facet_profile"}.
}
}

\examples{
toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
p <- plot_bias_interaction(
  fit,
  diagnostics = diagnose_mfrm(fit, residual_pca = "none"),
  facet_a = "Rater",
  facet_b = "Criterion",
  preset = "publication",
  draw = FALSE
)
}
\seealso{
\code{\link[=bias_interaction_report]{bias_interaction_report()}}, \code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=plot_displacement]{plot_displacement()}}
}
\concept{bias screening}
\concept{confidence intervals}
\concept{visual diagnostics}
