% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/robust_dcor.R
\name{robust_dcor}
\alias{robust_dcor}
\alias{print.robust_dcor}
\alias{summary.robust_dcor}
\alias{plot.robust_dcor}
\title{Robust Distance Correlation}
\usage{
robust_dcor(
  data,
  na_method = c("error", "pairwise", "complete"),
  p_value = FALSE,
  inference = c("none", "permutation"),
  n_perm = 999L,
  seed = NULL,
  c_const = 4,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  ...
)

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

\method{summary}{robust_dcor}(object, topn = NULL, show_ci = NULL, ...)

\method{plot}{robust_dcor}(
  x,
  title = NULL,
  low_color = "indianred1",
  high_color = "steelblue1",
  mid_color = "white",
  value_text_size = 4,
  ci_text_size = 3,
  show_value = TRUE,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or a data frame with at least two numeric
columns. All non-numeric columns are dropped. Columns must be numeric.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values.
\code{"pairwise"} recomputes each association 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{p_value}{Logical (default \code{FALSE}). If \code{TRUE}, attach
permutation p-values for pairwise independence.}

\item{inference}{Character scalar. Use \code{"none"} (default) for estimates
only or \code{"permutation"} to request permutation p-values. If
\code{inference = "permutation"} is supplied with \code{p_value = FALSE},
p-values are inferred and returned.}

\item{n_perm}{Positive integer; number of permutations used when
\code{p_value = TRUE}. Default \code{999}.}

\item{seed}{Optional positive integer seed for permutation inference.}

\item{c_const}{Positive numeric tuning constant for the biloop
transformation. Default \code{4}.}

\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:
\code{"matrix"}, \code{"sparse"}, or \code{"edge_list"}.}

\item{threshold}{Non-negative absolute-value filter for non-matrix outputs.
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{...}{Deprecated compatibility aliases. Currently only
\code{check_na} is supported.}

\item{x, object}{An object of class \code{robust_dcor}.}

\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.}

\item{width}{Optional display width.}

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

\item{title}{Plot title.}

\item{low_color, high_color, mid_color}{Colors used in the heatmap.}

\item{value_text_size, ci_text_size}{Text sizes for plot labels.}

\item{show_value}{Logical; overlay numeric values if \code{TRUE}.}
}
\value{
A symmetric correlation result. Dense output inherits from
\code{robust_dcor}, \code{corr_matrix}, and \code{matrix}. Sparse and
edge-list outputs use the package-standard \code{corr_sparse} and
\code{corr_edge_list} representations.
}
\description{
Computes robust distance correlations by applying the biloop transformation
to each numeric variable and then computing unbiased distance correlation on
the transformed variables.
}
\details{
Permutation inference is computed for every unique column pair, so the
workload grows as \eqn{p(p-1)n_\mathrm{perm}/2}. A warning is emitted for
large requests; reduce \code{n_perm}, reduce the number of columns, or run
estimates without permutation p-values when this cost is not intended.

For each variable \eqn{x = (x_1,\ldots,x_n)}, the wrapper first robustly
standardises values using the median
\deqn{m_x = \mathrm{median}(x)}
and raw median absolute deviation
\deqn{s_x = \mathrm{median}\{|x_i - m_x|\}.}
If this scale is zero or non-finite, the implementation falls back to
\eqn{\mathrm{IQR}(x) / 1.34898} and then the ordinary sample standard
deviation. Columns with no positive finite fallback scale are treated as
degenerate.

The standardised value \eqn{z_i = (x_i - m_x) / s_x} is mapped to two
bounded coordinates by the biloop transformation
\deqn{\theta_i = 2\pi\tanh(z_i / c),}
\deqn{u_i =
\begin{cases}
c\{1-\cos(\theta_i)\}, & z_i > 0,\\
-c\{1-\cos(\theta_i)\}, & z_i < 0,\\
0, & z_i = 0,
\end{cases}}
and
\deqn{v_i = \sin(\theta_i).}
Pairwise distances are Euclidean distances in this transformed
two-dimensional space,
\deqn{D^{(j)}_{ab} =
\left[(u_{aj}-u_{bj})^2 + (v_{aj}-v_{bj})^2\right]^{1/2},\quad a \ne b,}
with zero diagonal.

The transformed distance matrix is U-centred as
\deqn{A^{(j)}_{ab} =
D^{(j)}_{ab} - \frac{r^{(j)}_a + r^{(j)}_b}{n - 2}
+ \frac{S^{(j)}}{(n - 1)(n - 2)},\quad a \ne b,}
where \eqn{r^{(j)}_a = \sum_{b \ne a}D^{(j)}_{ab}} and
\eqn{S^{(j)} = \sum_{a \ne b}D^{(j)}_{ab}}. The diagonal of
\eqn{A^{(j)}} is zero.

For variables \eqn{j} and \eqn{k}, the unbiased robust distance covariance
is
\deqn{\widehat{\mathrm{dCov}}^2_u(j,k) =
\frac{2}{n(n-3)}\sum_{a < b} A^{(j)}_{ab} A^{(k)}_{ab}.}
The corresponding robust distance correlation is the usual non-negative
distance-correlation ratio based on this covariance and the two transformed
distance variances. Small negative numerical artifacts are clipped to zero.
}
\note{
\code{robust_dcor()} is more robust to extreme observations than classical
\code{dcor()}, but it may downweight genuine tail dependence. Classical
\code{dcor()} may be preferable when tail dependence is the scientific target.
Comparing both methods is recommended.
}
\section{Relationship to \code{\link[=dcor]{dcor()}}}{

\code{robust_dcor()} is not a replacement for \code{dcor()}. It estimates distance
correlation after a bounded robust transformation. Large differences between
\code{dcor()} and \code{robust_dcor()} can indicate that the classical dependence
signal is driven by tail observations or outliers.
}

\examples{
## Non-linear dependence: both estimators detect association.
set.seed(1)
n <- 200
x <- rnorm(n)
y <- x^2 + rnorm(n, sd = 0.2)

X <- cbind(x = x, y = y)

classical <- dcor(X)
robust <- robust_dcor(X)
round(c(
  dcor = classical["x", "y"],
  robust_dcor = robust["x", "y"]
), 3)

## One diagonal outlier can inflate classical dCor more than robust dCor.
set.seed(45)
x <- rnorm(20)
y <- rnorm(20)
x[1] <- 10
y[1] <- 10
X_out <- cbind(x = x, y = y)

classical <- dcor(X_out)
robust <- robust_dcor(X_out)
round(c(
  dcor = classical["x", "y"],
  robust_dcor = robust["x", "y"]
), 3)

print(classical)
print(robust)
summary(robust)
estimate(robust)
tidy(robust)
plot(robust)

## Several variables.
set.seed(7)
z <- rnorm(120)
X_multi <- cbind(
  linear = z + rnorm(120, sd = 0.3),
  nonlinear = z^2 + rnorm(120, sd = 0.3),
  noise = rnorm(120),
  outlier = rnorm(120)
)
X_multi[1, "outlier"] <- 12
X_multi[1, "noise"] <- 12

robust_multi <- robust_dcor(X_multi)

print(robust_multi)
summary(robust_multi)
plot(robust_multi)

}
\references{
Leyder, J., Raymaekers, J., & Rousseeuw, P. J. (2025). Robust distance
correlation through bounded transformations.
}
\seealso{
\code{\link[=dcor]{dcor()}}, \code{\link[=wincor]{wincor()}}, \code{\link[=pbcor]{pbcor()}}, \code{\link[=skipped_corr]{skipped_corr()}}
}
\author{
Thiago de Paula Oliveira
}
