% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting.R
\name{plot_interrater_agreement}
\alias{plot_interrater_agreement}
\title{Plot inter-rater agreement diagnostics using base R}
\usage{
plot_interrater_agreement(
  x,
  diagnostics = NULL,
  rater_facet = NULL,
  context_facets = NULL,
  exact_warn = 0.5,
  corr_warn = 0.3,
  plot_type = c("exact", "corr", "difference"),
  top_n = 20,
  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[=interrater_agreement_table]{interrater_agreement_table()}}.}

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

\item{rater_facet}{Name of the rater facet when \code{x} is \code{mfrm_fit}.}

\item{context_facets}{Optional context facets when \code{x} is \code{mfrm_fit}.}

\item{exact_warn}{Warning threshold for exact agreement.}

\item{corr_warn}{Warning threshold for pairwise correlation.}

\item{plot_type}{\code{"exact"}, \code{"corr"}, or \code{"difference"}.}

\item{top_n}{Maximum pairs displayed for bar-style plots.}

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

\item{palette}{Optional named color overrides (\code{ok}, \code{flag}, \code{expected}).}

\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 inter-rater agreement diagnostics using base R
}
\details{
Inter-rater agreement plots summarize pairwise consistency for a chosen
rater facet.  Agreement statistics are computed over observations that
share the same person and context-facet levels, ensuring that
comparisons reflect identical rating targets.

\strong{Exact agreement} is the proportion of matched observations where
both raters assigned the same category score.  The \strong{expected
agreement} line shows the proportion expected by chance given each
rater's marginal category distribution, providing a baseline.

\strong{Pairwise correlation} is the Pearson correlation between scores
assigned by each rater pair on matched observations.

The \strong{difference plot} decomposes disagreement into systematic bias
(mean signed difference on x-axis: positive = Rater 1 more severe)
and total inconsistency (mean absolute difference on y-axis).  Points
near the origin indicate both low bias and low inconsistency.

The \code{context_facets} parameter specifies which facets define "the
same rating target" (e.g., Criterion).  When \code{NULL}, all non-rater
facets are used as context.
}
\section{Plot types}{

\describe{
\item{\code{"exact"} (default)}{Bar chart of exact agreement proportion by
rater pair.  Expected agreement overlaid as connected circles.
Horizontal reference line at \code{exact_warn}.  Bars colored red when
observed agreement falls below the warning threshold.}
\item{\code{"corr"}}{Bar chart of pairwise Pearson correlation by rater
pair.  Reference line at \code{corr_warn}.  Ordered by correlation
(lowest first).  Low correlations suggest inconsistent rank
ordering of persons between raters.}
\item{\code{"difference"}}{Scatter plot.  X-axis: mean signed score
difference (Rater 1 \eqn{-} Rater 2); positive values indicate
Rater 1 is more severe.  Y-axis: mean absolute difference
(overall disagreement magnitude).  Points colored red when
flagged.  Vertical reference at 0.}
}
}

\section{Interpreting output}{

Pairs below \code{exact_warn} and/or \code{corr_warn} should be prioritized for
rater calibration review.  On the difference plot, points far from the
origin along the x-axis indicate systematic bias; points high on the
y-axis indicate large inconsistency regardless of direction.
}

\section{Typical workflow}{

\enumerate{
\item Select rater facet and run \code{"exact"} view.
\item Confirm with \code{"corr"} view.
\item Use \code{"difference"} to inspect directional disagreement.
}
}

\section{Further guidance}{

For a plot-selection guide and a longer walkthrough, see
\link{mfrmr_visual_diagnostics} and
\code{vignette("mfrmr-visual-diagnostics", package = "mfrmr")}.
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
p <- plot_interrater_agreement(fit, rater_facet = "Rater", draw = FALSE)
if (interactive()) {
  plot_interrater_agreement(
    fit,
    rater_facet = "Rater",
    draw = TRUE,
    plot_type = "exact",
    main = "Inter-rater Agreement (Customized)",
    palette = c(ok = "#2b8cbe", flag = "#cb181d"),
    label_angle = 45,
    preset = "publication"
  )
}
}
}
\seealso{
\code{\link[=interrater_agreement_table]{interrater_agreement_table()}}, \code{\link[=plot_facets_chisq]{plot_facets_chisq()}},
\code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}, \link{mfrmr_visual_diagnostics}
}
