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 |
|---|---|---|
|
higher |
scikit-learn silhouette |
|
higher |
Calinski-Harabasz |
|
lower |
Davies-Bouldin |
|
higher |
entropy of cluster sizes over |
|
higher |
density-based silhouette on a kNN graph |
|
higher |
local-cores cluster validity |
|
higher |
mean-max index |
|
higher |
Fisher-LDA cluster validation |
|
higher |
density-based clustering validation |
|
lower |
model fit (k-means, mixtures) |
|
higher |
prediction strength (resampling) |
|
higher |
smallest per-cluster bootstrap Jaccard |
ark reported the density-based silhouette under the name silhouette; here
the two are kept apart.
Module Attributes
Whether each metric is better high ( |
Functions
|
Entropy of the cluster sizes divided by |
|
Agreement of a clustering with known labels. |
|
Internal validity of one labelling: how compact and separated its clusters are. |
|
Share of points whose cluster's majority true label is their own. |
|
A metric's value, or NaN when it is undefined for this labelling. |
|
Cluster sizes in label order. |
|
Validity of the clustering at every candidate number of clusters. |
|
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:
- Return type:
- 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:
- Return type:
- 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
ValueErrorwhen undefined (e.g. one cluster).*args – Positional arguments of the metric.
**kwargs – Keyword arguments of the metric.
- Return type:
- 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 whenmetric="precomputed"(then only silhouette and balance apply).labels (
ArrayLike) – Cluster labels.k (
int|None) – Intended number of clusters, forbalance; 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:
- Returns:
Metric name to value (NaN where undefined, e.g. a single cluster); see
DIRECTIONfor 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:
- Return type:
- 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:
- Return type:
- Returns:
ari,nmiandpurity.- 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 returnssum(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:
- Return type:
- 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
errormessage, rather than losing the other results.- Parameters:
X (
ArrayLike) – Data, or a square distance matrix for ametric="precomputed"clusterer.estimator (
BaseEstimator|None) – Clusterer with ann_clusters(orn_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:
- Returns:
One row per k with
inertia,bic, the metrics and the size of thesmallestcluster.
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