% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rmcorr.R
\name{rmcorr}
\alias{rmcorr}
\alias{rmcorr_weighted}
\title{Repeated-Measures Correlation (rmcorr)}
\usage{
rmcorr(
  data = NULL,
  response,
  subject,
  na_method = c("error", "pairwise", "complete"),
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  keep_data = FALSE,
  verbose = FALSE,
  estimator = c("ancova", "weighted"),
  ci_method = c("auto", "fisher_z", "bootstrap", "none"),
  n_boot = 999L,
  seed = NULL,
  ...
)

rmcorr_weighted(data = NULL, response, subject, ...)
}
\arguments{
\item{data}{Optional \code{data.frame}/matrix containing the repeated-measures
dataset.}

\item{response}{Either:
\itemize{
\item a character vector of at least two column names in \code{data}, or
\item a numeric matrix/data frame with at least two columns.
}
If exactly two responses are supplied, the function returns a pairwise
repeated-measures correlation object of class \code{"rmcorr"}. If three or
more responses are supplied, a symmetric matrix of class
\code{"rmcorr_matrix"} is returned.}

\item{subject}{Subject identifier (factor/character/integer/numeric) or a
single character string naming the subject column in \code{data}.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing values in the selected response columns or
\code{subject}. \code{"pairwise"} uses pairwise complete cases and drops
subjects with fewer than two complete pairs for the specific contrast.
\code{"complete"} removes rows with missing or non-finite values in
\code{subject} and all selected response variables before fitting.}

\item{conf_level}{Confidence level used for Wald confidence intervals on the
repeated-measures correlation (default \code{0.95}).}

\item{n_threads}{Integer \eqn{\ge 1}. Number of OpenMP threads used by the
C++ backend in matrix mode. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{keep_data}{Logical (default \code{FALSE}). If \code{TRUE}, returned
objects retain a compact copy of the numeric response matrix plus encoded
subject identifiers. For pairwise fits this enables \code{plot()} to
reconstruct subject-level fitted lines lazily; for matrix outputs it also
allows \code{view_rmcorr_shiny()} to rebuild pairwise scatterplots from the
returned object alone.}

\item{verbose}{Logical; if \code{TRUE}, prints a short note about the thread
count used in matrix mode.}

\item{estimator}{Character scalar selecting the repeated-measures
correlation estimator. \code{"ancova"} (default) is the classical
subject-centred repeated-measures correlation. \code{"weighted"} is the
weighted repeated-measures correlation coefficient of Kondo et al. (2025),
designed for incomplete or unbalanced repeated-measurement schedules.}

\item{ci_method}{Confidence-interval engine. \code{"auto"} (default)
resolves to \code{"fisher_z"} for \code{estimator = "ancova"} and to
subject-level \code{"bootstrap"} for \code{estimator = "weighted"} when
\code{n_boot > 0}; otherwise \code{"none"}. \code{"none"} returns
\code{NA} bounds.}

\item{n_boot}{Integer \eqn{\ge 0}. Number of subject-level bootstrap
resamples when \code{ci_method = "bootstrap"}.}

\item{seed}{Optional positive integer seed used for bootstrap
reproducibility.}

\item{...}{Deprecated compatibility aliases. The legacy \code{check_na}
argument is still accepted here temporarily.}
}
\value{
Either a \code{"rmcorr"} object (exactly two responses) or a
\code{"rmcorr_matrix"} object (pairwise results when \eqn{\ge}3 responses).

\strong{If \code{"rmcorr"} (exactly two responses)}, outputs include:
\itemize{
\item \code{estimate}; repeated-measures correlation estimate.
\item \code{p_value}; two-sided p-value for the common within-subject slope.
\item \code{lwr}, \code{upr}; confidence interval limits for
\code{estimate}.
\item \code{slope}; common within-subject slope.
\item \code{df}; residual degrees of freedom \eqn{N - S - 1}.
\item \code{n_obs}; number of complete observations retained after
dropping subjects with fewer than two repeated pairs.
\item \code{n_subjects}; number of contributing subjects.
\item \code{responses}; names of the fitted response variables.
\item compatibility aliases \code{r}, \code{conf_int}, and \code{based.on}
are reconstructed on access without duplicate storage.
\item when \code{keep_data = TRUE}, compact source data are retained so
\code{plot()} can lazily reconstruct \code{data_long},
\code{intercepts}, and fitted lines; these are otherwise not stored.
}

\strong{If \code{"rmcorr_matrix"} (\eqn{\ge}3 responses)}, outputs are:
\itemize{
\item a symmetric numeric matrix of pairwise repeated-measures correlations.
\item attributes \code{method}, \code{description}, and
\code{package = "matrixCorr"}.
\item \code{diagnostics}; a list with square matrices for \code{slope},
\code{p_value}, \code{df}, \code{n_complete}, \code{n_subjects},
\code{conf_low}, and \code{conf_high}, plus scalar
\code{conf_level}.
}
}
\description{
Computes repeated-measures correlation for two or more continuous responses
observed repeatedly within subjects. Supply a \code{data.frame} plus column
names, or pass the response matrix/data frame and subject vector directly.
The repeated observations are indexed only by \code{subject}, thus no explicit
time variable is modeled, and the method targets a common within-subject
linear association after removing subject-specific means.
}
\details{
Repeated-measures correlation estimates the common \emph{within-subject}
linear association between two variables measured repeatedly on the same
subjects. It differs from agreement methods such as Lin's CCC or
Bland-Altman analysis because those target concordance or interchangeability,
whereas repeated-measures correlation targets the strength of the
subject-centred association.

For subject \eqn{i = 1,\ldots,S} and repeated observations
\eqn{j = 1,\ldots,n_i}, let \eqn{x_{ij}} and \eqn{y_{ij}} denote the two
responses. Define subject-specific means
\deqn{\bar x_i = \frac{1}{n_i}\sum_{j=1}^{n_i} x_{ij}, \qquad
      \bar y_i = \frac{1}{n_i}\sum_{j=1}^{n_i} y_{ij}.}
The repeated-measures correlation uses within-subject centred values
\deqn{x^\ast_{ij} = x_{ij} - \bar x_i, \qquad
      y^\ast_{ij} = y_{ij} - \bar y_i}
and computes
\deqn{r_{\mathrm{rm}} =
      \frac{\sum_i \sum_j x^\ast_{ij} y^\ast_{ij}}
           {\sqrt{\left(\sum_i \sum_j {x^\ast_{ij}}^2\right)
                  \left(\sum_i \sum_j {y^\ast_{ij}}^2\right)}}.}

Equivalently, this is the correlation implied by an ANCOVA model with a
common slope and subject-specific intercepts:
\deqn{y_{ij} = \alpha_i + \beta x_{ij} + \varepsilon_{ij}.}
The returned slope is
\deqn{\hat\beta =
      \frac{\sum_i \sum_j x^\ast_{ij} y^\ast_{ij}}
           {\sum_i \sum_j {x^\ast_{ij}}^2},}
and the subject-specific fitted intercepts are
\eqn{\hat\alpha_i = \bar y_i - \hat\beta \bar x_i}. Residual degrees of
freedom are \eqn{N - S - 1}, where \eqn{N = \sum_i n_i} after filtering to
complete observations and retaining only subjects with at least two repeated
pairs.

Confidence intervals are computed with a Fisher \eqn{z}-transformation of
\eqn{r_{\mathrm{rm}}} and then back-transformed to the correlation scale. In
matrix mode, the same estimator is applied to every pair of selected
response columns.

With \code{estimator = "weighted"}, the package implements the weighted
repeated-measures estimator from Kondo et al. (2025) using complete observed
\eqn{(x,y)} pairs per contrast. This estimator does not impute missing data;
it uses per-subject complete-pair sets and weighted sums of explained and
residual quantities from the fixed-subject ANCOVA decomposition.

Bootstrap confidence intervals use non-parametric subject-level resampling
(subjects are resampled as blocks, not rows).
}
\examples{
set.seed(2026)
n_subjects <- 20
n_rep <- 4
subject <- rep(seq_len(n_subjects), each = n_rep)
subj_eff_x <- rnorm(n_subjects, sd = 1.5)
subj_eff_y <- rnorm(n_subjects, sd = 2.0)
within_signal <- rnorm(n_subjects * n_rep)

dat <- data.frame(
  subject = subject,
  x = subj_eff_x[subject] + within_signal + rnorm(n_subjects * n_rep, sd = 0.2),
  y = subj_eff_y[subject] + 0.8 * within_signal + rnorm(n_subjects * n_rep, sd = 0.3),
  z = subj_eff_y[subject] - 0.4 * within_signal + rnorm(n_subjects * n_rep, sd = 0.4)
)

fit_xy <- rmcorr(dat, response = c("x", "y"), subject = "subject", keep_data = TRUE)
print(fit_xy)
summary(fit_xy)
estimate(fit_xy)
tidy(fit_xy)
ci(fit_xy)
confint(fit_xy)
plot(fit_xy)

fit_mat <- rmcorr(dat, response = c("x", "y", "z"), subject = "subject")
print(fit_mat, digits = 3)
summary(fit_mat)
tidy(fit_mat)
plot(fit_mat)

if (interactive() && requireNamespace("shiny", quietly = TRUE)) {
  fit_mat_view <- rmcorr(
    dat,
    response = c("x", "y", "z"),
    subject = "subject",
    keep_data = TRUE
  )
  view_rmcorr_shiny(fit_mat_view)
}
}
\references{
Bakdash, J. Z., & Marusich, L. R. (2017). Repeated Measures Correlation.
\emph{Frontiers in Psychology}, 8, 456.
\doi{10.3389/fpsyg.2017.00456}

Kondo, M., Nagashima, K., Isono, S., & Sato, Y. (2025). Weighted Repeated
Measures Correlation Coefficient: A New Correlation Coefficient for Handling
Missing Data With Repeated Measures. \emph{Statistics in Medicine},
44(10-12), e70046. \doi{10.1002/sim.70046}
}
\author{
Thiago de Paula Oliveira
}
