% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multirater_kappa.R
\name{multirater_kappa}
\alias{multirater_kappa}
\alias{print.multirater_kappa}
\alias{summary.multirater_kappa}
\alias{print.summary.multirater_kappa}
\alias{plot.multirater_kappa}
\title{Multi-Rater Kappa for Nominal Ratings}
\usage{
multirater_kappa(
  data,
  levels = NULL,
  input = c("ratings", "counts"),
  method = c("fleiss", "randolph"),
  exact = FALSE,
  na_method = c("error", "complete", "available"),
  min_raters = 2L,
  by_category = FALSE,
  ci = FALSE,
  p_value = FALSE,
  conf_level = 0.95,
  se_method = c("asymptotic", "jackknife", "none"),
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE,
  ...
)

\method{print}{multirater_kappa}(x, digits = 4, show_by_category = FALSE, ...)

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

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

\method{plot}{multirater_kappa}(
  x,
  type = c("agreement_map", "estimate", "item_agreement", "category_proportion",
    "by_category"),
  bins = 30L,
  ...
)
}
\arguments{
\item{data}{Input ratings or counts data.
For \code{input = "ratings"}, rows are items/subjects and columns are
raters/classifiers. For \code{input = "counts"}, rows are items/subjects,
columns are categories, and values are counts of raters assigning that
category to that item.}

\item{levels}{Optional explicit category labels. For nominal multi-rater
kappa, category order is not used in the estimator itself, but explicit
levels are useful when unobserved categories should be retained in the
output. If factor columns are mixed with non-factor columns, \code{levels}
must be supplied to avoid ambiguous implicit ordering.}

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

\item{method}{One of \code{"fleiss"} (fixed-marginal multi-rater kappa) or
\code{"randolph"} (free-marginal multi-rater kappa).}

\item{exact}{Logical; if \code{TRUE}, use the exact Fleiss fixed-marginal
variant. This is available only for \code{input = "ratings"} with
complete item-by-rater data and \code{method = "fleiss"}.}

\item{na_method}{Missing-data rule for \code{input = "ratings"}.
\code{"error"} rejects missing ratings. \code{"complete"} removes any item
with one or more missing ratings. \code{"available"} retains items with at
least \code{min_raters} observed ratings and allows the number of raters to
vary by item. For \code{input = "counts"}, missing counts are not allowed.}

\item{min_raters}{Minimum number of observed ratings required for an item to
be retained when \code{na_method = "available"} or when
\code{input = "counts"} rows are filtered by total raters. Must be at
least \code{2}.}

\item{by_category}{Logical; if \code{TRUE}, attach category-wise kappas based
on target-vs-other binary collapses of the category count matrix.}

\item{ci}{Logical; if \code{TRUE}, attach confidence intervals using the
selected \code{se_method}.}

\item{p_value}{Logical; if \code{TRUE}, attach z statistics and two-sided
p-values using the selected \code{se_method}.}

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

\item{se_method}{Standard-error method. \code{"asymptotic"} uses the
closed-form large-sample variance for the standard non-exact Fleiss kappa
when a common number of raters is available. \code{"jackknife"} uses
leave-one-item-out jackknife inference. \code{"none"} disables
inferential quantities and may not be combined with \code{ci = TRUE} or
\code{p_value = TRUE}. When inferential quantities are requested and
\code{se_method} is left at its default, \code{multirater_kappa()}
automatically falls back to \code{"jackknife"} if asymptotic inference is
unavailable for the chosen estimator/data combination. \code{se_method}
and \code{conf_level} are validated only when \code{ci} or \code{p_value}
requests inferential output.}

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

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

\item{...}{Unused.}

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

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

\item{show_by_category}{Logical; whether to print the attached category-wise
kappa table when available.}

\item{object}{A \code{multirater_kappa} object.}

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

\item{topn}{Optional number of leading/trailing rows 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{"agreement_map"}, \code{"estimate"}, \code{"item_agreement"},
\code{"category_proportion"}, or \code{"by_category"}.}

\item{bins}{Integer number of bins retained for compatibility; currently
unused by the default item-agreement profile plot.}
}
\value{
A one-row data frame with class
\code{c("multirater_kappa", "agreement_result", "data.frame")}. The object
carries estimator metadata and diagnostics in attributes, and may also
attach category-wise binary-collapsed results in
\code{attr(x, "by_category")}.
}
\description{
Estimates panel-level chance-corrected agreement among multiple raters
assigning items to nominal categories.
}
\details{
\code{multirater_kappa()} returns one panel-level agreement coefficient, not a
pairwise matrix. Fleiss' kappa is the default fixed-marginal estimator:
\deqn{\kappa = \frac{\bar P - P_e}{1 - P_e},}
where \eqn{\bar P} is the mean item-level agreement and
\eqn{P_e = \sum_j p_j^2} uses the pooled marginal category proportions.

Randolph's free-marginal alternative replaces the expected agreement with
\eqn{P_e = 1 / K}. This function is for nominal categories and does not use
category ordering. Use \code{\link[=weighted_kappa]{weighted_kappa()}} for two-rater ordered-category
agreement and \code{\link[=cohen_kappa]{cohen_kappa()}} for two-rater nominal agreement.

When \code{exact = TRUE}, the exact Fleiss fixed-marginal estimate requires
the original item-by-rater rating matrix. In \pkg{matrixCorr}, closed-form
asymptotic inference is only available for the standard non-exact Fleiss
estimator with a common number of raters per item. In other settings, use
\code{se_method = "jackknife"} when inferential quantities are needed.

With \code{input = "ratings"} and \code{na_method = "available"}, the
implementation supports unbalanced item-specific numbers of raters as a
generalisation beyond the strict equal-rater Fleiss setting. The returned
diagnostics record the observed per-item rater counts.

\strong{Confidence intervals and standard errors.}
Two inference paths are implemented.

If \code{se_method = "jackknife"}, the method computes leave-one-item-out
estimates \eqn{\hat\kappa_{(-1)},\ldots,\hat\kappa_{(-m)}} over the
\eqn{m} retained items and forms
\deqn{ \bar\kappa_{(.)} = \frac{1}{m}\sum_{i=1}^m \hat\kappa_{(-i)}, }
\deqn{ \widehat{\mathrm{Var}}_{\mathrm{JK}}(\hat\kappa)
      \;=\;
      \frac{m-1}{m}\sum_{i=1}^m
      \left(\hat\kappa_{(-i)} - \bar\kappa_{(.)}\right)^2. }
The standard error is
\eqn{\widehat{\mathrm{se}}(\hat\kappa)=
\sqrt{\widehat{\mathrm{Var}}_{\mathrm{JK}}(\hat\kappa)}} and the CI is
\deqn{ \hat\kappa \pm z_{1-\alpha/2}\,\widehat{\mathrm{se}}(\hat\kappa), }
truncated to \eqn{[-1, 1]}.

If \code{se_method = "asymptotic"}, the closed-form variance is available
only for the standard non-exact Fleiss estimator
with a common number of raters per item. Let \eqn{m} be the number of items,
\eqn{n} the common number of raters, \eqn{p_j} the pooled category
proportions, and define
\deqn{ S = \sum_j p_j(1-p_j), \qquad
       C = \sum_j p_j(1-p_j)(1-2p_j). }
Then the variance estimator is
\deqn{ \widehat{\mathrm{Var}}(\hat\kappa)
      \;=\;
      \frac{2\,(S^2 - C)}{S^2\,m\,n\,(n-1)}. }
The standard error and CI are then obtained from the same Wald form
above and truncated to \eqn{[-1, 1]}. When asymptotic inference is
unavailable and inferential output is requested with the default setting,
\code{multirater_kappa()} automatically falls back to the jackknife path.
}
\examples{
raters <- data.frame(
  r1 = c("A", "A", "B", "C", "A", "B"),
  r2 = c("A", "B", "B", "C", "A", "B"),
  r3 = c("A", "A", "B", "B", "A", "C"),
  stringsAsFactors = FALSE
)

fit <- multirater_kappa(raters)
print(fit)
summary(fit)
estimate(fit)
tidy(fit)
# The default plot is an item-by-category agreement map.
# Rows are items, ordered from stronger to weaker item-level agreement.
# Columns are categories. Each tile shows how many raters assigned that
# category to that item, and darker fill means a larger share of raters
# chose that category for that item.
plot(fit)

}
\references{
Fleiss, J. L. (1971). Measuring nominal scale agreement among many raters.
\emph{Psychological Bulletin}, 76, 378-382. \doi{10.1037/h0031619}

Randolph, J. J. (2005). Free-Marginal Multirater Kappa: An Alternative to
Fleiss' Fixed-Marginal Multirater Kappa.
}
\seealso{
\code{\link[=cohen_kappa]{cohen_kappa()}} for unweighted two-rater nominal agreement;
\code{\link[=weighted_kappa]{weighted_kappa()}} for two-rater ordered-category agreement.
}
\author{
Thiago de Paula Oliveira
}
