milia.cluster#

Clustering: clusterers, validity, model selection, stability, agreement and conformal sets.

class milia.cluster.BaseClusterer#

Bases: ClusterMixin, BaseEstimator, ABC

Shared fit and predict for every clusterer.

Subclasses implement _fit(X) -> labels and, when they can label new points, _predict(X) -> labels. Hyperparameters are keyword arguments of __init__, stored unchanged.

Variables:
  • labels – Cluster label of each training row; -1 marks noise.

  • n_clusters – Number of clusters found, noise excluded.

  • n_features_in – Number of features seen during fit.

Examples

A clusterer is written by implementing _fit (and _predict when it can label new points):

>>> import numpy as np
>>> class Sign(BaseClusterer):
...     def _fit(self, X):
...         return (X[:, 0] > 0).astype(int)
>>> model = Sign().fit(np.array([[-1.0], [2.0], [3.0]]))
>>> model.labels_.tolist(), model.n_clusters_, hasattr(model, "predict")
([0, 1, 1], 2, False)
fit(X, y=None)#

Cluster the training data.

Parameters:
  • X (ArrayLike) – Data of shape (n_samples, n_features), or a square distance matrix when the clusterer is built with metric="precomputed".

  • y (None) – Ignored; present for API consistency.

Return type:

BaseClusterer

Returns:

The fitted clusterer.

predict(X)#

Assign new rows to the fitted clusters.

Only available on clusterers that can label new points (centroid and mixture models); density and hierarchical clusterers do not define it.

Parameters:

X (ArrayLike) – Rows with the number of features seen in fit.

Return type:

ndarray

Returns:

One cluster label per row.

Examples

>>> import numpy as np
>>> from milia import make
>>> model = make("clusterer", "kmeans", n_clusters=2).fit(np.array([[0.0], [0.2], [5.0], [5.2]]))
>>> bool(model.predict([[0.1]])[0] == model.labels_[0])
True

Modules

ablation

Ablation of a clustering pipeline, one axis at a time and in pairs.

agreement

Agreement between clusterings: across algorithms, seeds, time windows and known groups.

base

Base class for clusterers, following scikit-learn's clustering API.

conformal

Split-conformal prediction sets for cluster membership (Lei, Rinaldo and Wasserman, 2015).

consensus

Consensus (ensemble) clustering through a co-association matrix (Fred and Jain, 2005).

describe

Describing clusters: when they peak, what share of energy falls in a window, what they explain.

fitting

Refitting a clusterer at a chosen number of clusters.

graph

Connectivity of the k-nearest-neighbour graph: is a split real geometry or an embedding artefact?

indices

Cluster validity indices beyond scikit-learn's silhouette, Calinski-Harabasz and Davies-Bouldin.

models

Registered clusterers, one module per model (see milia.core.registry).

search

Multi-objective search over whole clustering pipelines (Optuna, NSGA-II).

selection

Choosing the number of clusters.

stability

Resampling checks of whether a clustering is real or an artefact of one sample.

validation

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