% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gwet_ac.R
\name{gwet_ac}
\alias{gwet_ac}
\alias{summary.gwet_ac}
\alias{print.summary.gwet_ac}
\alias{print.gwet_ac}
\alias{plot.gwet_ac}
\title{Gwet's AC1 and AC2 Agreement Coefficients}
\usage{
gwet_ac(
  data,
  y = NULL,
  weights = c("unweighted", "linear", "quadratic", "ordinal", "radical", "ratio",
    "circular", "bipolar"),
  levels = NULL,
  input = c("pairwise", "ratings", "counts"),
  na_method = c("error", "pairwise", "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),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  verbose = FALSE,
  ...
)

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

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

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

\method{plot}{gwet_ac}(
  x,
  title = NULL,
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  type = c("agreement_map", "estimate", "item_agreement", "category_proportion",
    "by_category"),
  bins = 30L,
  ...
)
}
\arguments{
\item{data}{Input data. If \code{y} is supplied, \code{data} is the first
rater vector. Otherwise:
for \code{input = "pairwise"}, rows are units and columns are raters;
for \code{input = "ratings"}, rows are items and columns are raters;
for \code{input = "counts"}, rows are items and columns are categories
containing rater counts.}

\item{y}{Optional second rater vector for scalar two-rater agreement.}

\item{weights}{Weight specification. \code{"unweighted"} yields AC1.
Weighted schemes yield AC2. Supported built-in schemes are
\code{"linear"}, \code{"quadratic"}, \code{"ordinal"},
\code{"radical"}, \code{"ratio"}, \code{"circular"}, and
\code{"bipolar"}. A custom numeric agreement-weight matrix may also be
supplied. Character schemes must be supplied as a single value.}

\item{levels}{Optional explicit category labels. This is mainly useful when
unused categories should still be retained in the calculation, and is the
recommended way to define ordering for ordinal AC2 weights.}

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

\item{na_method}{Missing-data rule. For scalar two-rater and pairwise matrix
modes, \code{"error"} rejects missing values, \code{"complete"} applies
listwise deletion in matrix mode, and \code{"pairwise"} uses complete
pairs within each pair of raters. For \code{input = "ratings"},
\code{"available"} retains items with at least \code{min_raters}
observed ratings. For \code{input = "counts"}, missing values are not
allowed.}

\item{min_raters}{Minimum number of observed ratings required for an item to
be retained in panel mode. Must be at least \code{2}.}

\item{by_category}{Logical; if \code{TRUE}, attach one-vs-all category-wise
AC1 estimates for panel-level fits. This is available only for the
unweighted coefficient.}

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

\item{p_value}{Logical; if \code{TRUE}, attach test statistics and p-values.}

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

\item{se_method}{Standard-error method. \code{"asymptotic"} uses the
analytic large-sample formula. \code{"jackknife"} is retained as an
alternative for panel-level fits. \code{"none"} disables inferential
output.}

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

\item{output}{One of \code{"matrix"}, \code{"sparse"}, or
\code{"edge_list"} for pairwise matrix mode.}

\item{threshold}{Numeric threshold used only for thresholded pairwise matrix
output.}

\item{diag}{Logical; include diagonal entries in thresholded pairwise matrix
output.}

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

\item{...}{Unused.}

\item{object}{A \code{gwet_ac} 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 \code{gwet_ac} 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{show_by_category}{Logical; whether to print attached category-wise
panel results when available.}

\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 estimate labels in matrix plots.}

\item{ci_text_size}{Text size for CI labels in matrix plots.}

\item{show_value}{Logical; whether to print estimate and CI labels.}

\item{type}{Plot type for panel-level fits: \code{"agreement_map"},
\code{"estimate"}, \code{"item_agreement"}, \code{"category_proportion"},
or \code{"by_category"}.}

\item{bins}{Integer number of bins retained for compatibility with the
panel-level item-agreement plot.}
}
\value{
If \code{y} is supplied, a scalar numeric object of class
\code{c("gwet_ac", "numeric")}. If \code{input = "pairwise"}, a
\code{corr_result}. If \code{input} is \code{"ratings"} or \code{"counts"},
a one-row data frame with class
\code{c("gwet_ac", "agreement_result", "data.frame")}.
}
\description{
Estimates Gwet's chance-corrected agreement coefficient for either
unweighted nominal agreement (AC1) or weighted agreement (AC2) in two-rater
pairwise form or panel-level multi-rater form.
}
\details{
For two raters, let \eqn{w_{ab}} denote the agreement weight for cell
\eqn{(a,b)}, \eqn{p_{ab}} the cell proportion, and
\eqn{\pi_k = (p_{k+} + p_{+k})/2}. Then
\deqn{ P_o = \sum_{a,b} w_{ab} p_{ab}, }
\deqn{ P_e =
       \frac{\sum_{a,b} w_{ab}}{q(q-1)}
       \sum_{k=1}^q \pi_k(1-\pi_k), }
and
\deqn{ AC = \frac{P_o - P_e}{1 - P_e}. }
With identity weights \eqn{w_{ab} = 1(a=b)} this is Gwet's AC1, the
nominal-agreement coefficient. With non-identity agreement weights this is
Gwet's AC2, which extends the same chance-correction idea to ordered or
partially creditable disagreement by letting near disagreements receive
larger agreement weights than distant disagreements.

\strong{Category ordering for weighted AC2.} Built-in weighted schemes use
the category order to define near and distant disagreements. If
\code{levels} is supplied, that order is used. Otherwise, factor inputs use
their factor levels, numeric/integer/logical inputs use sorted observed
values, character inputs use first-observed order, and counts inputs use
column order (or \code{levels}, when supplied). For ordinal analyses,
supplying \code{levels} is recommended whenever first-observed character
order is not the intended scale order.

For panel-level counts, if \eqn{r_{ik}} is the number of raters assigning
item \eqn{i} to category \eqn{k}, \eqn{r_i = \sum_k r_{ik}}, and
\eqn{w_{kl}} is the agreement-weight matrix, then the item-level agreement is
\deqn{ A_i =
       \frac{1}{r_i(r_i-1)}
       \sum_k r_{ik}\left(\sum_l w_{kl}r_{il}-1\right). }
The observed agreement is the mean of \eqn{A_i} over retained items. The
chance term uses the average item-wise category proportions
\eqn{\pi_k = m^{-1}\sum_i r_{ik}/r_i}, where \eqn{m} is the number of
retained items.

\strong{Confidence intervals and inference.}

The primary inferential path is the analytic large-sample method. For two
raters, define
\deqn{ s_{ab}
       =
       w_{ab}
       -
       \frac{2(1-AC)\sum_{u,v} w_{uv}}{q(q-1)}
       \left(1 - \frac{\pi_a + \pi_b}{2}\right). }
The backend variance estimator is
\deqn{ \widehat{\mathrm{Var}}(\widehat{AC})
       =
       \frac{1}{n(1-P_e)^2}
       \left[
       \sum_{a,b} p_{ab} s_{ab}^2
       -
       \left\{P_o - 2(1-AC)P_e\right\}^2
       \right], }
where \eqn{n} is the number of complete paired ratings.

For panel-level counts, write
\deqn{ AC_i = \frac{A_i - P_e}{1 - P_e}, }
and define the item-specific chance term
\deqn{ P_{e,i}
       =
       \frac{\sum_{k,l} w_{kl}}{q(q-1)}
       \sum_{k=1}^q \frac{r_{ik}}{r_i}(1-\pi_k). }
The asymptotic linearised contribution used by the backend is
\deqn{ \xi_i
       =
       AC_i
       -
       \frac{2(1-AC)}{1-P_e}(P_{e,i} - P_e), }
giving
\deqn{ \widehat{\mathrm{Var}}(\widehat{AC})
       =
       \frac{1}{m(m-1)}
       \sum_{i=1}^m (\xi_i - AC)^2, }
where \eqn{m} is the number of retained items.

The reported standard error is
\eqn{\widehat{\mathrm{se}}(\widehat{AC}) =
\sqrt{\widehat{\mathrm{Var}}(\widehat{AC})}}, and the confidence interval is
the t interval
\deqn{ \widehat{AC} \pm t_{1-\alpha/2,\nu}\,
       \widehat{\mathrm{se}}(\widehat{AC}), }
truncated to \eqn{[-1,1]}. Here \eqn{\nu = n-1} for the two-rater path and
\eqn{\nu = m-1} for panel-level asymptotic inference. The reported test
statistic is the corresponding t ratio for \eqn{H_0: AC = 0}. For
panel-level fits, \code{se_method = "jackknife"} remains available as a
second option, using the leave-one-item-out variance
\deqn{ \widehat{\mathrm{Var}}_{\mathrm{JK}}(\widehat{AC})
       =
       \frac{m-1}{m}
       \sum_{i=1}^m
       \left(\widehat{AC}_{(-i)} - \overline{AC}_{(-\cdot)}\right)^2. }
}
\examples{
x <- c("A", "A", "B", "B", "A", "C")
y <- c("A", "B", "B", "B", "A", "C")
gwet_ac(x, y)
gwet_ac(x, y, weights = "quadratic", levels = c("A", "B", "C"))

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_pw <- gwet_ac(raters)
fit_panel <- gwet_ac(raters, input = "ratings")
print(fit_pw)
print(fit_panel)
estimate(fit_pw)
tidy(fit_pw)
tidy(fit_panel)

}
\references{
Gwet, K. L. (2008). Computing inter-rater reliability and its variance in
the presence of high agreement. \emph{British Journal of Mathematical and
Statistical Psychology}, 61, 29-48. \doi{10.1348/000711006X126600}
}
\seealso{
\code{\link[=cohen_kappa]{cohen_kappa()}} for two-rater nominal kappa;
\code{\link[=multirater_kappa]{multirater_kappa()}} for panel-level nominal kappa;
\code{\link[=weighted_kappa]{weighted_kappa()}} for weighted Cohen-type agreement.
}
\author{
Thiago de Paula Oliveira
}
