gap_statistic

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

gap_statistic(features: ndarray, labels: ndarray, *, n_references: int = 10, random_state: int = 0) → float[source]

Gap statistic of one clustering (Tibshirani, Walther & Hastie, 2001).

Compares the achieved within-cluster dispersion against the dispersion expected from uniformly distributed noise spanning the same bounding box. A larger gap means the structure found is less likely to be an artefact of the data’s extent, so the score is maximised.

Parameters:

  • features – Sample matrix of shape (n_samples, n_features).

  • labels – Cluster label per sample, shape (n_samples,).

  • n_references – Uniform reference datasets to average over.

  • random_state – Seed for the reference datasets, making the score reproducible.

Returns:

log(E*[W_k]) - log(W_k); 0.0 when the clustering is degenerate (a single cluster or zero dispersion).

Raises:

ValueError – If features and labels disagree on sample count.