% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weighted_kappa.R
\name{weighted_kappa}
\alias{weighted_kappa}
\alias{print.weighted_kappa}
\title{Pairwise Weighted Cohen's Kappa for Ordered Ratings}
\usage{
weighted_kappa(
  data,
  y = NULL,
  weights = c("quadratic", "linear", "unweighted"),
  levels = 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{print}{weighted_kappa}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{In matrix mode, a matrix or data frame whose rows are
observational units and whose columns are raters or classifiers. Each
column contains ordered category ratings. In two-vector mode, the first
ordinal rating vector.}

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

\item{weights}{Weight specification. The default \code{"quadratic"} uses
Fleiss-Cohen-style agreement weights. \code{"linear"} uses equal-spacing
agreement weights. \code{"unweighted"} reduces to ordinary Cohen's kappa.
Custom numeric weight matrices must be symmetric agreement weights with
diagonal 1 and entries in \code{[0, 1]}.}

\item{levels}{Optional ordered category levels. Weighted kappa depends on
category order and will not silently alphabetise arbitrary labels. If
omitted, order is inferred only when all involved ratings are ordered
factors with identical levels or when all involved ratings are numeric or
integer and can be ordered by their sorted unique values.}

\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 for \eqn{H_0: \kappa_w = 0}.}

\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{...}{Reserved for future extensions. Unsupported extra arguments are
rejected.}

\item{x}{A matrix-style \code{weighted_kappa} object.}

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

\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"}.}
}
\value{
If \code{y} is supplied, a scalar S3 object of class
\code{c("weighted_kappa", "numeric")} is returned with diagnostics and
optional \code{ci} and \code{inference} attributes. Otherwise a symmetric
matrix-style result with estimator class \code{weighted_kappa}.
}
\description{
Computes weighted Cohen's kappa for either a pair of ordinal rating vectors
or all pairwise combinations of ordinal columns in a matrix or data frame.
}
\details{
This implementation uses agreement/similarity weights internally:
\itemize{
\item \code{"unweighted"}: \eqn{w_{ij} = 1(i = j)}
\item \code{"linear"}: \eqn{w_{ij} = 1 - |i - j| / (K - 1)}
\item \code{"quadratic"}: \eqn{w_{ij} = 1 - (i - j)^2 / (K - 1)^2}
}
The \code{"quadratic"} scheme is the default and corresponds to
Fleiss-Cohen-style agreement weights. The \code{"linear"} scheme
corresponds to equal-spacing agreement weights.

For matrix mode, rows are shared observational units and columns are raters
or classifiers. A common category map is resolved in R and the main
computation is performed in C++. Missing-data handling follows the usual
\pkg{matrixCorr} \code{na_method} conventions. Pairwise complete counts are
stored in \code{attr(x, "diagnostics")$n_complete}.

\strong{Confidence intervals and standard errors.}
Confidence intervals and p-values use the exact large-sample multinomial
delta-method formula. Let
\eqn{A_w = \sum_{a,b} w_{ab} p_{ab}} be the observed weighted agreement,
\eqn{E_w = \sum_{a,b} w_{ab} q_a r_b} the expected weighted agreement,
and \eqn{D = 1 - E_w}. Define the weighted margin summaries
\deqn{ u_a = \sum_b w_{ab} r_b, \qquad v_b = \sum_a w_{ab} q_a. }
For each cell \eqn{(a,b)}, the backend uses
\deqn{ g_{ab}
      \;=\;
      \frac{D\,w_{ab} + (A_w - 1)\,(u_a + v_b)}{D^2}. }
The variance estimator is
\deqn{ \widehat{\mathrm{Var}}(\hat\kappa_w)
      \;=\;
      \frac{1}{n}\left(
      \sum_{a,b} p_{ab} g_{ab}^2 -
      \Big(\sum_{a,b} p_{ab} g_{ab}\Big)^2
      \right), }
where \eqn{n} is the number of complete paired ratings. The standard error
is \eqn{\widehat{\mathrm{se}}(\hat\kappa_w)=
\sqrt{\widehat{\mathrm{Var}}(\hat\kappa_w)}} and the CI is the Wald interval
\deqn{ \hat\kappa_w \pm z_{1-\alpha/2}\,\widehat{\mathrm{se}}(\hat\kappa_w), }
truncated to \eqn{[-1, 1]} in the returned result. Use \code{\link[=cohen_kappa]{cohen_kappa()}} for
unordered nominal categories where all disagreements are equally serious.
}
\examples{
raters <- data.frame(
  r1 = ordered(c("low", "low", "mid", "high", "high"),
               levels = c("low", "mid", "high")),
  r2 = ordered(c("low", "mid", "mid", "high", "high"),
               levels = c("low", "mid", "high")),
  r3 = ordered(c("low", "low", "high", "high", "mid"),
               levels = c("low", "mid", "high"))
)

wk <- weighted_kappa(raters)
print(wk)
summary(wk)
estimate(wk)
tidy(wk)
plot(wk)

x <- raters$r1
y <- raters$r2
weighted_kappa(x, y, weights = "linear")

}
\references{
Cohen, J. (1968). Weighted kappa: Nominal scale agreement with provision for
scaled disagreement or partial credit. \emph{Psychological Bulletin},
70(4), 213-220. \doi{10.1037/h0026256}
}
\seealso{
\code{\link[=cohen_kappa]{cohen_kappa()}} for unweighted two-rater nominal agreement;
\code{\link[=multirater_kappa]{multirater_kappa()}} for panel-level nominal agreement among three or more
raters.
}
\author{
Thiago de Paula Oliveira
}
