bcdcor: Pairwise Bias-Corrected Squared Distance Correlation

Description

Computes the U-centred bias-corrected squared distance-correlation statistic for numeric columns using a high-performance C++ backend. Unlike conventional distance correlation, this finite-sample statistic may be negative. It is the statistic used by the Székely-Rizzo bias-corrected distance-correlation t-test.

Usage

bcdcor(
  data,
  na_method = c("error", "pairwise", "complete"),
  p_value = FALSE,
  n_threads = getOption("matrixCorr.threads", 1L),
  output = c("matrix", "sparse", "edge_list"),
  threshold = 0,
  diag = TRUE,
  ...
)
# S3 method for bcdcor
print(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
# S3 method for bcdcor
plot(
  x,
  title = "Bias-corrected squared distance correlation heatmap",
  low_color = "firebrick3",
  mid_color = "white",
  high_color = "steelblue1",
  value_text_size = 4,
  show_value = TRUE,
  ...
)
# S3 method for bcdcor
summary(
  object,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
# S3 method for summary.bcdcor
print(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

Value

A symmetric correlation result where the (i, j) entry is the signed U-centred bias-corrected squared distance-correlation statistic. The object has class bcdcor. When p_value = TRUE, the inference

attribute contains bcdcor, statistic, parameter, and p_value.

Arguments

data: A numeric matrix or a data frame with at least two numeric columns. All non-numeric columns are dropped. Columns must be numeric.
na_method: Character scalar controlling missing-data handling. "error" rejects missing, NaN, and infinite values. "pairwise" recomputes each association on its own pairwise complete-case overlap. "complete" performs listwise deletion once across the retained numeric columns.
p_value: Logical (default FALSE). If TRUE, attach pairwise p-values, test statistics, and degrees of freedom from the bias-corrected distance-correlation t-test.
n_threads: Integer $\geq 1$. Number of OpenMP threads. Defaults to getOption("matrixCorr.threads", 1L).
output: Output representation for the computed estimates: "matrix", "sparse", or "edge_list".
threshold: Non-negative absolute-value filter for non-matrix outputs: keep entries with abs(value) >= threshold. Must be 0 when output = "matrix".
diag: Logical; whether to include diagonal entries in "sparse" and "edge_list" outputs.
...: Additional arguments passed to ggplot2::theme() or other ggplot2 layers.
x: An object of class summary.dcor.
digits: Integer; number of decimal places to print.
n: Optional row threshold for compact preview output.
topn: Optional number of leading/trailing rows to show when truncated.
max_vars: Optional maximum number of visible columns; NULL derives this from console width.
width: Optional display width; defaults to getOption("width").
show_ci: One of "yes" or "no".
title: Plot title. Default is "Distance correlation heatmap".
low_color, mid_color, high_color: Colours used in the bcdcor() heatmap.
value_text_size: Font size for displaying values. Default is 4.
show_value: Logical; if TRUE (default), overlay numeric values on the heatmap tiles.
object: An object of class dcor.

Difference between <code>dcor()</code> and <code>bcdcor()</code>

dcor() returns conventional nonnegative distance correlation $R_n$. dcor(squared = TRUE) returns conventional $R_n^2$. bcdcor() returns the U-centred bias-corrected squared statistic used by the t-test. In finite samples, bcdcor(x) is not generally equal to dcor(x)^2.

Author

Thiago de Paula Oliveira

Details

Let $A^{(x)}$ and $A^{(y)}$ be U-centred distance matrices. The U-centred construction provides an unbiased estimator of squared distance covariance, $$V_{n,U}^2(x,y)=\frac{1}{n(n-3)} \sum_{i \ne j} A^{(x)}_{ij} A^{(y)}_{ij}.$$ The bias-corrected squared distance-correlation statistic is $$R_n^\ast(x,y)= \frac{V_{n,U}^2(x,y)} {\sqrt{V_{n,U}^2(x,x)V_{n,U}^2(y,y)}}.$$ This ratio is signed and may be negative in finite samples.

When p_value = TRUE, the t statistic is $$T = \sqrt{M - 1}\frac{R_n^\ast} {\sqrt{1 - (R_n^\ast)^2}}, \quad M=\frac{n(n-3)}{2},$$ referenced to a Student $t$ distribution with $M-1$ degrees of freedom. The signed statistic is not clipped before inference.

References

Szekely, G. J., & Rizzo, M. L. (2013). The distance correlation t-test of independence. Journal of Multivariate Analysis, 117, 193-213.

Examples

Run this code

# \donttest{
# Bias-corrected versus conventional squared dCor
set.seed(100)
n <- 150
x <- rnorm(n)
y <- 0.6 * x + sqrt(1 - 0.6^2) * rnorm(n)
X <- cbind(x = x, y = y)

# These are related but are not the same finite-sample estimator:
# dcor(..., squared = TRUE) uses the conventional V-statistic,
# whereas bcdcor() uses U-centering and bias correction.
dcor(X, squared = TRUE)
bcdcor(X)

# Bias-corrected squared dCor can be negative in finite samples,
# particularly under weak dependence or independence.
# This is not a negative-dependence estimate.
set.seed(3)
x <- rnorm(80)
y <- rnorm(80)
X <- cbind(x = x, y = y)

bcdcor(X)

# Bias-corrected dCor t-test
set.seed(2026)
n <- 80
x <- rnorm(n)
y <- x^2 + rnorm(n, sd = 0.25)
X <- cbind(x = x, y = y)

fit <- bcdcor(X, p_value = TRUE)

fit
summary(fit)

inf <- attr(fit, "inference")
inf$bcdcor
inf$statistic
inf$parameter
inf$p_value

# bcdcor() supports the same missing-data modes as dcor().
X_miss <- cbind(
  a = c(1, 2, NA, 4, 5, 6),
  b = c(2, 3, 4, 5, NA, 7),
  c = c(6, 5, 4, 3, 2, 1)
)

bcdcor(X_miss, na_method = "complete")
bcdcor(X_miss, na_method = "pairwise")

# Edge-list thresholding uses absolute magnitude and preserves signs.
set.seed(3)
X <- cbind(x = rnorm(80), y = rnorm(80), z = rnorm(80))

bcdcor(
  X,
  output = "edge_list",
  threshold = 0.001,
  diag = FALSE
)
# }

Run the code above in your browser using DataLab