% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cohen_kappa.R
\name{cohen_kappa}
\alias{cohen_kappa}
\alias{summary.cohen_kappa}
\alias{print.summary.cohen_kappa}
\alias{print.cohen_kappa}
\alias{plot.cohen_kappa}
\title{Pairwise Cohen's Kappa for Nominal Ratings}
\usage{
cohen_kappa(
  data,
  y = NULL,
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  p_value = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  ...
)

\method{summary}{cohen_kappa}(object, digits = 4, ci_digits = 3, p_digits = 4, ...)

\method{print}{summary.cohen_kappa}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{print}{cohen_kappa}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{cohen_kappa}(
  x,
  title = NULL,
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)
}
\arguments{
\item{data}{In matrix mode, a matrix or data frame whose rows are
observational units and whose columns are raters or classifiers. Supported
column types are factor, ordered factor, character, logical, integer, and
numeric, all treated as nominal categories here. If the ratings are truly
ordinal and disagreements should be weighted by distance, use
\code{\link[=weighted_kappa]{weighted_kappa()}} instead. In two-vector mode, the first nominal rating
vector.}

\item{y}{Optional second nominal rating vector. When supplied, the function
returns a single Cohen's kappa estimate for \code{data} and \code{y}.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing values. \code{"complete"} applies listwise
deletion across retained columns before computing the matrix. In matrix
mode, \code{"pairwise"} uses pair-specific complete observations.}

\item{ci}{Logical; if \code{TRUE}, attach large-sample delta-method
confidence intervals.}

\item{p_value}{Logical; if \code{TRUE}, attach large-sample delta-method
Wald test statistics and p-values.}

\item{conf_level}{Confidence level used when \code{ci = TRUE}. Default is
\code{0.95}.}

\item{n_threads}{Integer \eqn{\ge 1}. Number of OpenMP threads used by the
matrix C++ backend. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{output}{Output representation for matrix mode.
\itemize{
\item \code{"matrix"} (default): full dense matrix.
\item \code{"sparse"}: sparse matrix from \pkg{Matrix} containing only
retained entries after thresholding.
\item \code{"edge_list"}: long-form data frame representation.
}}

\item{threshold}{Non-negative absolute-value filter for non-matrix outputs:
retain entries with \code{abs(value) >= threshold}. Must be \code{0} when
\code{output = "matrix"}.}

\item{diag}{Logical; whether to include diagonal entries in sparse and
edge-list outputs.}

\item{...}{Additional theme arguments.}

\item{object}{A scalar or matrix-style \code{cohen_kappa} object.}

\item{digits}{Integer; number of decimal places for displayed values.}

\item{ci_digits}{Integer; number of decimal places for confidence limits.}

\item{p_digits}{Integer; number of decimal places for p-values.}

\item{x}{A scalar or matrix-style \code{cohen_kappa} object.}

\item{n}{Optional preview row threshold.}

\item{topn}{Optional number of leading/trailing rows to show when truncated.}

\item{max_vars}{Optional maximum number of visible columns.}

\item{width}{Optional display width.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{title}{Optional plot title.}

\item{low_color}{Fill/color used for negative agreement.}

\item{high_color}{Fill/color used for positive agreement.}

\item{mid_color}{Unused placeholder for API consistency with matrix heatmaps.}

\item{value_text_size}{Text size for the estimate label.}

\item{ci_text_size}{Text size for the CI label.}

\item{show_value}{Logical; whether to print the estimate and CI labels.}
}
\value{
If \code{y} is supplied, a scalar S3 object of class \code{"cohen_kappa"}
backed by a numeric value, with attributes \code{diagnostics}, and
optionally \code{ci}, \code{inference}, and \code{conf.level}. Otherwise a
symmetric matrix-style result with estimator class \code{cohen_kappa}.
}
\description{
Computes unweighted Cohen's kappa for either a pair of nominal rating
vectors or all pairwise combinations of nominal columns in a matrix or data
frame.
}
\details{
Cohen's kappa is an agreement coefficient for two raters assigning the same
units to mutually exclusive nominal categories. For contingency-table cell
proportions \eqn{p_{ij}},
\deqn{
\kappa = \frac{p_o - p_e}{1 - p_e},
}
where \eqn{p_o = \sum_i p_{ii}} is the observed agreement and
\eqn{p_e = \sum_i p_{i+} p_{+i}} is the chance agreement implied by the
marginal category proportions.

This implementation is strictly the original unweighted nominal-scale Cohen's
kappa. If the categories are ordinal and near disagreements should count as
less severe than distant disagreements, use \code{\link[=weighted_kappa]{weighted_kappa()}} instead.

In matrix mode, columns are treated as raters/classifiers and rows as shared
observational units. All pairwise Cohen's kappas between columns are
computed. Category labels are encoded in R before dispatch to C++, using a
common label mapping across all columns so that identical labels in different
columns correspond to the same category code.

Missing values are encoded as \code{NA_integer_} before entering the C++
backend. With \code{na_method = "error"}, missing values are rejected before
computation. With \code{na_method = "complete"}, listwise deletion is
applied across retained columns. With \code{na_method = "pairwise"}, each
pair uses its own complete observations. Pairwise complete counts are stored
in \code{attr(x, "diagnostics")$n_complete}.

\strong{Confidence intervals and standard errors.}
The implementation uses the exact large-sample formula. Let \eqn{p_{ab}}
be the empirical cell proportions,
\eqn{q_a = \sum_b p_{ab}} the row margins, \eqn{r_b = \sum_a p_{ab}} the
column margins, and \eqn{D = 1 - p_e}. For each cell \eqn{(a,b)}, define
the influence contribution
\deqn{ g_{ab}
      \;=\;
      \frac{\mathbf{1}(a=b)\,D + (p_o - 1)\,(r_a + q_b)}{D^2}. }
The variance estimator used by the code is
\deqn{ \widehat{\mathrm{Var}}(\hat\kappa)
      \;=\;
      \frac{1}{n}\left(
      \sum_{a,b} p_{ab} g_{ab}^2 -
      \Big(\sum_{a,b} p_{ab} g_{ab}\Big)^2
      \right), }
with \eqn{n} the number of complete paired ratings and
\eqn{\widehat{\mathrm{se}}(\hat\kappa)=\sqrt{\widehat{\mathrm{Var}}(\hat\kappa)}}.
The confidence interval is the Wald interval
\deqn{ \hat\kappa \pm z_{1-\alpha/2}\,\widehat{\mathrm{se}}(\hat\kappa), }
truncated to \eqn{[-1, 1]} in the returned result.
}
\examples{
x <- factor(c("A", "A", "B", "B", "A", "B"))
y <- factor(c("A", "B", "B", "B", "A", "A"))
cohen_kappa(x, y)

raters <- data.frame(
  r1 = factor(c("low", "low", "high", "high", "mid")),
  r2 = factor(c("low", "mid", "high", "high", "mid")),
  r3 = c("low", "low", "high", "mid", "mid")
)
ck <- cohen_kappa(raters)
print(ck)
summary(ck)
estimate(ck)
tidy(ck)
plot(ck)

}
\references{
Cohen, J. (1960). A coefficient of agreement for nominal scales.
\emph{Educational and Psychological Measurement}, 20(1), 37-46.
\doi{10.1177/001316446002000104}
}
\seealso{
\code{\link[=weighted_kappa]{weighted_kappa()}} for two-rater ordered-category agreement with
distance-sensitive disagreement weights; \code{\link[=multirater_kappa]{multirater_kappa()}} for
panel-level nominal agreement among three or more raters.
}
\author{
Thiago de Paula Oliveira
}
