openquant.codependence

Compiled from Rust (crates/pyopenquant). Signatures and types are from the shipped .pyi stubs; descriptions are the functions’ own docstrings, as help() shows them. All Python modules.

Functions

absolute_angular_distance

absolute_angular_distance(x: Sequence[float], y: Sequence[float]) -> float

Absolute angular distance sqrt((1 - |rho|) / 2) from the Pearson correlation of two series.

In [0, sqrt(1/2)] and 0 for rho = +-1: perfectly anti-correlated series are treated as identical, as suits long-short portfolios. López de Prado, Machine Learning for Asset Managers (2020), chapter 3. Pass returns or other stationary series, not price levels.

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

Returns

float

The absolute angular distance.

Raises

ValueError

If x and y differ in length, have fewer than two observations, or either series is constant.

angular_distance

angular_distance(x: Sequence[float], y: Sequence[float]) -> float

Angular distance sqrt((1 - rho) / 2) from the Pearson correlation rho of two series.

In [0, 1]: 0 for rho = 1 and 1 for rho = -1, so a negatively correlated asset is treated as a diversifier (suits long-only portfolios). López de Prado, Machine Learning for Asset Managers (2020), chapter 3; the distance layer under AFML chapter 16. Pass returns or other stationary series, not trending price levels.

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

Returns

float

The angular distance.

Raises

ValueError

If x and y differ in length, have fewer than two observations, or either series is constant.

distance_correlation

distance_correlation(x: Sequence[float], y: Sequence[float]) -> float

Distance correlation of two series (Székely et al., 2007).

Double-centres the matrices of pairwise absolute differences within each series and returns dCov(x, y) / sqrt(dVar(x) * dVar(y)), in [0, 1], which is zero only when the series are independent (unlike Pearson correlation). Memory is O(n^2) (about 16 MB at 1,000 observations).

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

Returns

float

The distance correlation.

Raises

ValueError

If x and y differ in length, have fewer than two observations, or either series is constant.

get_mutual_info

get_mutual_info(
    x: Sequence[float],
    y: Sequence[float],
    n_bins: int | None = None,
    normalize: bool = False,
) -> float

Mutual information I[X;Y] = H[X] + H[Y] - H[X,Y] from an equal-width 2-D histogram.

Estimated from an n_bins x n_bins histogram with natural logarithms. With n_bins=None the count comes from get_optimal_number_of_bins with the sample correlation. With normalize=True the result is divided by min(H[X], H[Y]) and lies in [0, 1]. The estimate is biased upward on small samples; compare values only at equal length and binning. Normalised mutual information is not a distance; use variation_of_information_score for clustering. López de Prado, Machine Learning for Asset Managers (2020), chapter 3.

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

n_bins : int | None, default None

Bins per axis; None picks the optimal count.

normalize : bool, default False

Divide by the smaller marginal entropy.

Returns

float

The (optionally normalised) mutual information, in nats.

Raises

ValueError

If x and y differ in length or are empty, have fewer than two observations with n_bins=None, n_bins is 0 or the bin rule fails, a series is constant with n_bins=None, or a marginal entropy is zero with normalize=True.

get_optimal_number_of_bins

get_optimal_number_of_bins(num_obs: int, corr_coef: float | None = None) -> int

Histogram bin count that minimises the bias of entropy estimates.

Hacine-Gharbi et al. (2012). With corr_coef=None uses the univariate (marginal entropy) rule; with the correlation rho of two series uses the bivariate (joint entropy) rule round(sqrt(1 + sqrt(1 + 24 N / (1 - rho^2))) / sqrt(2)). A correlation within 1e-4 of +-1 falls back to the univariate rule.

Parameters

num_obs : int

Number of observations N; must be positive.

corr_coef : float | None, default None

Sample correlation of the two series for the bivariate rule; None for the univariate rule.

Returns

int

The bin count.

Raises

ValueError

If num_obs is 0, or the rule does not yield a positive count (a NaN corr_coef).

squared_angular_distance

squared_angular_distance(x: Sequence[float], y: Sequence[float]) -> float

Squared angular distance sqrt((1 - rho^2) / 2) from the Pearson correlation of two series.

Like absolute_angular_distance, 0 for rho = +-1; it spreads out high correlations and compresses low ones. López de Prado, Machine Learning for Asset Managers (2020), chapter 3. Pass returns or other stationary series, not price levels.

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

Returns

float

The squared angular distance.

Raises

ValueError

If x and y differ in length, have fewer than two observations, or either series is constant.

variation_of_information_score

variation_of_information_score(
    x: Sequence[float],
    y: Sequence[float],
    n_bins: int | None = None,
    normalize: bool = False,
) -> float

Variation of information VI[X;Y] = H[X] + H[Y] - 2 I[X;Y] of two series (Meilă, 2007).

A true metric, estimated from equal-width histograms with natural logarithms: the uncertainty left in each variable once the other is known. With normalize=True it is divided by the joint entropy H[X,Y] and lies in [0, 1], with 0 meaning each variable determines the other. With n_bins=None the count comes from get_optimal_number_of_bins with the sample correlation. López de Prado, Machine Learning for Asset Managers (2020), chapter 3.

Parameters

x : list[float]

First series.

y : list[float]

Second series, paired with x.

n_bins : int | None, default None

Bins per axis; None picks the optimal count.

normalize : bool, default False

Divide by the joint entropy.

Returns

float

The (optionally normalised) variation of information.

Raises

ValueError

If x and y differ in length or are empty, have fewer than two observations with n_bins=None, n_bins is 0 or the bin rule fails, a series is constant with n_bins=None, or the joint entropy is zero with normalize=True.