% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/concordance_corr.R
\name{ccc}
\alias{ccc}
\alias{print.ccc}
\alias{summary.ccc}
\alias{print.summary.ccc}
\alias{plot.ccc}
\title{Pairwise Lin's concordance correlation coefficient}
\usage{
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
)

\method{print}{ccc}(
  x,
  digits = 4,
  ci_digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{summary}{ccc}(
  object,
  digits = 4,
  ci_digits = 2,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{print}{summary.ccc}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{ccc}(
  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,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or data frame with at least two numeric columns.
Non-numeric columns will be ignored.}

\item{ci}{Logical; if TRUE, return lower and upper confidence bounds}

\item{conf_level}{Confidence level for CI, default = 0.95}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values.
\code{"complete"} removes rows incomplete in any retained numeric column
before computing all CCC estimates. \code{"pairwise"} recomputes each
method pair on its own complete finite overlap.}

\item{n_threads}{Integer \eqn{\geq 1}. Number of OpenMP threads. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{output}{Output representation for the computed estimates.
\itemize{
\item \code{"matrix"} (default): full dense matrix; best when you need
matrix algebra, dense heatmaps, or full compatibility with existing code.
\item \code{"sparse"}: sparse matrix from \pkg{Matrix} containing only
retained entries; best when many values are dropped by thresholding.
\item \code{"edge_list"}: long-form data frame with columns
\code{row}, \code{col}, \code{value}; convenient for filtering, joins,
and network-style workflows.
}}

\item{threshold}{Non-negative absolute-value filter for non-matrix outputs:
keep entries with \code{abs(value) >= threshold}. Use
\code{threshold > 0} when you want only stronger associations (typically
with \code{output = "sparse"} or \code{"edge_list"}). Keep
\code{threshold = 0} to retain all values. Must be \code{0} when
\code{output = "matrix"}.}

\item{diag}{Logical; whether to include diagonal entries in
\code{"sparse"} and \code{"edge_list"} outputs.}

\item{verbose}{Logical; if TRUE, prints how many threads are used}

\item{x}{An object of class \code{"ccc"} (either a matrix or a list with CIs).}

\item{digits}{Integer; decimals for CCC estimates (default 4).}

\item{ci_digits}{Integer; decimals for CI bounds (default 2).}

\item{n}{Optional row threshold for compact preview output.}

\item{topn}{Optional number of leading/trailing rows to show when truncated.}

\item{max_vars}{Optional maximum number of visible columns; \code{NULL} derives this
from console width.}

\item{width}{Optional display width; defaults to \code{getOption("width")}.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{...}{Passed to \code{ggplot2::theme()}.}

\item{object}{A \code{"ccc"} or \code{"ccc_ci"} object to summarize.}

\item{title}{Title for the plot.}

\item{low_color}{Color for low CCC values.}

\item{high_color}{Color for high CCC values.}

\item{mid_color}{Color for mid CCC values.}

\item{value_text_size}{Text size for CCC values in the heatmap.}

\item{ci_text_size}{Text size for confidence intervals.}

\item{show_value}{Logical; if \code{TRUE} (default), overlay numeric values
on the heatmap tiles.}
}
\value{
A symmetric numeric matrix with class \code{"ccc"} and attributes:
\itemize{
\item \code{method}: The method used ("Lin's concordance")
\item \code{description}: Description string
}
If \code{ci = FALSE}, returns matrix of class \code{"ccc"}.
If \code{ci = TRUE}, returns a list with elements: \code{est},
\code{lwr.ci}, \code{upr.ci}.

For \code{summary.ccc}, a data frame with columns
\code{item1}, \code{item2}, \code{estimate}, and (optionally)
\code{lwr}, \code{upr}, plus \code{n_complete} when available.
}
\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
\code{\link{ba}}).
}
\details{
Lin's CCC is defined as
\deqn{
\rho_c \;=\; \frac{2\,\mathrm{cov}(X, Y)}
                 {\sigma_X^2 + \sigma_Y^2 + (\mu_X - \mu_Y)^2},
}
where \eqn{\mu_X,\mu_Y} are the means, \eqn{\sigma_X^2,\sigma_Y^2} the
variances, and \eqn{\mathrm{cov}(X,Y)} the covariance. Equivalently,
\deqn{
\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 \eqn{|\rho_c| \le |r| \le 1}, \eqn{\rho_c = r} iff
\eqn{\mu_X=\mu_Y} and \eqn{\sigma_X=\sigma_Y}, and \eqn{\rho_c=1} iff, in
addition, \eqn{r=1}. CCC is symmetric in \eqn{(X,Y)} and penalises both
location and scale differences; unlike Pearson's \eqn{r}, it is not invariant
to affine transformations that change means or variances.

When \code{ci = TRUE}, large-sample confidence intervals for
\eqn{\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 \eqn{[-1, 1]}. For speed, CIs are omitted
when \code{ci = FALSE}.

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

Missing-data handling follows the same contract as \code{\link{pearson_corr}}
and \code{\link{spearman_rho}}. With \code{na_method = "error"} (default),
missing and non-finite values are rejected. With \code{"complete"}, rows
incomplete in any retained numeric column are removed once before all pairwise
CCC estimates are computed. With \code{"pairwise"}, each method pair is
computed on its own complete finite overlap, and \code{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 \code{"sparse"} and \code{"edge_list"}
outputs retain entries according to \code{abs(CCC) >= threshold}.

Probability of agreement, available through \code{\link{prob_agree}},
answers a
different question from CCC. CCC is a coefficient-based summary of
concordance between paired measurements. \code{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.
}
\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, 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)
}

}
\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.
}
\seealso{
\code{\link{print.ccc}}, \code{\link{plot.ccc}},
\code{\link{ba}}, \code{\link{prob_agree}}, and \code{\link{cia}}.
\code{ccc()} answers the question "How well do two paired measurements
agree overall, accounting for both correlation and mean/scale bias?".
In contrast, \code{cia()} answers "Are two or more methods
interchangeable at the individual level relative to within-method
replicate disagreement?".

For repeated measurements look at \code{\link{ccc_rm_reml}},
\code{\link{ccc_rm_ustat}} or \code{\link{ba_rm}}
}
\author{
Thiago de Paula Oliveira
}
