dcor: Distance Correlation and Energy Statistics

Common errors

• ValueError: x and y must have the same number of observations.

  cause The number of samples (rows) in the input arrays `x` and `y` do not match.
  fix Ensure that `x.shape[0]` is equal to `y.shape[0]`. If `x` and `y` are 1D arrays, they must have the same length.

• TypeError: unsupported operand type(s) for -: 'list' and 'list'

  cause dcor functions expect `numpy.ndarray` objects, but raw Python lists were passed directly.
  fix Convert your lists to NumPy arrays using `np.array(my_list)` before passing them to dcor functions.

• AttributeError: module 'dcor' has no attribute 'get_distance_correlation'

  cause Attempting to use an old function name `get_distance_correlation` which was deprecated and removed.
  fix Update your code to use the current function name `dcor.distance_correlation`.

• TypeError: independence_test() missing 1 required positional argument: 'n_bootstraps'

  cause The `independence_test` function requires the `n_bootstraps` argument to specify the number of bootstrap iterations.
  fix Add the `n_bootstraps` argument with an appropriate integer value, e.g., `dcor.independence_test(x, y, n_bootstraps=1000)`.

Warnings

• breaking The function `dcor.get_distance_correlation` was renamed to `dcor.distance_correlation` in version 0.4.0. Using the old name will result in an AttributeError.
  Fix: Update your code to use `dcor.distance_correlation`.
• gotcha Input data for all dcor functions (e.g., `distance_correlation`, `energy_distance`) must be NumPy arrays or objects convertible to them. Passing raw Python lists will lead to TypeError.
  Fix: Ensure your input data is converted to `numpy.ndarray` before passing it to dcor functions (e.g., `np.array(my_list)`).
• gotcha When performing statistical tests like `dcor.independence_test`, the `n_bootstraps` parameter is mandatory and determines the number of bootstrap samples used for p-value calculation. A too small value can lead to unreliable results.
  Fix: Always provide a sufficiently large `n_bootstraps` argument (e.g., 1000 or more for production) to `independence_test`.
• gotcha The input arrays `x` and `y` must have the same number of observations (rows). If they represent samples, they must be from the same number of experimental units.
  Fix: Reshape or filter your data to ensure `x.shape[0] == y.shape[0]` before computing statistics like distance correlation or energy distance.

Install

• pip install dcor Install stable version

Imports

• distance_correlation
  wrong:

  from dcor import get_distance_correlation

  correct:

  from dcor import distance_correlation

  The function was renamed in a previous major version for clarity.
• energy_distance

  from dcor import energy_distance

• independence_test

  from dcor import independence_test

Quickstart

This quickstart demonstrates how to calculate distance correlation, energy distance, and perform an independence test using dcor. It initializes sample NumPy arrays and applies the main functions, printing their results.

import numpy as np
import dcor

# Example data
x = np.array([1, 2, 3, 4, 5])
y = np.array([1, 2, 3, 4, 5])
z = np.array([5, 4, 3, 2, 1])
w = np.array([1, 2, 3, 4, 6]) # Slightly different for energy_distance

# Calculate distance correlation
dc_xy = dcor.distance_correlation(x, y)
dc_xz = dcor.distance_correlation(x, z)
print(f"Distance correlation (x, y): {dc_xy:.4f}")
print(f"Distance correlation (x, z): {dc_xz:.4f}")

# Calculate energy distance
ed_xw = dcor.energy_distance(x, w)
print(f"Energy distance (x, w): {ed_xw:.4f}")

# Perform independence test (requires bootstrapping)
# Note: n_bootstraps should be sufficiently large for real analysis
independence_p_value = dcor.independence_test(x, y, n_bootstraps=100).p_value
print(f"P-value for independence test (x, y): {independence_p_value:.4f}")