ccc: Pairwise Lin's concordance correlation coefficient

Description

Computes all pairwise Lin's Concordance Correlation Coefficients (CCC) from the numeric columns of a matrix or data frame. CCC measures both precision (Pearson correlation) and accuracy (closeness to the 45-degree line). This function is backed by a high-performance 'C++' implementation.

Lin's CCC quantifies the concordance between a new test/measurement and a gold-standard for the same variable. Like a correlation, CCC ranges from -1 to 1 with perfect agreement at 1, and it cannot exceed the absolute value of the Pearson correlation between variables. It can be legitimately computed even with small samples (e.g., 10 observations), and results are often similar to intraclass correlation coefficients. CCC provides a single summary of agreement, but it may not capture systematic bias; a Bland–Altman plot (differences vs. means) is recommended to visualize bias, proportional trends, and heteroscedasticity (see bland_altman).

Usage

ccc(data, ci = FALSE, conf_level = 0.95, verbose = FALSE)
# S3 method for ccc
print(x, digits = 4, ci_digits = 4, show_ci = c("auto", "yes", "no"), ...)
# S3 method for ccc
summary(
  object,
  digits = 4,
  ci_digits = 2,
  show_ci = c("auto", "yes", "no"),
  ...
)
# S3 method for summary.ccc
print(x, ...)
# S3 method for ccc
plot(
  x,
  title = "Lin's Concordance Correlation Heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  ...
)

Value

A symmetric numeric matrix with class "ccc" and attributes:

method: The method used ("Lin's concordance")
description: Description string

If ci = FALSE, returns matrix of class "ccc". If ci = TRUE, returns a list with elements: est, lwr.ci, upr.ci.

For summary.ccc, a data frame with columns method1, method2, estimate and (optionally) lwr, upr.

Arguments

data

A numeric matrix or data frame with at least two numeric columns. Non-numeric columns will be ignored.

ci

Logical; if TRUE, return lower and upper confidence bounds

conf_level

Confidence level for CI, default = 0.95

verbose

Logical; if TRUE, prints how many threads are used

x

An object of class "ccc" (either a matrix or a list with CIs).

digits

Integer; decimals for CCC estimates (default 4).

ci_digits

Integer; decimals for CI bounds (default 2).

show_ci

One of "auto", "yes", "no".

"auto" (default): include CI columns only if the object has non-NA CIs.
"yes": always include CI columns (may contain NA).
"no": never include CI columns.

...

Passed to ggplot2::theme().

object

A "ccc" or "ccc_ci" object to summarize.

title

Title for the plot.

low_color

Color for low CCC values.

high_color

Color for high CCC values.

mid_color

Color for mid CCC values.

value_text_size

Text size for CCC values in the heatmap.

ci_text_size

Text size for confidence intervals.

Author

Thiago de Paula Oliveira

Details

Lin's CCC is defined as $$ \rho_c \;=\; \frac{2\,\mathrm{cov}(X, Y)} {\sigma_X^2 + \sigma_Y^2 + (\mu_X - \mu_Y)^2}, $$ where $\mu_X,\mu_Y$ are the means, $\sigma_X^2,\sigma_Y^2$ the variances, and $\mathrm{cov}(X,Y)$ the covariance. Equivalently, $$ \rho_c \;=\; r \times C_b, \qquad r \;=\; \frac{\mathrm{cov}(X,Y)}{\sigma_X \sigma_Y}, \quad C_b \;=\; \frac{2 \sigma_X \sigma_Y} {\sigma_X^2 + \sigma_Y^2 + (\mu_X - \mu_Y)^2}. $$ Hence $|\rho_c| \le |r| \le 1$, $\rho_c = r$ iff $\mu_X=\mu_Y$ and $\sigma_X=\sigma_Y$, and $\rho_c=1$ iff, in addition, $r=1$. CCC is symmetric in $(X,Y)$ and penalises both location and scale differences; unlike Pearson's $r$, it is not invariant to affine transformations that change means or variances.

When ci = TRUE, large-sample confidence intervals for $\rho_c$ are returned for each pair (delta-method approximation). For speed, CIs are omitted when ci = FALSE.

If either variable has zero variance, $\rho_c$ is undefined and NA is returned for that pair (including the diagonal).

Missing values are not allowed; inputs must be numeric with at least two distinct non-missing values per column.

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.

Bland J, Altman D (1986). Statistical methods for assessing agreement between two methods of clinical measurement. The Lancet 327: 307-310.

Examples

Run this code

# Example with multivariate normal data
Sigma <- matrix(c(1, 0.5, 0.3,
                  0.5, 1, 0.4,
                  0.3, 0.4, 1), nrow = 3)
mu <- c(0, 0, 0)
set.seed(123)
mat_mvn <- MASS::mvrnorm(n = 100, mu = mu, Sigma = Sigma)
result_mvn <- ccc(mat_mvn)
print(result_mvn)
summary(result_mvn)
plot(result_mvn)

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

Run the code above in your browser using DataLab