milia.cluster.validation#

Internal and external validity of a clustering, and sweeps over the number of clusters.

Metric names used throughout milia, with their direction:

name

better

meaning

silhouette

higher

scikit-learn silhouette

calinski

higher

Calinski-Harabasz

davies

lower

Davies-Bouldin

balance

higher

entropy of cluster sizes over log(k)

densitysilhouette

higher

density-based silhouette on a kNN graph

lccv

higher

local-cores cluster validity

mmi

higher

mean-max index

cvflda

higher

Fisher-LDA cluster validation

dbcv, dbcvknn

higher

density-based clustering validation

inertia, bic

lower

model fit (k-means, mixtures)

strength

higher

prediction strength (resampling)

stability

higher

smallest per-cluster bootstrap Jaccard

ark reported the density-based silhouette under the name silhouette; here the two are kept apart.

Module Attributes

DIRECTION

Whether each metric is better high ("max") or low ("min").

Functions

balance(labels[, k])

Entropy of the cluster sizes divided by log(k).

external(pred, true)

Agreement of a clustering with known labels.

internal(X, labels[, k, extended, dbcv, metric])

Internal validity of one labelling: how compact and separated its clusters are.

purity(pred, true)

Share of points whose cluster's majority true label is their own.

safe(score, *args, **kwargs)

A metric's value, or NaN when it is undefined for this labelling.

sizes(labels[, noise])

Cluster sizes in label order.

sweep(X, ks[, estimator, resampling, ...])

Validity of the clustering at every candidate number of clusters.

tendency(X[, fraction, random_state])

Hopkins statistic: whether the data have a clustering tendency at all.

milia.cluster.validation.DIRECTION: dict[str, str] = {'balance': 'max', 'bic': 'min', 'calinski': 'max', 'cvflda': 'max', 'davies': 'min', 'dbcv': 'max', 'dbcvknn': 'max', 'densitysilhouette': 'max', 'inertia': 'min', 'lccv': 'max', 'mmi': 'max', 'silhouette': 'max', 'stability': 'max', 'strength': 'max', 'strengthstd': 'min'}#

Whether each metric is better high ("max") or low ("min").

milia.cluster.validation.sizes(labels, noise=False)#

Cluster sizes in label order.

Parameters:
  • labels (ArrayLike) – Cluster labels; -1 marks noise.

  • noise (bool) – Count the noise label as a cluster too.

Return type:

ndarray

Returns:

The size of each cluster.

Examples

>>> sizes([0, 0, 1, -1]).tolist(), sizes([0, 0, 1, -1], noise=True).tolist()
([2, 1], [1, 2, 1])
milia.cluster.validation.balance(labels, k=None)#

Entropy of the cluster sizes divided by log(k).

1 for equal sizes, near 0 when one cluster holds almost every point. The trust gate uses it to reject a “clustering” that only isolates an outlier.

Parameters:
  • labels (ArrayLike) – Cluster labels.

  • k (int | None) – Intended number of clusters; the number found when omitted.

Return type:

float

Returns:

The balance, NaN when k <= 1.

Examples

>>> balance([0, 0, 1, 1]), round(balance([0] * 9 + [1]), 2)
(1.0, 0.47)
milia.cluster.validation.safe(score, *args, **kwargs)#

A metric’s value, or NaN when it is undefined for this labelling.

Parameters:
  • score – Metric function raising ValueError when undefined (e.g. one cluster).

  • *args – Positional arguments of the metric.

  • **kwargs – Keyword arguments of the metric.

Return type:

float

Returns:

The value as a float, or NaN.

Examples

>>> from sklearn.metrics import silhouette_score
>>> safe(silhouette_score, np.zeros((4, 2)), [0, 0, 0, 0])
nan
milia.cluster.validation.internal(X, labels, k=None, extended=False, dbcv=False, metric='euclidean')#

Internal validity of one labelling: how compact and separated its clusters are.

Parameters:
  • X (ArrayLike) – The data the labels were fitted on, or a square distance matrix when metric="precomputed" (then only silhouette and balance apply).

  • labels (ArrayLike) – Cluster labels.

  • k (int | None) – Intended number of clusters, for balance; the number found when omitted.

  • extended (bool) – Also compute the density- and model-based indices (densitysilhouette, lccv, mmi, cvflda); slower.

  • dbcv (bool) – Also compute both DBCV variants (dbcv, dbcvknn); slowest.

  • metric (str) – "euclidean" or "precomputed".

Return type:

