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.
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
)# S3 method for cia
summary(object, digits = 4, ci_digits = 3, ...)
# S3 method for cia
print(
x,
digits = 4,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
...
)
# S3 method for summary.cia
print(
x,
digits = NULL,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
...
)
# S3 method for cia
plot(
x,
title = NULL,
low_color = "indianred1",
high_color = "steelblue1",
mid_color = "white",
value_text_size = 4,
ci_text_size = 3,
show_value = TRUE,
...
)
# S3 method for cia_ci
print(x, ...)
For scope = "overall", a one-row data frame with class
c("cia_overall", "cia", "data.frame"). For scope = "pairwise" and
ci = FALSE, a dense matrix-style object using the package's standard
correlation-result infrastructure. For scope = "pairwise" and ci = TRUE,
a list with elements est, lwr.ci, and upr.ci, classed as
c("cia", "cia_ci").
A data frame in long format.
Character scalar naming the numeric measurement column.
Character scalar naming the subject/unit identifier column.
Character scalar naming the method/device/rater column.
Character scalar naming the replicate identifier within each subject-method cell.
Optional character scalar naming the reference method. When
NULL (default), the no-reference CIA is estimated.
One of "pairwise" or "overall". "pairwise" returns the
two-method
CIA for each method pair, or the reference-scaled CIA for each
method-versus-reference comparison when reference is supplied.
"overall" returns one CIA coefficient across all retained methods.
One of "mom_unconstrained" or "vc_constrained".
"mom_unconstrained" is the literal raw method-of-moments CIA ratio and
may exceed 1. "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.
Logical; if TRUE, attach confidence intervals using the selected
inference method.
Confidence level used when ci = TRUE. Default is 0.95.
One of "delta", "bootstrap", or "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.
Number of subject-bootstrap resamples when ci = TRUE and
inference = "bootstrap".
Optional positive integer seed for reproducible bootstrap resampling.
Integer >= 1. Number of OpenMP threads passed to the C++ backend.
Logical; if TRUE, emit short progress messages.
A cia object.
Integer; number of decimal places for estimates.
Integer; number of decimal places for confidence limits.
Additional arguments passed to downstream print helpers.
A cia object.
Optional preview row threshold.
Optional number of leading/trailing rows to show when truncated.
Optional maximum number of visible columns.
Optional display width.
One of "yes" or "no".
Optional plot title.
Color used for lower agreement values.
Color used for higher agreement values.
Midpoint color for pairwise heatmaps.
Text size for overlaid estimate labels.
Text size for CI labels.
Logical; whether to overlay numeric values.
Thiago de Paula Oliveira
Let Y_ijk denote replicate k on subject i measured by method j.
Without a reference method, CIA is defined by $$ \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 J, CIA is defined by
$$
\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 X and Y. For each eligible
subject i, define
$$
G_{1i} = \mathrm{mean}\{(X_{ik} - X_{ik'})^2\},
$$
$$
G_{2i} = \mathrm{mean}\{(Y_{il} - Y_{il'})^2\},
$$
$$
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 \(\bar G_1\), \(\bar G_2\), and \(\bar G_3\) denote the averages
of these subject-level quantities across eligible subjects. Then the
no-reference pairwise estimator is
$$
\widehat{\mathrm{CIA}}_{XY}^{\mathrm{raw}} =
\frac{(\bar G_1 + \bar G_2)/2}{\bar G_3},
$$
and the reference pairwise estimator is
$$
\widehat{\mathrm{CIA}}_{XR}^{\mathrm{raw}} = \frac{\bar G_1}{\bar G_3},
$$
where X is the reference method.
For overall CIA, the current implementation follows the balanced replicated
formulas in the cited papers. This requires n common subjects, J
retained methods, and the same replicate count K >= 2 in every retained
subject-method cell. If the data are not balanced in this sense,
scope = "overall" returns an informative error rather than using an
approximation.
Write \(\bar Y_{ij}\) for the mean of the K replicates on subject i
and method j. Define the within-method mean square
$$
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 $$ A_{i\cdot} = \frac{1}{J} \sum_{j=1}^{J} A_{ij}, $$ the subject-wide mean $$ \bar Y_{i\cdot\cdot} = \frac{1}{J} \sum_{j=1}^{J} \bar Y_{ij}, $$ and the subject-level denominator $$ 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 \(\bar A = n^{-1}\sum_i A_{i\cdot}\) and \(\bar B = n^{-1}\sum_i B_{Ni}\), the overall no-reference estimator is $$ \widehat{\mathrm{CIA}}_{N}^{\mathrm{raw}} = \frac{\bar A}{\bar B}. $$
For the reference overall estimator, let method R be the retained
reference method. Define
$$
A_{iR} = A_{i,R}
$$
and
$$
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 \(\bar A_R = n^{-1}\sum_i A_{iR}\) and
\(\bar B_R = n^{-1}\sum_i B_{Ri}\), the overall reference estimator is
$$
\widehat{\mathrm{CIA}}_{R}^{\mathrm{raw}} = \frac{2 \bar A_R}{\bar B_R}.
$$
Two estimators are available. estimator = "mom_unconstrained" reports the
raw ratio estimator directly. estimator = "vc_constrained" applies the
non-negative variance-component boundary from the cited papers. In the
no-reference setting this uses
\(\hat\tau^2_{\mathrm{raw}} = \bar B - \bar A\), and in the reference
setting it uses \(\hat\tau^2_{\mathrm{raw}} = \bar B_R/2 - \bar A_R\).
The constrained estimator then sets
\(\hat\tau^2 = \max(\hat\tau^2_{\mathrm{raw}}, 0)\) and reports
\(\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 IEC <= 2.4948 corresponds to CIA >= 0.445, and
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 attr(x, "diagnostics").
Barnhart HX, Kosinski AS, Haber M. (2007). Assessing individual agreement. Journal of Biopharmaceutical Statistics, 17(4), 697-719. tools:::Rd_expr_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. 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. Computer Methods and Programs in Biomedicine.
ccc, ba, and prob_agree.
cia() answers the question "Are methods interchangeable for
individual subjects once within-method replicate disagreement is taken into
account?". In contrast, ccc() answers "How well do two paired
measurements agree overall, combining correlation with location/scale
agreement?".
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)
Run the code above in your browser using DataLab