% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cia.R
\name{cia}
\alias{cia}
\alias{summary.cia}
\alias{print.cia}
\alias{print.summary.cia}
\alias{plot.cia}
\alias{print.cia_ci}
\title{Coefficient of Individual Agreement}
\usage{
cia(
  data,
  response,
  subject,
  method,
  replicate,
  reference = NULL,
  scope = c("pairwise", "overall"),
  estimator = c("mom_unconstrained", "vc_constrained"),
  ci = FALSE,
  conf_level = 0.95,
  inference = c("delta", "bootstrap", "none"),
  B = 1000L,
  seed = NULL,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE
)

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

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

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

\method{plot}{cia}(
  x,
  title = NULL,
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)

\method{print}{cia_ci}(x, ...)
}
\arguments{
\item{data}{A data frame in long format.}

\item{response}{Character scalar naming the numeric measurement column.}

\item{subject}{Character scalar naming the subject/unit identifier column.}

\item{method}{Character scalar naming the method/device/rater column.}

\item{replicate}{Character scalar naming the replicate identifier within each
subject-method cell.}

\item{reference}{Optional character scalar naming the reference method. When
\code{NULL} (default), the no-reference CIA is estimated.}

\item{scope}{One of \code{"pairwise"} or \code{"overall"}. \code{"pairwise"} returns the
two-method
CIA for each method pair, or the reference-scaled CIA for each
method-versus-reference comparison when \code{reference} is supplied.
\code{"overall"} returns one CIA coefficient across all retained methods.}

\item{estimator}{One of \code{"mom_unconstrained"} or \code{"vc_constrained"}.
\code{"mom_unconstrained"} is the literal raw method-of-moments CIA ratio and
may exceed 1. \code{"vc_constrained"} is a bounded package-level
variance-component variant that constrains the estimated inter-method
variance component to be non-negative before converting it back to CIA.}

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

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

\item{inference}{One of \code{"delta"}, \code{"bootstrap"}, or \code{"none"}. When
confidence intervals are requested, pairwise CIA uses a delta-method normal
interval by default and also supports subject-bootstrap percentile
intervals. For overall CIA, delta-method normal intervals are available for
the unconstrained moment estimator, and subject-bootstrap percentile
intervals are also available.}

\item{B}{Number of subject-bootstrap resamples when \code{ci = TRUE} and
\code{inference = "bootstrap"}.}

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

\item{n_threads}{Integer >= 1. Number of OpenMP threads passed to the C++
backend.}

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

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

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

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

\item{...}{Additional arguments passed to downstream print helpers.}

\item{x}{A \code{cia} 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}{Color used for lower agreement values.}

\item{high_color}{Color used for higher agreement values.}

\item{mid_color}{Midpoint color for pairwise heatmaps.}

\item{value_text_size}{Text size for overlaid estimate labels.}

\item{ci_text_size}{Text size for CI labels.}

\item{show_value}{Logical; whether to overlay numeric values.}
}
\value{
For \code{scope = "overall"}, a one-row data frame with class
\code{c("cia_overall", "cia", "data.frame")}. For \code{scope = "pairwise"} and
\code{ci = FALSE}, a dense matrix-style object using the package's standard
correlation-result infrastructure. For \code{scope = "pairwise"} and \code{ci = TRUE},
a list with elements \code{est}, \code{lwr.ci}, and \code{upr.ci}, classed as
\code{c("cia", "cia_ci")}.
}
\description{
\code{cia()} estimates the coefficient of individual agreement. CIA assesses
individual-level interchangeability by comparing between-method disagreement
with within-method replicate disagreement. Unlike CCC, CIA is not intended
to be driven by between-subject heterogeneity.

The estimator requires replicated readings within method. A data set with
one observation per subject per method is insufficient for CIA because the
within-method disagreement term cannot be estimated.
}
\details{
Let \code{Y_ijk} denote replicate \code{k} on subject \code{i} measured by method \code{j}.

Without a reference method, CIA is defined by
\deqn{
\mathrm{CIA}^N =
\frac{\sum_j E\{(Y_{ijk} - Y_{ijk'})^2\} / 2}
     {\sum_{j < j'} E\{(Y_{ij} - Y_{ij'})^2\} / (J - 1)}.
}

With a reference method \code{J}, CIA is defined by
\deqn{
\mathrm{CIA}^R =
\frac{E\{(Y_{iJk} - Y_{iJk'})^2\}}
     {\sum_{j=1}^{J-1} E\{(Y_{ij} - Y_{iJ})^2\} / (J - 1)}.
}

This implementation uses method-of-moments estimators built from
subject-level disagreement functions.

For pairwise CIA, consider two methods \code{X} and \code{Y}. For each eligible
subject \code{i}, define
\deqn{
G_{1i} = \mathrm{mean}\{(X_{ik} - X_{ik'})^2\},
}
\deqn{
G_{2i} = \mathrm{mean}\{(Y_{il} - Y_{il'})^2\},
}
\deqn{
G_{3i} = \mathrm{mean}\{(X_{ik} - Y_{il})^2\},
}
where the first two means are over all distinct within-method replicate
pairs and the third mean is over all cross-method replicate combinations.
Let \eqn{\bar G_1}, \eqn{\bar G_2}, and \eqn{\bar G_3} denote the averages
of these subject-level quantities across eligible subjects. Then the
no-reference pairwise estimator is
\deqn{
\widehat{\mathrm{CIA}}_{XY}^{\mathrm{raw}} =
\frac{(\bar G_1 + \bar G_2)/2}{\bar G_3},
}
and the reference pairwise estimator is
\deqn{
\widehat{\mathrm{CIA}}_{XR}^{\mathrm{raw}} = \frac{\bar G_1}{\bar G_3},
}
where \code{X} is the reference method.

For overall CIA, the current implementation follows the balanced replicated
formulas in the cited papers. This requires \code{n} common subjects, \code{J}
retained methods, and the same replicate count \code{K >= 2} in every retained
subject-method cell. If the data are not balanced in this sense,
\code{scope = "overall"} returns an informative error rather than using an
approximation.

Write \eqn{\bar Y_{ij}} for the mean of the \code{K} replicates on subject \code{i}
and method \code{j}. Define the within-method mean square
\deqn{
A_{ij} = \frac{\sum_{k=1}^{K} (Y_{ijk} - \bar Y_{ij})^2}{K - 1}.
}

For the no-reference overall estimator, define the subject-level within term
\deqn{
A_{i\cdot} = \frac{1}{J} \sum_{j=1}^{J} A_{ij},
}
the subject-wide mean
\deqn{
\bar Y_{i\cdot\cdot} = \frac{1}{J} \sum_{j=1}^{J} \bar Y_{ij},
}
and the subject-level denominator
\deqn{
B_{Ni} =
\frac{\sum_{j=1}^{J} (\bar Y_{ij} - \bar Y_{i\cdot\cdot})^2}{J - 1}
+ \left(1 - \frac{1}{K}\right) A_{i\cdot}.
}
With \eqn{\bar A = n^{-1}\sum_i A_{i\cdot}} and
\eqn{\bar B = n^{-1}\sum_i B_{Ni}}, the overall no-reference estimator is
\deqn{
\widehat{\mathrm{CIA}}_{N}^{\mathrm{raw}} = \frac{\bar A}{\bar B}.
}

For the reference overall estimator, let method \code{R} be the retained
reference method. Define
\deqn{
A_{iR} = A_{i,R}
}
and
\deqn{
B_{Ri} =
\frac{\sum_{j \ne R} (\bar Y_{ij} - \bar Y_{iR})^2}{J - 1}
+ \left(1 - \frac{1}{K}\right)
  \frac{\sum_{j \ne R} A_{ij}}{J - 1}
+ \left(1 - \frac{1}{K}\right) A_{iR}.
}
With \eqn{\bar A_R = n^{-1}\sum_i A_{iR}} and
\eqn{\bar B_R = n^{-1}\sum_i B_{Ri}}, the overall reference estimator is
\deqn{
\widehat{\mathrm{CIA}}_{R}^{\mathrm{raw}} = \frac{2 \bar A_R}{\bar B_R}.
}

Two estimators are available. \code{estimator = "mom_unconstrained"} reports the
raw ratio estimator directly. \code{estimator = "vc_constrained"} applies the
non-negative variance-component boundary from the cited papers. In the
no-reference setting this uses
\eqn{\hat\tau^2_{\mathrm{raw}} = \bar B - \bar A}, and in the reference
setting it uses \eqn{\hat\tau^2_{\mathrm{raw}} = \bar B_R/2 - \bar A_R}.
The constrained estimator then sets
\eqn{\hat\tau^2 = \max(\hat\tau^2_{\mathrm{raw}}, 0)} and reports
\eqn{\widehat{\mathrm{CIA}} = \widehat{\sigma}_W^2 /
(\widehat{\sigma}_W^2 + \hat\tau^2)} on the corresponding scale. This
applies the boundary on the implied inter-method variance component rather
than clamping CIA directly.

When confidence intervals are requested, pairwise CIA uses a large-sample
delta-method normal interval by default and also supports subject-bootstrap
percentile intervals. For overall CIA, delta-method normal intervals are
available for the unconstrained moment estimator, and subject-bootstrap
percentile intervals are also available.

High CIA indicates stronger individual agreement. The FDA individual
bioequivalence boundary \code{IEC <= 2.4948} corresponds to \code{CIA >= 0.445}, and
\code{CIA >= 0.8} is sometimes used as a stronger practical rule. Such thresholds
are context-dependent and are not hard-coded by this function.

Missing rows in the required columns are removed before estimation and the
counts are recorded in \code{attr(x, "diagnostics")}.
}
\examples{
set.seed(1)
subjects <- sprintf("s\%02d", 1:30)
methods <- c("A", "B", "C")
replicates <- sprintf("r\%02d", 1:20)
dat <- expand.grid(
  subject = subjects,
  method = methods,
  replicate = replicates,
  KEEP.OUT.ATTRS = FALSE,
  stringsAsFactors = FALSE
)
subject_effect <- stats::rnorm(length(subjects), sd = 3)
method_shift <- c(A = 0, B = 0.15, C = -0.10)
method_sd <- c(A = 0.45, B = 0.45, C = 0.30)
dat$value <- subject_effect[match(dat$subject, subjects)] +
  method_shift[dat$method] +
  stats::rnorm(nrow(dat), sd = method_sd[dat$method])

fit_overall <- cia(
  dat,
  response = "value",
  subject = "subject",
  method = "method",
  replicate = "replicate",
  scope = "overall"
)
print(fit_overall)
summary(fit_overall)
estimate(fit_overall)
tidy(fit_overall)
plot(fit_overall)

fit_pairwise <- cia(
  dat,
  response = "value",
  subject = "subject",
  method = "method",
  replicate = "replicate",
  scope = "pairwise"
)
print(fit_pairwise)
summary(fit_pairwise)
tidy(fit_pairwise)
plot(fit_pairwise)

}
\references{
Barnhart HX, Kosinski AS, Haber M. (2007). Assessing individual agreement.
\emph{Journal of Biopharmaceutical Statistics}, 17(4), 697-719.
\doi{10.1080/10543400701329489}

Barnhart HX, Haber M, Lokhnygina Y, Kosinski AS. (2007). Comparison of
concordance correlation coefficient and coefficient of individual agreement
in assessing agreement. \emph{Journal of Biopharmaceutical Statistics},
17(4), 721-738.

Pan Y, Gao J, Haber M, Barnhart HX. (2010). Estimation of coefficients of
individual agreement (CIA's) for quantitative and binary data using SAS and
R. \emph{Computer Methods and Programs in Biomedicine}.
}
\seealso{
\code{\link{ccc}}, \code{\link{ba}}, and \code{\link{prob_agree}}.
\code{cia()} answers the question "Are methods interchangeable for
individual subjects once within-method replicate disagreement is taken into
account?". In contrast, \code{ccc()} answers "How well do two paired
measurements agree overall, combining correlation with location/scale
agreement?".
}
\author{
Thiago de Paula Oliveira
}
