% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{interrater_agreement_table}
\alias{interrater_agreement_table}
\title{Build an inter-rater agreement report}
\usage{
interrater_agreement_table(
  fit,
  diagnostics = NULL,
  rater_facet = NULL,
  context_facets = NULL,
  exact_warn = 0.5,
  corr_warn = 0.3,
  include_precision = TRUE,
  top_n = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{rater_facet}{Name of the rater facet. If \code{NULL}, inferred from facet names.}

\item{context_facets}{Optional context facets used to match observations for
agreement. If \code{NULL}, all remaining facets (including \code{Person}) are used.}

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

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

\item{include_precision}{If \code{TRUE}, append rater severity spread indices from
the facet precision summary when available.}

\item{top_n}{Optional maximum number of pair rows to keep.}
}
\value{
A named list with:
\itemize{
\item \code{summary}: one-row inter-rater summary
\item \code{pairs}: pair-level agreement table
\item \code{settings}: applied options and thresholds
}
}
\description{
Build an inter-rater agreement report
}
\details{
This helper computes pairwise rater agreement on matched contexts
and returns both a pair-level table and a one-row summary. The output is
package-native and does not require knowledge of legacy report numbering.
}
\section{Interpreting output}{

\itemize{
\item \code{summary}: overall agreement level, number/share of flagged pairs.
\item \code{pairs}: pairwise exact agreement, correlation, and direction/size gaps.
\item \code{settings}: applied facet matching and warning thresholds.
}

Pairs flagged by both low exact agreement and low correlation generally
deserve highest calibration priority.
}

\section{Typical workflow}{

\enumerate{
\item Run with explicit \code{rater_facet} (and \code{context_facets} if needed).
\item Review \code{summary(ir)} and top flagged rows in \code{ir$pairs}.
\item Visualize with \code{\link[=plot_interrater_agreement]{plot_interrater_agreement()}}.
}
}

\section{Output columns}{

The \code{pairs} data.frame contains:
\describe{
\item{Rater1, Rater2}{Rater pair identifiers.}
\item{N}{Number of matched-context observations for this pair.}
\item{Exact}{Proportion of exact score agreements.}
\item{ExpectedExact}{Expected exact agreement under chance.}
\item{Adjacent}{Proportion of adjacent (+/- 1 category) agreements.}
\item{MeanDiff}{Signed mean score difference (Rater1 - Rater2).}
\item{MAD}{Mean absolute score difference.}
\item{Corr}{Pearson correlation between paired scores.}
\item{Flag}{Logical; \code{TRUE} when Exact < \code{exact_warn} or Corr < \code{corr_warn}.}
\item{OpportunityCount, ExactCount, ExpectedExactCount, AdjacentCount}{Raw
counts behind the agreement proportions.}
}

The \code{summary} data.frame contains:
\describe{
\item{RaterFacet}{Name of the rater facet analyzed.}
\item{TotalPairs}{Number of rater pairs evaluated.}
\item{ExactAgreement}{Mean exact agreement across all pairs.}
\item{AgreementMinusExpected}{Observed exact agreement minus expected exact
agreement.}
\item{MeanCorr}{Mean pairwise correlation.}
\item{FlaggedPairs, FlaggedShare}{Count and proportion of flagged pairs.}
\item{RaterSeparation, RaterReliability}{Severity-spread indices for the
rater facet, reported separately from agreement.}
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
ir <- interrater_agreement_table(fit, rater_facet = "Rater")
# One-row overview: ExactAgreement, ExpectedExactAgreement, MeanCorr,
# RaterSeparation, and RaterReliability are the headline reportable
# statistics.
ir$summary
# Per-pair detail (Rater1 vs Rater2 with Exact, Adjacent, Corr, MAD).
head(ir$pairs)
p_ir <- plot(ir, draw = FALSE)
p_ir$data$plot
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=facets_chisq_table]{facets_chisq_table()}}, \code{\link[=plot_interrater_agreement]{plot_interrater_agreement()}},
\link{mfrmr_visual_diagnostics}
}
