% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spearman_rho.R
\name{spearman_rho}
\alias{spearman_rho}
\alias{print.spearman_rho}
\alias{plot.spearman_rho}
\alias{summary.spearman_rho}
\alias{print.summary.spearman_rho}
\title{Pairwise Spearman's rank correlation}
\usage{
spearman_rho(
  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}{spearman_rho}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  ci_digits = 3,
  show_ci = NULL,
  ...
)

\method{plot}{spearman_rho}(
  x,
  title = "Spearman's rank correlation heatmap",
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)

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

\method{print}{summary.spearman_rho}(
  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
jackknife Euclidean-likelihood confidence intervals for the off-diagonal
Spearman 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.spearman_rho}.}

\item{digits}{Integer; number of decimal places to print.}

\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 Spearman confidence limits in the
pairwise summary.}

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

\item{title}{Plot title. Default is \code{"Spearman's rank correlation
heatmap"}.}

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

\item{high_color}{Color for the maximum rho value. 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{spearman_rho}.}
}
\value{
A symmetric numeric matrix where the \code{(i, j)}-th element is
the Spearman 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{spearman_rho} object.

A \code{ggplot} object representing the heatmap.
}
\description{
Computes pairwise Spearman's rank correlations for the numeric columns of a
matrix or data frame using a high-performance 'C++' backend. Optional
confidence intervals are available via a jackknife Euclidean-likelihood
method.
}
\details{
For each column \eqn{j=1,\ldots,p}, let
\eqn{R_{\cdot j} \in \{1,\ldots,n\}^n} denote the (mid-)ranks of
\eqn{X_{\cdot j}}, assigning average ranks to ties. The mean rank is
\eqn{\bar R_j = (n+1)/2} regardless of ties. Define the centred rank
vectors \eqn{\tilde R_{\cdot j} = R_{\cdot j} - \bar R_j \mathbf{1}},
where \eqn{\mathbf{1}\in\mathbb{R}^n} is the all-ones vector. The
Spearman correlation between columns \eqn{i} and \eqn{j} is the Pearson
correlation of their rank vectors:
\deqn{
\rho_S(i,j) \;=\;
\frac{\sum_{k=1}^n (R_{ki}-\bar R_i)(R_{kj}-\bar R_j)}
     {\sqrt{\sum_{k=1}^n (R_{ki}-\bar R_i)^2}\;
      \sqrt{\sum_{k=1}^n (R_{kj}-\bar R_j)^2}}.
}
In matrix form, with \eqn{R=[R_{\cdot 1},\ldots,R_{\cdot p}]},
\eqn{\mu=(n+1)\mathbf{1}_p/2} for \eqn{\mathbf{1}_p\in\mathbb{R}^p}, and
\eqn{S_R=\bigl(R-\mathbf{1}\mu^\top\bigr)^\top
           \bigl(R-\mathbf{1}\mu^\top\bigr)/(n-1)},
the Spearman correlation matrix is
\deqn{
\widehat{\rho}_S \;=\; D^{-1/2} S_R D^{-1/2}, \qquad
D \;=\; \mathrm{diag}(\mathrm{diag}(S_R)).
}
When there are no ties, the familiar rank-difference formula obtains
\deqn{
\rho_S(i,j) \;=\; 1 - \frac{6}{n(n^2-1)} \sum_{k=1}^n d_k^2,
\quad d_k \;=\; R_{ki}-R_{kj},
}
but this expression does \emph{not} hold under ties; computing Pearson on
mid-ranks (as above) is the standard tie-robust approach. Without ties,
\eqn{\mathrm{Var}(R_{\cdot j})=(n^2-1)/12}; with ties, the variance is
smaller.

\eqn{\rho_S(i,j) \in [-1,1]} and \eqn{\widehat{\rho}_S} is symmetric
positive semi-definite by construction (up to floating-point error). The
implementation symmetrises the result to remove round-off asymmetry.
Spearman's correlation is invariant to strictly monotone transformations
applied separately to each variable.

\strong{Computation.} Each column is ranked (mid-ranks) to form \eqn{R}.
The product \eqn{R^\top R} is computed via a 'BLAS' symmetric rank update
('SYRK'), and centred using
\deqn{
(R-\mathbf{1}\mu^\top)^\top (R-\mathbf{1}\mu^\top)
\;=\; R^\top R \;-\; n\,\mu\mu^\top,
}
avoiding an explicit centred copy. Division by \eqn{n-1} yields the sample
covariance of ranks; standardising by \eqn{D^{-1/2}} gives \eqn{\widehat{\rho}_S}.
Columns with zero rank variance (all values equal) are returned as \code{NA}
along their row/column; the corresponding diagonal entry is also \code{NA}.

When \code{na_method = "pairwise"}, each \eqn{(i,j)} estimate is recomputed
on the pairwise complete-case overlap of columns \eqn{i} and \eqn{j}. When
\code{ci = TRUE}, confidence intervals are computed in 'C++' using the
jackknife Euclidean-likelihood method of de Carvalho and Marques (2012).
For a pairwise estimate \eqn{U = \hat\rho_S}, delete-one jackknife
pseudo-values are formed as
\deqn{
Z_i = nU - (n-1)U_{(-i)}, \qquad i = 1,\ldots,n,
}
where \eqn{U_{(-i)}} is the Spearman correlation after removing observation
\eqn{i}. The confidence limits solve
\deqn{
\frac{n(U-\theta)^2}{n^{-1}\sum_{i=1}^n (Z_i - \theta)^2}
= \chi^2_{1,\;\texttt{conf\_level}}.
}

Ranking costs
\eqn{O\!\bigl(p\,n\log n\bigr)}; forming and normalising
\eqn{R^\top R} costs \eqn{O\!\bigl(n p^2\bigr)} with \eqn{O(p^2)} additional
memory. The optional jackknife Euclidean-likelihood confidence intervals add
per-pair delete-one recomputation work and are intended for inference rather
than raw-matrix throughput.
}
\note{
Missing values are rejected when \code{na_method = "error"}. Columns
with fewer than two usable observations are excluded.
}
\examples{
## Monotone transformation invariance (Spearman is rank-based)
set.seed(123)
n <- 400; p <- 6; rho <- 0.6
Sigma <- rho^abs(outer(seq_len(p), seq_len(p), "-"))
L <- chol(Sigma)
X <- matrix(rnorm(n * p), n, p) \%*\% L
colnames(X) <- paste0("V", seq_len(p))

X_mono <- X
X_mono[, 1] <- exp(X_mono[, 1])
X_mono[, 2] <- log1p(exp(X_mono[, 2]))
X_mono[, 3] <- X_mono[, 3]^3

sp_X <- spearman_rho(X)
sp_m <- spearman_rho(X_mono)
summary(sp_X)
round(max(abs(sp_X - sp_m)), 3)
plot(sp_X)

## Confidence intervals
sp_ci <- spearman_rho(X[, 1:3], ci = TRUE)
print(sp_ci, show_ci = "yes")
summary(sp_ci)
estimate(sp_ci)
tidy(sp_ci)
ci(sp_ci)
confint(sp_ci)

## Ties handled via mid-ranks
tied <- cbind(
  a = rep(1:5, each = 20),
  b = rep(5:1, each = 20) + rnorm(100, sd = 0.1),
  c = as.numeric(gl(10, 10))
)
sp_tied <- spearman_rho(tied, ci = TRUE)
print(sp_tied, digits = 2, show_ci = "yes")

# Interactive viewing (requires shiny)
if (interactive() && requireNamespace("shiny", quietly = TRUE)) {
  view_corr_shiny(sp_X)
}
}
\references{
Spearman, C. (1904). The proof and measurement of association between
two things. International Journal of Epidemiology, 39(5), 1137-1150.

de Carvalho, M., & Marques, F. (2012). Jackknife Euclidean
likelihood-based inference for Spearman's rho. North American Actuarial
Journal, 16(4), 487-492.
}
\seealso{
\code{\link{print.spearman_rho}}, \code{\link{plot.spearman_rho}}
}
\author{
Thiago de Paula Oliveira
}
