% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ccc_repeated.R
\name{ccc_rm_ustat}
\alias{ccc_rm_ustat}
\title{Repeated-Measures Lin's Concordance Correlation Coefficient (CCC)}
\usage{
ccc_rm_ustat(
  data,
  response,
  subject,
  method,
  time = NULL,
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE,
  Dmat = NULL,
  delta = 1
)
}
\arguments{
\item{data}{A data frame containing the repeated-measures dataset.}

\item{response}{Character. Name of the numeric outcome column.}

\item{subject}{Character. Column identifying subjects. Every subject must
have measurements from all methods (and times, when supplied); rows with
incomplete \{subject, time, method\} coverage are dropped per pair.}

\item{method}{Character. Name of the method column (factor with L
\eqn{\geq} 2 levels).}

\item{time}{Character or NULL. Name of the time/repetition column. If NULL,
one time point is assumed.}

\item{ci}{Logical. If TRUE, returns confidence intervals (default FALSE).}

\item{conf_level}{Confidence level for CI (default 0.95).}

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

\item{verbose}{Logical. If TRUE, prints diagnostic output (default FALSE).}

\item{Dmat}{Optional numeric weight matrix (T \eqn{\times} T) for
timepoints. Defaults to identity.}

\item{delta}{Numeric. Exponent applied to the absolute pointwise differences
between two method trajectories before the time-weighted quadratic form is
evaluated. Internally, the function forms
\eqn{v_t = |X_t - Y_t|^\delta} and then computes
\eqn{v^\top D v}, where \eqn{D} is \code{Dmat}.
Therefore, when \code{Dmat} is diagonal:
\itemize{
\item \code{delta = 1} (default) gives the standard quadratic
repeated-measures CCC distance,
\eqn{(X - Y)^\top D (X - Y)}.
\item \code{delta = 2} gives a fourth-power loss,
which puts stronger emphasis on large disagreements.
\item \code{delta = 0} gives a binary disagreement indicator before
aggregation, analogous to a repeated-measures kappa-type distance.
}
In most applications, \code{delta = 1} should be used because it matches
the usual quadratic distance used in repeated-measures CCC.}
}
\value{
If \code{ci = FALSE}, a symmetric matrix of class \code{"ccc"} (estimates only).
If \code{ci = TRUE}, a list of class \code{"ccc"}, \code{"ccc_ci"} with elements:
\itemize{
\item \code{est}: CCC estimate matrix
\item \code{lwr.ci}: Lower bound matrix
\item \code{upr.ci}: Upper bound matrix
}
}
\description{
Computes all pairwise Lin's Concordance Correlation Coefficients (CCC)
across multiple methods (L \eqn{\geq} 2) for repeated-measures data.
Each subject must be measured by all methods across the same set of time
points or replicates.

CCC measures both accuracy (how close measurements are to the line of
equality) and precision (Pearson correlation). Confidence intervals are
optionally computed using a U-statistics-based estimator with Fisher's Z
transformation
}
\details{
This function computes pairwise Lin's Concordance Correlation Coefficient
(CCC) between methods in a repeated-measures design using a
U-statistics-based nonparametric estimator proposed by
Carrasco et al. (2013). It is computationally efficient and robust,
particularly for large-scale or balanced longitudinal designs.

Lin's CCC is defined as
\deqn{
\rho_c = \frac{2 \cdot \mathrm{cov}(X, Y)}{\sigma_X^2 + \sigma_Y^2 +
(\mu_X - \mu_Y)^2}
}{
CCC = 2 * cov(X, Y) / [var(X) + var(Y) + (mean(X) - mean(Y))^2]
}
where:
\itemize{
\item \eqn{X} and \eqn{Y} are paired measurements from two methods.
\item \eqn{\mu_X}, \eqn{\mu_Y} are means, and \eqn{\sigma_X^2},
\eqn{\sigma_Y^2} are variances.
}
\subsection{U-statistics Estimation}{

For repeated measures across \eqn{T} time points and \eqn{n} subjects we
assume
\itemize{
\item all \eqn{n(n-1)} pairs of subjects are considered to compute a
U-statistic estimator for within-method and cross-method distances.
\item if \code{delta > 0}, pairwise distances are raised to a power before
applying a time-weighted kernel matrix \eqn{D}.
\item if \code{delta = 0}, the method reduces to a version similar to a
repeated-measures kappa.
}
}

\subsection{Confidence Intervals}{

Confidence intervals are constructed using a \strong{Fisher Z-transformation}
of the CCC. Specifically,
\itemize{
\item The CCC is transformed using
\eqn{Z = 0.5 \log((1 + \rho_c) / (1 - \rho_c))}.
\item Standard errors are computed from the asymptotic variance of the
U-statistic.
\item Normal-based intervals are computed on the Z-scale and then
back-transformed to the CCC scale.
}
}

\subsection{Assumptions}{

\itemize{
\item The design must be \strong{balanced}, where all subjects must have
complete observations for all methods and time points.
\item The method is \strong{nonparametric} and does not require assumptions
of normality or linear mixed effects.
\item Weights (\code{Dmat}) allow differential importance of time points.
}

For \strong{unbalanced} or \strong{complex hierarchical} data (e.g.,
missing timepoints, covariate adjustments), consider using
\code{\link{ccc_rm_reml}}, which uses a variance components approach
via linear mixed models.
}
}
\examples{
set.seed(123)
df <- expand.grid(subject = 1:10,
                  time = 1:2,
                  method = c("A", "B", "C"))
df$y <- rnorm(nrow(df), mean = match(df$method, c("A", "B", "C")), sd = 1)

# CCC matrix (no CIs)
ccc1 <- ccc_rm_ustat(df, response = "y", subject = "subject",
                            method = "method", time = "time")
print(ccc1)
summary(ccc1)
plot(ccc1)

# With confidence intervals
ccc2 <- ccc_rm_ustat(df, response = "y", subject = "subject",
                            method = "method", time = "time", ci = TRUE)
print(ccc2)
summary(ccc2)
estimate(ccc2)
tidy(ccc2)
ci(ccc2)
confint(ccc2)
plot(ccc2)

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

#------------------------------------------------------------------------
# Choosing delta based on distance sensitivity
#------------------------------------------------------------------------
# Standard quadratic RM-CCC distance: (X - Y)' D (X - Y)
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 1)

# Fourth-power loss when D is diagonal: emphasises large disagreements
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 2)
# Binary disagreement indicator before aggregation
ccc_rm_ustat(df, response = "y", subject = "subject",
             method = "method", time = "time", delta = 0)
}
\references{
Lin L (1989). A concordance correlation coefficient to evaluate reproducibility.
\emph{Biometrics}, 45: 255-268.

Lin L (2000). A note on the concordance correlation coefficient.
\emph{Biometrics}, 56: 324-325.

Carrasco JL, Jover L (2003). Estimating the concordance correlation coefficient:
a new approach. \emph{Computational Statistics & Data Analysis}, 47(4): 519-539.
}
\seealso{
\code{\link{ccc}}, \code{\link{ccc_rm_reml}},
\code{\link{plot.ccc}}, \code{\link{print.ccc}}
}
\author{
Thiago de Paula Oliveira
}
