ccc_rm_ustat: Repeated-Measures Lin's Concordance Correlation Coefficient (CCC)

Description

Computes all pairwise Lin's Concordance Correlation Coefficients (CCC) across multiple methods (L $\geq$ 2) for repeated-measures data. Each subject must be measured by all methods across the same set of time points or replicates.

CCC measures both accuracy (how close measurements are to the line of equality) and precision (Pearson correlation). Confidence intervals are optionally computed using a U-statistics-based estimator with Fisher's Z transformation

Usage

ccc_rm_ustat(
  data,
  response,
  subject,
  method,
  time = NULL,
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE,
  Dmat = NULL,
  delta = 1
)

Value

If ci = FALSE, a symmetric matrix of class "ccc" (estimates only). If ci = TRUE, a list of class "ccc", "ccc_ci" with elements:

est: CCC estimate matrix
lwr.ci: Lower bound matrix
upr.ci: Upper bound matrix

Arguments

data

A data frame containing the repeated-measures dataset.

response

Character. Name of the numeric outcome column.

subject

Character. Column identifying subjects. Every subject must have measurements from all methods (and times, when supplied); rows with incomplete {subject, time, method} coverage are dropped per pair.

method

Character. Name of the method column (factor with L $\geq$ 2 levels).

time

Character or NULL. Name of the time/repetition column. If NULL, one time point is assumed.

ci

Logical. If TRUE, returns confidence intervals (default FALSE).

conf_level

Confidence level for CI (default 0.95).

n_threads

Integer ($\geq$ 1). Number of OpenMP threads to use for computation. Defaults to getOption("matrixCorr.threads", 1L).

verbose

Logical. If TRUE, prints diagnostic output (default FALSE).

Dmat

Optional numeric weight matrix (T $\times$ T) for timepoints. Defaults to identity.

delta

Numeric. Exponent applied to the absolute pointwise differences between two method trajectories before the time-weighted quadratic form is evaluated. Internally, the function forms $v_t = |X_t - Y_t|^\delta$ and then computes $v^\top D v$, where $D$ is Dmat. Therefore, when Dmat is diagonal:

delta = 1 (default) gives the standard quadratic repeated-measures CCC distance, $(X - Y)^\top D (X - Y)$.
delta = 2 gives a fourth-power loss, which puts stronger emphasis on large disagreements.
delta = 0 gives a binary disagreement indicator before aggregation, analogous to a repeated-measures kappa-type distance.

In most applications, delta = 1 should be used because it matches the usual quadratic distance used in repeated-measures CCC.

Author

Thiago de Paula Oliveira

Details

This function computes pairwise Lin's Concordance Correlation Coefficient (CCC) between methods in a repeated-measures design using a U-statistics-based nonparametric estimator proposed by Carrasco et al. (2013). It is computationally efficient and robust, particularly for large-scale or balanced longitudinal designs.

Lin's CCC is defined as $$ \rho_c = \frac{2 \cdot \mathrm{cov}(X, Y)}{\sigma_X^2 + \sigma_Y^2 + (\mu_X - \mu_Y)^2} $$ where:

$X$ and $Y$ are paired measurements from two methods.
$\mu_X$, $\mu_Y$ are means, and $\sigma_X^2$, $\sigma_Y^2$ are variances.

U-statistics Estimation

For repeated measures across $T$ time points and $n$ subjects we assume

all $n(n-1)$ pairs of subjects are considered to compute a U-statistic estimator for within-method and cross-method distances.
if delta > 0, pairwise distances are raised to a power before applying a time-weighted kernel matrix $D$.
if delta = 0, the method reduces to a version similar to a repeated-measures kappa.

Confidence Intervals

Confidence intervals are constructed using a Fisher Z-transformation of the CCC. Specifically,

The CCC is transformed using $Z = 0.5 \log((1 + \rho_c) / (1 - \rho_c))$.
Standard errors are computed from the asymptotic variance of the U-statistic.
Normal-based intervals are computed on the Z-scale and then back-transformed to the CCC scale.

Assumptions

The design must be balanced, where all subjects must have complete observations for all methods and time points.
The method is nonparametric and does not require assumptions of normality or linear mixed effects.
Weights (Dmat) allow differential importance of time points.

For unbalanced or complex hierarchical data (e.g., missing timepoints, covariate adjustments), consider using ccc_rm_reml, which uses a variance components approach via linear mixed models.

References

Lin L (1989). A concordance correlation coefficient to evaluate reproducibility. Biometrics, 45: 255-268.

Lin L (2000). A note on the concordance correlation coefficient. Biometrics, 56: 324-325.

Carrasco JL, Jover L (2003). Estimating the concordance correlation coefficient: a new approach. Computational Statistics & Data Analysis, 47(4): 519-539.

Examples

Run this code

set.seed(123)
df <- expand.grid(subject = 1:10,
                  time = 1:2,
                  method = c("A", "B", "C"))
df$y <- rnorm(nrow(df), mean = match(df$method, c("A", "B", "C")), sd = 1)

# CCC matrix (no CIs)
ccc1 <- ccc_rm_ustat(df, response = "y", subject = "subject",
                            method = "method", time = "time")
print(ccc1)
summary(ccc1)
plot(ccc1)

# With confidence intervals
ccc2 <- ccc_rm_ustat(df, response = "y", subject = "subject",
                            method = "method", time = "time", ci = TRUE)
print(ccc2)
summary(ccc2)
estimate(ccc2)
tidy(ccc2)
ci(ccc2)
confint(ccc2)
plot(ccc2)

# Interactive viewing (requires shiny)
if (interactive() && requireNamespace("shiny", quietly = TRUE)) {
  view_corr_shiny(ccc2)
}

#------------------------------------------------------------------------
# Choosing delta based on distance sensitivity
#------------------------------------------------------------------------
# Standard quadratic RM-CCC distance: (X - Y)' D (X - Y)
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 1)

# Fourth-power loss when D is diagonal: emphasises large disagreements
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 2)
# Binary disagreement indicator before aggregation
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 0)

Run the code above in your browser using DataLab