% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/krippendorff_alpha.R
\name{krippendorff_alpha}
\alias{krippendorff_alpha}
\alias{print.krippendorff_alpha}
\alias{summary.krippendorff_alpha}
\alias{print.summary.krippendorff_alpha}
\alias{plot.krippendorff_alpha}
\title{Krippendorff's Alpha Reliability Coefficient}
\usage{
krippendorff_alpha(
  data,
  levels = NULL,
  input = c("ratings", "counts"),
  level = c("nominal", "ordinal", "interval", "ratio"),
  method = c("customary", "analytical"),
  na_method = c("error", "complete", "available"),
  min_raters = 2L,
  ci = FALSE,
  p_value = FALSE,
  conf_level = 0.95,
  se_method = c("auto", "bootstrap", "jackknife", "none"),
  n_boot = 1000L,
  seed = NULL,
  n_threads = getOption("matrixCorr.threads", 1L),
  return_matrices = FALSE,
  verbose = FALSE,
  ...
)

\method{print}{krippendorff_alpha}(x, digits = 4, ...)

\method{summary}{krippendorff_alpha}(object, digits = 4, ...)

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

\method{plot}{krippendorff_alpha}(
  x,
  type = c("estimate", "item_disagreement", "category_proportion", "coincidence"),
  ...
)
}
\arguments{
\item{data}{Input data.
For \code{input = "ratings"}, rows are units/items and columns are
coders/raters. For \code{input = "counts"}, rows are units/items and
columns are categories containing per-item category counts.}

\item{levels}{Optional category labels in analysis order. For ordinal
character data, explicit \code{levels} are required unless the data are
ordered factors. For interval and ratio alpha, \code{levels} must be
coercible to finite numeric values.}

\item{input}{One of \code{"ratings"} or \code{"counts"}.}

\item{level}{Measurement level: \code{"nominal"}, \code{"ordinal"},
\code{"interval"}, or \code{"ratio"}.}

\item{method}{Estimator. \code{"customary"} uses the coincidence-matrix
estimator of Krippendorff/Hayes. \code{"analytical"} uses the improved
estimator and jackknife inference direction described by Hughes.}

\item{na_method}{Missing-data rule. \code{"error"} rejects missing ratings,
\code{"complete"} removes any item with one or more missing ratings, and
\code{"available"} retains items with at least \code{min_raters} observed
ratings. For \code{input = "counts"}, missing counts are not allowed and
rows with total counts below \code{min_raters} are dropped.}

\item{min_raters}{Minimum number of observed ratings required for a retained
item. Must be at least \code{2}.}

\item{ci}{Logical; if \code{TRUE}, attach confidence intervals.}

\item{p_value}{Logical; if \code{TRUE}, attach test statistics and p-values.
This is available only for \code{method = "analytical"} with jackknife
inference.}

\item{conf_level}{Confidence level for intervals. Default is \code{0.95}.}

\item{se_method}{Standard-error method. \code{"auto"} resolves to
\code{"bootstrap"} for customary alpha when \code{ci = TRUE}, and to
\code{"jackknife"} for analytical alpha when \code{ci = TRUE} or
\code{p_value = TRUE}. \code{"bootstrap"} is allowed only for customary
alpha. \code{"jackknife"} is the primary inference path for analytical
alpha. \code{"none"} disables uncertainty output.}

\item{n_boot}{Number of bootstrap resamples used for customary alpha when
\code{ci = TRUE}.}

\item{seed}{Optional positive integer seed used for reproducible bootstrap
resampling.}

\item{n_threads}{Integer \eqn{\ge 1}. Number of OpenMP threads used by the
C++ backend.}

\item{return_matrices}{Logical; if \code{TRUE}, attach the retained count
matrix, observed coincidence matrix, expected coincidence matrix, and
disagreement matrix in \code{attr(x, "matrices")}.}

\item{verbose}{Logical; if \code{TRUE}, emit short progress messages.}

\item{...}{Unused.}

\item{x}{A \code{krippendorff_alpha} object.}

\item{digits}{Integer; number of decimal places for rounded numeric columns.}

\item{object}{A \code{krippendorff_alpha} 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{type}{Plot type: \code{"estimate"}, \code{"item_disagreement"},
\code{"category_proportion"}, or \code{"coincidence"}.}
}
\value{
A one-row data frame with class
\code{c("krippendorff_alpha", "agreement_result", "data.frame")}. The
object stores method metadata, diagnostics, and optional matrices in
attributes.
}
\description{
Estimates Krippendorff's alpha as a panel-level reliability/agreement
coefficient among two or more coders, raters, observers, judges, or
instruments. Missing ratings are supported through \code{na_method}, and
nominal, ordinal, interval, and ratio disagreement functions are available.
}
\details{
Krippendorff's alpha is a panel-level reliability coefficient, not a
pairwise correlation matrix. The customary coincidence-matrix estimator is
\deqn{ \alpha = 1 - \frac{D_o}{D_e}, }
where \eqn{D_o} is the observed disagreement and \eqn{D_e} is the expected
disagreement under chance assignment.

For retained item \eqn{u} with \eqn{m_u} observed ratings and category
counts \eqn{n_{uc}}, the observed coincidence matrix updates by
\deqn{ O_{ck} \leftarrow O_{ck} +
       \frac{n_{uc}(n_{uk} - 1(c=k))}{m_u - 1}. }
Let \eqn{n_c = \sum_k O_{ck}} and \eqn{n = \sum_c n_c}. Then
\deqn{ D_o = \frac{1}{n}\sum_{c,k} O_{ck}\,\delta^2_{ck}, }
\deqn{ D_e = \frac{1}{n(n-1)}\sum_{c,k} n_c n_k\,\delta^2_{ck}, }
where \eqn{\delta^2_{ck}} is the level-specific disagreement matrix.

The disagreement functions implemented here are:
\itemize{
\item nominal: \eqn{\delta^2_{ck} = 1(c \ne k)}
\item ordinal: Krippendorff's cumulative-margin disagreement based on the
pooled category margins
\item interval: \eqn{\delta^2_{ck} = (v_c - v_k)^2}
\item ratio:
\eqn{\delta^2_{ck} = (v_c - v_k)^2 / (v_c + v_k)^2}, with
\eqn{\delta^2_{ck}=0} when both values are zero
}

\strong{Analytical estimator and inference.}
Hughes (2024) recommends a different point estimator based on within-item
and pooled pairwise disagreement. Let \eqn{a} be the number of retained
items, \eqn{m_i} the number of ratings in item \eqn{i}, and
\eqn{N = \sum_i m_i}. Define
\deqn{ \bar n = \frac{N - \sum_i m_i^2 / N}{a - 1}. }
The within-item mean square is
\deqn{ MSE =
       \frac{1}{N}\sum_{i=1}^a
       \frac{\sum_{j<k}\delta^2(x_{ij}, x_{ik})}{m_i - 1}, }
the pooled total disagreement is
\deqn{ SST = \frac{1}{N}\sum_{r<s}\delta^2(z_r, z_s), }
where \eqn{z_1,\ldots,z_N} are the pooled observed ratings, and
\deqn{ SSA = SST - (N-a)\,MSE, \qquad
       MSA = \frac{SSA}{a-1}. }
With \eqn{\theta = MSA/MSE} and \eqn{\eta = \log(\theta)}, the analytical
alpha estimate is
\deqn{ \alpha =
       \frac{\theta - 1}{\theta + \bar n - 1}. }

When analytical inference is requested, the implementation uses the
delete-one-item jackknife on \eqn{\eta}. If \eqn{\eta_{(-i)}} is the
leave-one-item-out transform and \eqn{a} is the number of retained items,
the jackknife pseudo-values are
\deqn{ p_i = a\,\hat\eta - (a-1)\,\hat\eta_{(-i)}, }
with standard error
\deqn{ \widehat{\mathrm{se}}(\hat\eta)
       = \sqrt{\mathrm{Var}(p_1,\ldots,p_a) / a}. }
The confidence interval is formed on the \eqn{\eta}-scale with a
\eqn{t_{a-1}} critical value and back-transformed to alpha using the full
data \eqn{\bar n}. The analytical p-value tests \eqn{H_0: \alpha = 0},
equivalently \eqn{H_0: \eta = 0}, via the t statistic
\deqn{ t = \hat\eta / \widehat{\mathrm{se}}(\hat\eta). }

For customary alpha, percentile bootstrap intervals are available by
resampling retained items with replacement and recomputing the customary
estimate.
}
\examples{
raters <- data.frame(
  r1 = c("A", "A", "B", "B", "C", "A"),
  r2 = c("A", "B", "B", "B", "C", "A"),
  r3 = c("A", "A", "B", "C", "C", "A"),
  stringsAsFactors = FALSE
)

fit <- krippendorff_alpha(raters, level = "nominal", na_method = "available")
print(fit)
summary(fit)
estimate(fit)
tidy(fit)
plot(fit)

}
\references{
Krippendorff, K. (2011/2013). Computing Krippendorff's alpha-reliability.

Hayes, A. F. and Krippendorff, K. (2007). Answering the call for a standard
reliability measure for coding data. \emph{Communication Methods and
Measures}, 1(1), 77-89.

Hughes, J. (2024). Toward improved inference for Krippendorff's Alpha
agreement coefficient. \emph{Journal of Statistical Planning and
Inference}, 233, 106170.
}
\seealso{
\code{\link[=multirater_kappa]{multirater_kappa()}} for nominal multi-rater kappa;
\code{\link[=gwet_ac]{gwet_ac()}} for AC1/AC2 agreement coefficients.
}
\author{
Thiago de Paula Oliveira
}
