openquant.onc

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

get_onc_clusters

get_onc_clusters(
    corr_mat: Sequence[Sequence[float]],
    repeat: int,
    seed: int = 42,
) -> Any

Optimal Number of Clusters (ONC) partition of a correlation matrix.

Not from AFML: López de Prado, Machine Learning for Asset Managers (2020), section 4.4, Snippets 4.1-4.2. Correlations become distances sqrt((1 - rho) / 2) (inputs clamped to [-1, 1]), each item is represented by its row of that matrix, and k-means is run for every k from 2 to max(N - 1, 2), repeat times each; the partition with the highest silhouette t-statistic mean(S) / std(S) wins. Clusters scoring below average are re-clustered and kept only if that improves their mean t-statistic. Negative correlation means far apart. Each k-means run is one k-means++ initialisation (as scikit-learn's KMeans), all drawn from one random stream seeded by seed, so results are deterministic. ONC is a random search: clean structure comes back the same under any seed, but on real data the partition can depend on the seed; compare a few seeds and raise repeat before relying on one. The search starts at k = 2, so a matrix with no structure is still partitioned; a low mean silhouette is the sign the clusters are not real. Cost grows at least as N^3.

Parameters

corr_mat : list[list[float]]

N x N correlation matrix (N >= 2), one inner list per row. Symmetry and a unit diagonal are not checked.

repeat : int

Number of k-means initialisations per candidate k; must be positive.

seed : int, default 42

Seed of the random stream behind every k-means initialisation (the Rust DEFAULT_SEED when omitted).

Returns

dict[str, Any]

ordered_correlation (list[list[float]], the input permuted so each cluster's members are contiguous), clusters (dict[int, list[int]], cluster label to member indices in the input's row order) and silhouette_scores (list[float], one per item in the input's row order; 0 for a singleton cluster's member).

Raises

ValueError

If corr_mat is empty or ragged, or the core rejects the input (e.g. repeat of 0, a non-square matrix or fewer than two rows, or NaN entries that leave no candidate partition).