milia.cluster.graph#

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

A group that forms its own connected component of the kNN graph in the original feature space is genuinely separate; one that only separates after a non-linear embedding may be an artefact of the embedding.

Functions

components(X[, neighbors])

Connected components of the symmetrised k-nearest-neighbour graph.

connectivity(X[, neighbors])

Component count and smallest component size as the neighbourhood grows.

validate(mask, features, embedding[, labels])

Silhouette of a group against the rest in feature space and in an embedding.

milia.cluster.graph.components(X, neighbors=10)#

Connected components of the symmetrised k-nearest-neighbour graph.

Parameters:
  • X (ArrayLike) – Data.

  • neighbors (int) – Neighbours per point.

Return type:

tuple[int, ndarray]

Returns:

(count, labels) – number of components and the component of each row.

Examples

>>> import numpy as np
>>> X = np.r_[np.zeros((5, 2)), np.full((5, 2), 9.0)] + np.random.default_rng(0).normal(scale=0.1, size=(10, 2))
>>> components(X, 3)[0]
2
milia.cluster.graph.connectivity(X, neighbors=(5, 10, 15, 20, 30))#

Component count and smallest component size as the neighbourhood grows.

A component that survives large neighbourhoods is a genuinely separate group.

Parameters:
Return type:

DataFrame

Returns:

One row per size with components and smallest.

Examples

>>> import numpy as np
>>> X = np.r_[np.zeros((5, 2)), np.full((5, 2), 9.0)] + np.random.default_rng(0).normal(scale=0.1, size=(10, 2))
>>> connectivity(X, (3, 6))["components"].tolist()
[2, 1]
milia.cluster.graph.validate(mask, features, embedding, labels=None)#

Silhouette of a group against the rest in feature space and in an embedding.

A high embedding silhouette with a low feature-space silhouette suggests the embedding created the separation.

Parameters:
  • mask (ArrayLike) – Boolean membership of the group.

  • features (ArrayLike) – Original features.

  • embedding (ArrayLike) – Embedded coordinates.

  • labels (ArrayLike | None) – Labels to compare the group with by ARI; skipped when None.

Return type:

dict

Returns:

size, features, embedding and, when given, ari.

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 = validate(truth == 0, X, X[:, :1], truth == 0)
>>> out["size"], out["ari"]
(20, 1.0)