ccc: Pairwise Lin's concordance correlation coefficient

In matrixCorr: Collection of Correlation and Association Estimators

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.

Usage

ccc(data, ci = FALSE, conf_level = 0.95, verbose = FALSE)

## S3 method for class 'ccc'
print(x, digits = 4, ...)

## S3 method for class 'ccc'
plot(
  x,
  title = "Lin's Concordance Correlation Heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ...
)

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 confidence intervals).
digits	Integer; number of decimal places to print in the concordance matrix (default is 4).
...	Additional arguments passed to underlying functions (like theme or print).
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 (typically near 0).
value_text_size	Text size for numbers in the heatmap.

Details

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}

This formula combines the Pearson correlation coefficient r = \mathrm{cov}(X, Y) / (\sigma_X \sigma_Y) with a bias correction factor:

C_b = \frac{2 \sigma_X \sigma_Y}{\sigma_X^2 + \sigma_Y^2 + (\mu_X - \mu_Y)^2}

Confidence intervals are not provided in the matrix version to retain speed, but can be computed separately for individual variable pairs using the scalar form of Lin's CCC.

Missing values are not allowed; input must be clean numeric data.

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.

Author(s)

Thiago de Paula Oliveira

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.

See Also

print.ccc, plot.ccc

Examples

# 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)
plot(result_mvn)

matrixCorr documentation built on Aug. 26, 2025, 5:07 p.m.