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).
ccc(
data,
ci = FALSE,
conf_level = 0.95,
na_method = c("error", "complete", "pairwise"),
n_threads = getOption("matrixCorr.threads", 1L),
output = c("matrix", "sparse", "edge_list"),
threshold = 0,
diag = TRUE,
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,
...
)
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
item1, item2, estimate, and (optionally)
lwr, upr, plus n_complete when available.
A numeric matrix or data frame with at least two numeric columns. Non-numeric columns will be ignored.
Logical; if TRUE, return lower and upper confidence bounds
Confidence level for CI, default = 0.95
Character scalar controlling missing-data handling.
"error" rejects missing, NaN, and infinite values.
"complete" removes rows incomplete in any retained numeric column
before computing all CCC estimates. "pairwise" recomputes each
method pair on its own complete finite overlap.
Integer \(\geq 1\). Number of OpenMP threads. Defaults to
getOption("matrixCorr.threads", 1L).
Output representation for the computed estimates.
"matrix" (default): full dense matrix; best when you need
matrix algebra, dense heatmaps, or full compatibility with existing code.
"sparse": sparse matrix from Matrix containing only
retained entries; best when many values are dropped by thresholding.
"edge_list": long-form data frame with columns
row, col, value; convenient for filtering, joins,
and network-style workflows.
Non-negative absolute-value filter for non-matrix outputs:
keep entries with abs(value) >= threshold. Use
threshold > 0 when you want only stronger associations (typically
with output = "sparse" or "edge_list"). Keep
threshold = 0 to retain all values. Must be 0 when
output = "matrix".
Logical; whether to include diagonal entries in
"sparse" and "edge_list" outputs.
Logical; if TRUE, prints how many threads are used
An object of class "ccc" (either a matrix or a list with CIs).
Integer; decimals for CCC estimates (default 4).
Integer; decimals for CI bounds (default 2).
Optional row threshold for compact preview output.
Optional number of leading/trailing rows to show when truncated.
Optional maximum number of visible columns; NULL derives this
from console width.
Optional display width; defaults to getOption("width").
One of "yes" or "no".
Passed to ggplot2::theme().
A "ccc" or "ccc_ci" object to summarize.
Title for the plot.
Color for low CCC values.
Color for high CCC values.
Color for mid CCC values.
Text size for CCC values in the heatmap.
Text size for confidence intervals.
Logical; if TRUE (default), overlay numeric values
on the heatmap tiles.
Thiago de Paula Oliveira
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. The implementation uses Lin's
delta-method standard error and then forms limits on a Fisher-z transformed
CCC scale before mapping back to \([-1, 1]\). 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-data handling follows the same contract as pearson_corr
and spearman_rho. With na_method = "error" (default),
missing and non-finite values are rejected. With "complete", rows
incomplete in any retained numeric column are removed once before all pairwise
CCC estimates are computed. With "pairwise", each method pair is
computed on its own complete finite overlap, and n_complete
diagnostics may vary by pair. Pairwise CIs require at least three complete
observations for that pair.
Negative CCC estimates are fully supported. Matrix output preserves the
signed estimate, while thresholded "sparse" and "edge_list"
outputs retain entries according to abs(CCC) >= threshold.
Probability of agreement, available through prob_agree,
answers a
different question from CCC. CCC is a coefficient-based summary of
concordance between paired measurements. prob_agree() follows Stevens and
Anderson-Cook (2017) and estimates the probability that two estimated
quantities or curves differ by no more than a user-specified practical
tolerance.
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.
print.ccc, plot.ccc,
ba, prob_agree, and cia.
See robust_ccc for MCD based robust concordance using joint
reweighted location and scatter estimates.
ccc() answers the question "How well do two paired measurements
agree overall, accounting for both correlation and mean/scale bias?".
In contrast, cia() answers "Are two or more methods
interchangeable at the individual level relative to within-method
replicate disagreement?".
For repeated measurements look at ccc_rm_reml,
ccc_rm_ustat or ba_rm
# 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, ci = TRUE)
print(result_mvn)
summary(result_mvn)
estimate(result_mvn)
tidy(result_mvn)
ci(result_mvn)
confint(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