% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting.R
\name{plot_facets_chisq}
\alias{plot_facets_chisq}
\title{Plot facet variability diagnostics using base R}
\usage{
plot_facets_chisq(
  x,
  diagnostics = NULL,
  fixed_p_max = 0.05,
  random_p_max = 0.05,
  plot_type = c("fixed", "random", "variance"),
  main = NULL,
  palette = NULL,
  label_angle = 45,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)
}
\arguments{
\item{x}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=facets_chisq_table]{facets_chisq_table()}}.}

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

\item{fixed_p_max}{Warning cutoff for fixed-effect chi-square p-values.}

\item{random_p_max}{Warning cutoff for random-effect chi-square p-values.}

\item{plot_type}{\code{"fixed"}, \code{"random"}, or \code{"variance"}.}

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

\item{palette}{Optional named color overrides (\code{fixed_ok}, \code{fixed_flag},
\code{random_ok}, \code{random_flag}, \code{variance}).}

\item{label_angle}{X-axis label angle for bar-style plots.}

\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 facet variability diagnostics using base R
}
\details{
Facet chi-square tests assess whether the elements within each facet
differ significantly.

\strong{Fixed-effect chi-square} tests the null hypothesis
\eqn{H_0: \delta_1 = \delta_2 = \cdots = \delta_J} (all element
measures are equal). A flagged result (\eqn{p <} \code{fixed_p_max})
suggests detectable between-element spread under the fitted model, but
it should be interpreted alongside design quality, sample size, and other
diagnostics.

\strong{Random-effect chi-square} tests whether element heterogeneity
exceeds what would be expected from measurement error alone, treating
element measures as random draws. A flagged result is screening
evidence that the facet may not be exchangeable under the current model.

\strong{Random variance} is the estimated between-element variance
component after removing measurement error.  It quantifies the
magnitude of true heterogeneity on the logit scale.
}
\section{Plot types}{

\describe{
\item{\code{"fixed"} (default)}{Bar chart of fixed-effect chi-square by
facet. Bars colored red when the null hypothesis is rejected at
\code{fixed_p_max}. A flagged (red) bar means the facet shows spread worth
reviewing under the fitted model.}
\item{\code{"random"}}{Bar chart of random-effect chi-square by facet.
Bars colored red when rejected at \code{random_p_max}.}
\item{\code{"variance"}}{Bar chart of estimated random variance
(logit\eqn{^2}) by facet.  Reference line at 0.  Larger values
indicate greater true heterogeneity among elements.}
}
}

\section{Interpreting output}{

Colored flags reflect configured p-value thresholds (\code{fixed_p_max},
\code{random_p_max}). For the fixed test, a flagged (red) result suggests
facet spread worth reviewing under the current model. For the random test, a
flagged result is screening evidence that the facet may contribute
non-trivial heterogeneity beyond measurement error.
}

\section{Typical workflow}{

\enumerate{
\item Review \code{"fixed"} and \code{"random"} panels for flagged facets.
\item Check \code{"variance"} to contextualize heterogeneity.
\item Cross-check with inter-rater and element-level fit diagnostics.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
p <- plot_facets_chisq(fit, draw = FALSE)
if (interactive()) {
  plot_facets_chisq(
    fit,
    draw = TRUE,
    plot_type = "fixed",
    preset = "publication",
    main = "Facet Chi-square (Customized)",
    palette = c(fixed_ok = "#2b8cbe", fixed_flag = "#cb181d"),
    label_angle = 45
  )
}
}
\seealso{
\code{\link[=facets_chisq_table]{facets_chisq_table()}}, \code{\link[=plot_interrater_agreement]{plot_interrater_agreement()}}, \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}
}
