% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pearson_corr.R
\name{pearson_corr}
\alias{pearson_corr}
\alias{print.pearson_corr}
\alias{plot.pearson_corr}
\alias{summary.pearson_corr}
\alias{print.summary.pearson_corr}
\title{Pairwise Pearson correlation}
\usage{
pearson_corr(
  data,
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  ...
)

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

\method{plot}{pearson_corr}(
  x,
  title = "Pearson correlation heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)

\method{summary}{pearson_corr}(
  object,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  ci_digits = 3,
  show_ci = NULL,
  ...
)

\method{print}{summary.pearson_corr}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or a data frame with at least two numeric
columns. All non-numeric columns will be excluded. Each column must have
at least two non-missing values.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values.
\code{"pairwise"} recomputes each correlation on its own pairwise
complete-case overlap. This is permissive, but different matrix entries
may be based on different rows. \code{"complete"} performs listwise
deletion once across the retained numeric columns and then computes the
estimator on the common complete sample.}

\item{ci}{Logical (default \code{FALSE}). If \code{TRUE}, attach pairwise
Fisher-\eqn{z} confidence intervals for the off-diagonal Pearson
correlations.}

\item{conf_level}{Confidence level used when \code{ci = TRUE}. Default is
\code{0.95}.}

\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{...}{Additional arguments passed to \code{ggplot2::theme()} or other
\code{ggplot2} layers.}

\item{x}{An object of class \code{summary.pearson_corr}.}

\item{digits}{Integer; number of decimal places to print in the concordance}

\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{ci_digits}{Integer; digits for Pearson confidence limits in the
pairwise summary.}

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

\item{title}{Plot title. Default is \code{"Pearson correlation heatmap"}.}

\item{low_color}{Color for the minimum correlation. Default is
\code{"indianred1"}.}

\item{high_color}{Color for the maximum correlation. Default is
\code{"steelblue1"}.}

\item{mid_color}{Color for zero correlation. Default is \code{"white"}.}

\item{value_text_size}{Font size for displaying correlation values. Default
is \code{4}.}

\item{ci_text_size}{Text size for confidence intervals in the heatmap.}

\item{show_value}{Logical; if \code{TRUE} (default), overlay numeric values
on the heatmap tiles.}

\item{object}{An object of class \code{pearson_corr}.}
}
\value{
A symmetric numeric matrix where the \code{(i, j)}-th element is
the Pearson correlation between the \code{i}-th and \code{j}-th
numeric columns of the input. When \code{ci = TRUE}, the object also
carries a \code{ci} attribute with elements \code{est}, \code{lwr.ci},
\code{upr.ci}, and \code{conf.level}. When pairwise-complete evaluation is
used, pairwise sample sizes are stored in \code{attr(x, "diagnostics")$n_complete}.

Invisibly returns the \code{pearson_corr} object.

A \code{ggplot} object representing the heatmap.
}
\description{
Computes pairwise Pearson correlations for the numeric columns of a matrix
or data frame using a high-performance 'C++' backend. Optional Fisher-z
confidence intervals are available.
}
\details{
Let \eqn{X \in \mathbb{R}^{n \times p}} be a
numeric matrix with rows as observations and columns as variables, and let
\eqn{\mathbf{1} \in \mathbb{R}^n} denote the all-ones vector. Define the column
means \eqn{\mu = (1/n)\,\mathbf{1}^\top X} and the centred cross-product
matrix
\deqn{ S \;=\; (X - \mathbf{1}\mu)^\top (X - \mathbf{1}\mu)
      \;=\; X^\top \!\Big(I_n - \tfrac{1}{n}\mathbf{1}\mathbf{1}^\top\Big) X
      \;=\; X^\top X \;-\; n\,\mu\,\mu^\top. }
The (unbiased) sample covariance is
\deqn{ \widehat{\Sigma} \;=\; \tfrac{1}{n-1}\,S, }
and the sample standard deviations are \eqn{s_i = \sqrt{\widehat{\Sigma}_{ii}}}.
The Pearson correlation matrix is obtained by standardising \eqn{\widehat{\Sigma}}, and it is given by
\deqn{ R \;=\; D^{-1/2}\,\widehat{\Sigma}\,D^{-1/2}, \qquad
      D \;=\; \mathrm{diag}(\widehat{\Sigma}_{11},\ldots,\widehat{\Sigma}_{pp}), }
equivalently, entrywise \eqn{R_{ij} = \widehat{\Sigma}_{ij}/(s_i s_j)} for
\eqn{i \neq j} and \eqn{R_{ii} = 1}. With \eqn{1/(n-1)} scaling,
\eqn{\widehat{\Sigma}} is unbiased for the covariance; the induced
correlations are biased in finite samples.

The implementation forms \eqn{X^\top X} via a BLAS
symmetric rank-\eqn{k} update (SYRK) on the upper triangle, then applies the
rank-1 correction \eqn{-\,n\,\mu\,\mu^\top} to obtain \eqn{S} without
explicitly materialising \eqn{X - \mathbf{1}\mu}. After scaling by
\eqn{1/(n-1)}, triangular normalisation by \eqn{D^{-1/2}} yields \eqn{R},
which is then symmetrised to remove round-off asymmetry. Tiny negative values
on the covariance diagonal due to floating-point rounding are truncated to
zero before taking square roots.

If a variable has zero variance (\eqn{s_i = 0}), the corresponding row and
column of \eqn{R} are set to \code{NA}. When
\code{na_method = "pairwise"}, each \eqn{(i,j)} correlation is recomputed on
the pairwise complete-case overlap of columns \eqn{i} and \eqn{j}.

When \code{ci = TRUE}, Fisher-\eqn{z} confidence intervals are computed from
the observed pairwise Pearson correlation \eqn{r_{ij}} and the pairwise
complete-case sample size \eqn{n_{ij}}:
\deqn{
z_{ij} = \operatorname{atanh}(r_{ij}), \qquad
\operatorname{SE}(z_{ij}) = \frac{1}{\sqrt{n_{ij} - 3}}.
}
With \eqn{z_{1-\alpha/2} = \Phi^{-1}(1 - \alpha/2)}, the confidence limits are
\deqn{
\tanh\!\bigl(z_{ij} - z_{1-\alpha/2}\operatorname{SE}(z_{ij})\bigr)
\;\;\text{and}\;\;
\tanh\!\bigl(z_{ij} + z_{1-\alpha/2}\operatorname{SE}(z_{ij})\bigr).
}
Confidence intervals are reported only when \eqn{n_{ij} > 3}.

\strong{Computational complexity.} The dominant cost is \eqn{O(n p^2)} flops
with \eqn{O(p^2)} memory.
}
\note{
\code{na_method = "complete"} is useful when a common analysis sample is
required across all matrix entries. For covariance- or cross-product-based
correlations, it also avoids the non-positive-semidefinite matrices that can
arise from pairwise deletion.
}
\examples{
## MVN with AR(1) correlation
set.seed(123)
p <- 6; n <- 300; rho <- 0.5
# true correlation
Sigma <- rho^abs(outer(seq_len(p), seq_len(p), "-"))
L <- chol(Sigma)
# MVN(n, 0, Sigma)
X <- matrix(rnorm(n * p), n, p) \%*\% L
colnames(X) <- paste0("V", seq_len(p))

pr <- pearson_corr(X)
print(pr, digits = 2)
summary(pr)
estimate(pr)
tidy(pr)
plot(pr)

## Confidence intervals
pr_ci <- pearson_corr(X[, 1:3], ci = TRUE)
ci(pr_ci)
confint(pr_ci)

## Compare the sample estimate to the truth
Rhat <- cor(X)
# estimated
round(Rhat[1:4, 1:4], 2)
# true
round(Sigma[1:4, 1:4], 2)
off <- upper.tri(Sigma, diag = FALSE)
# MAE on off-diagonals
mean(abs(Rhat[off] - Sigma[off]))

## Larger n reduces sampling error
n2 <- 2000
X2 <- matrix(rnorm(n2 * p), n2, p) \%*\% L
Rhat2 <- cor(X2)
off <- upper.tri(Sigma, diag = FALSE)
## mean absolute error (MAE) of the off-diagonal correlations
mean(abs(Rhat2[off] - Sigma[off]))

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

}
\references{
Pearson, K. (1895). "Notes on regression and inheritance in the case of
two parents". Proceedings of the Royal Society of London, 58, 240-242.
}
\seealso{
\code{\link{print.pearson_corr}}, \code{\link{plot.pearson_corr}}
}
\author{
Thiago de Paula Oliveira
}