dict[str, float]

Returns:

Metric name to value (NaN where undefined, e.g. a single cluster); see DIRECTION for which way each is better.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> centres = np.repeat(np.array([[0.0, 0.0], [6.0, 6.0], [0.0, 6.0]]), 20, axis=0)
>>> X, truth = centres + rng.normal(scale=0.5, size=(60, 2)), np.repeat([0, 1, 2], 20)
>>> out = internal(X, truth)
>>> sorted(out), out["silhouette"] > 0.8
(['balance', 'calinski', 'davies', 'silhouette'], True)
milia.cluster.validation.purity(pred, true)#

Share of points whose cluster’s majority true label is their own.

Parameters:
  • pred (ndarray) – Predicted labels.

  • true (ndarray) – Known labels.

Return type:

float

Returns:

Purity in [0, 1].

Examples

>>> purity(np.array([0, 0, 1, 1]), np.array([0, 1, 1, 1]))
0.75
milia.cluster.validation.external(pred, true)#

Agreement of a clustering with known labels.

Adjusted Rand index and normalised mutual information are corrected so that chance agreement scores about 0. Purity is not, and favours many small clusters; read it with the other two.

Parameters:
  • pred (ArrayLike) – Predicted labels.

  • true (ArrayLike) – Known labels, e.g. planted archetypes or building types.

Return type:

dict[str, float]

Returns:

ari, nmi and purity.

Raises:

ValueError – If the two label arrays differ in length.

Examples

>>> external([0, 0, 1, 1], [1, 1, 0, 0])
{'ari': 1.0, 'nmi': 1.0, 'purity': 1.0}
milia.cluster.validation.tendency(X, fraction=0.1, random_state=0)#

Hopkins statistic: whether the data have a clustering tendency at all.

Compares the distance from uniformly drawn points of the bounding box to the nearest data point (u) with the distance from sampled data points to their nearest other data point (w), and returns sum(u) / (sum(u) + sum(w)). Values near 0.5 indicate points spread as uniformly as random ones, so there is nothing to cluster; values towards 1 indicate clusters (Hopkins and Skellam, 1954). Run it before choosing the number of clusters.

Parameters:
  • X (ArrayLike) – Data, meters by features.

  • fraction (float) – Share of the points used as the sample (at least ten points).

  • random_state (int) – Seed.

Return type:

float

Returns:

The statistic in [0, 1].

Raises:

ValueError – If fewer than twenty points are given.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> uniform = rng.random((300, 2))
>>> clustered = np.repeat(np.array([[0.0, 0.0], [5.0, 5.0]]), 150, axis=0) + rng.normal(
...     scale=0.3, size=(300, 2)
... )
>>> bool(tendency(uniform) < 0.65), bool(tendency(clustered) > 0.85)
(True, True)
milia.cluster.validation.sweep(X, ks, estimator=None, resampling=False, extended=False, dbcv=False, splits=10, bootstrap=100, random_state=42, jobs=-1)#

Validity of the clustering at every candidate number of clusters.

The clusterer is cloned and refitted at each k. Fits run in parallel across k; a k whose fit fails keeps its row, with NaN metrics and an error message, rather than losing the other results.

Parameters:
  • X (ArrayLike) – Data, or a square distance matrix for a metric="precomputed" clusterer.

  • ks (Sequence[int]) – Candidate numbers of clusters.

  • estimator (BaseEstimator | None) – Clusterer with an n_clusters (or n_components) hyperparameter; k-means with 50 restarts when omitted.

  • resampling (bool) – Also run prediction strength and bootstrap stability (the trust audit). Expensive: use on a short list of candidate k.

  • extended (bool) – Also compute the density- and model-based indices.

  • dbcv (bool) – Also compute both DBCV variants.

  • splits (int) – Prediction-strength splits.

  • bootstrap (int) – Bootstrap resamples for stability.

  • random_state (int) – Seed for the default k-means and the resampling.

  • jobs (int) – Parallel jobs across k.

Return type:

DataFrame

Returns:

One row per k with inertia, bic, the metrics and the size of the smallest cluster.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> centres = np.repeat(np.array([[0.0, 0.0], [6.0, 6.0], [0.0, 6.0]]), 20, axis=0)
>>> X, truth = centres + rng.normal(scale=0.5, size=(60, 2)), np.repeat([0, 1, 2], 20)
>>> scores = sweep(X, range(2, 6), jobs=1)
>>> int(scores.loc[scores["silhouette"].idxmax(), "k"])
3