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 ba).

Usage

ccc(data, ci = FALSE, conf_level = 0.95, verbose = FALSE)
# S3 method for ccc
print(
  x,
  digits = 4,
  ci_digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
# S3 method for ccc
summary(
  object,
  digits = 4,
  ci_digits = 2,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
# S3 method for summary.ccc
print(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
# 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,
  show_value = TRUE,
  ...
)

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).
n: Optional row threshold for compact preview output.
topn: Optional number of leading/trailing rows to show when truncated.
max_vars: Optional maximum number of visible columns; NULL derives this from console width.
width: Optional display width; defaults to getOption("width").
show_ci: One of "yes" or "no".
...: 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.
show_value: Logical; if TRUE (default), overlay numeric values on the heatmap tiles.

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