% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/schafer_corr.R
\name{shrinkage_corr}
\alias{shrinkage_corr}
\alias{schafer_corr}
\alias{print.shrinkage_corr}
\alias{print.schafer_corr}
\alias{plot.shrinkage_corr}
\alias{plot.schafer_corr}
\alias{summary.shrinkage_corr}
\alias{summary.schafer_corr}
\title{Shrinkage Correlation}
\usage{
shrinkage_corr(
  data,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE
)

schafer_corr(
  data,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE
)

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

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

\method{plot}{shrinkage_corr}(
  x,
  title = "Schafer-Strimmer shrinkage correlation",
  cluster = TRUE,
  hclust_method = "complete",
  triangle = c("upper", "lower", "full"),
  show_value = TRUE,
  show_values = NULL,
  value_text_limit = 60,
  value_text_size = 3,
  palette = c("diverging", "viridis"),
  ...
)

\method{plot}{schafer_corr}(
  x,
  title = "Schafer-Strimmer shrinkage correlation",
  cluster = TRUE,
  hclust_method = "complete",
  triangle = c("upper", "lower", "full"),
  show_value = TRUE,
  show_values = NULL,
  value_text_limit = 60,
  value_text_size = 3,
  palette = c("diverging", "viridis"),
  ...
)

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

\method{summary}{schafer_corr}(
  object,
  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. Columns must be numeric
and contain no \code{NA}s.}

\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{x}{An object of class \code{shrinkage_corr} or
\code{schafer_corr}.}

\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{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{...}{Additional arguments passed to \code{ggplot2::theme()}.}

\item{title}{Plot title.}

\item{cluster}{Logical; if TRUE, reorder rows/cols by hierarchical clustering
on distance \eqn{1 - r}.}

\item{hclust_method}{Linkage method for \code{hclust}; default \code{"complete"}.}

\item{triangle}{One of \code{"full"}, \code{"upper"}, \code{"lower"}.
Default to \code{upper}.}

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

\item{show_values}{Deprecated compatibility alias for \code{show_value}. If
supplied, it overrides \code{show_value}.}

\item{value_text_limit}{Integer threshold controlling when values are drawn.}

\item{value_text_size}{Font size for values if shown.}

\item{palette}{Character; \code{"diverging"} (default) or \code{"viridis"}.}

\item{object}{An object of class \code{shrinkage_corr} or
\code{schafer_corr}.}
}
\value{
A symmetric numeric matrix of class \code{shrinkage_corr} (with
compatibility class \code{schafer_corr}) where entry \code{(i, j)} is the
shrunk correlation between the \code{i}-th and \code{j}-th numeric columns.
Attributes:
\itemize{
\item \code{method} = \code{"schafer_shrinkage"}
\item \code{description} = \code{"Schafer-Strimmer shrinkage correlation
  matrix"}
\item \code{package} = \code{"matrixCorr"}
}
Columns with zero variance are set to \code{NA} across row/column (including
the diagonal), matching \code{pearson_corr()} behaviour.

Invisibly returns \code{x}.

A \code{ggplot} object.
}
\description{
Computes a shrinkage correlation matrix for numeric data using a
high-performance 'C++' backend. The current implementation uses the
Schafer-Strimmer shrinkage estimator to stabilise Pearson correlation
estimates by shrinking off-diagonal entries towards zero.
}
\details{
Let \eqn{R} be the sample Pearson correlation matrix. The Schafer-Strimmer
shrinkage estimator targets the identity in correlation space and uses
\eqn{\hat\lambda = \frac{\sum_{i<j}\widehat{\mathrm{Var}}(r_{ij})}
{\sum_{i<j} r_{ij}^2}} (clamped to \eqn{[0,1]}), where
\eqn{\widehat{\mathrm{Var}}(r_{ij}) \approx \frac{(1-r_{ij}^2)^2}{n-1}}.
The returned estimator is \eqn{R_{\mathrm{shr}} = (1-\hat\lambda)R +
\hat\lambda I}.
}
\note{
No missing values are permitted. Columns with fewer than two observations
or zero variance are flagged as \code{NA} (row/column).
}
\examples{
## Multivariate normal with AR(1) dependence (Toeplitz correlation)
set.seed(1)
n <- 80; p <- 40; rho <- 0.6
d <- abs(outer(seq_len(p), seq_len(p), "-"))
Sigma <- rho^d

X <- MASS::mvrnorm(n, mu = rep(0, p), Sigma = Sigma)
colnames(X) <- paste0("V", seq_len(p))

Rshr <- shrinkage_corr(X)
print(Rshr, digits = 2, n = 6, max_vars = 6)
summary(Rshr)
estimate(Rshr)
tidy(Rshr)
plot(Rshr)

## Shrinkage typically moves the sample correlation closer to the truth
Rraw <- stats::cor(X)
off  <- upper.tri(Sigma, diag = FALSE)
mae_raw <- mean(abs(Rraw[off] - Sigma[off]))
mae_shr <- mean(abs(Rshr[off] - Sigma[off]))
print(c(MAE_raw = mae_raw, MAE_shrunk = mae_shr))
plot(Rshr, title = "Schafer-Strimmer shrinkage correlation")

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

}
\references{
Schafer, J. & Strimmer, K. (2005). A shrinkage approach to large-scale
covariance matrix estimation and implications for functional genomics.
\emph{Statistical Applications in Genetics and Molecular Biology}, 4(1).
}
\seealso{
\code{\link{print.shrinkage_corr}},
\code{\link{plot.shrinkage_corr}}, \code{\link{pearson_corr}}
}
\author{
Thiago de Paula Oliveira
}
