Clustering

base

Abstract base class for clustering backends.

Clusterer

Bases: ABC

Base interface for feature-space clustering algorithms.

Implementations wrap scikit-learn or custom clustering methods and expose a uniform fit / predict API.

cluster_centers_ abstractmethod property

cluster_centers_: Optional[ndarray]

Return cluster centroids if available.

Returns:

Type	Description
ndarray or None	Array of shape (n_clusters, n_features), or None if the method does not define explicit centers.

model abstractmethod property

model: Any

Return the underlying fitted model object for serialization.

Returns:

Type	Description
object	Backend-specific model instance.

fit abstractmethod

fit(X: ndarray) -> 'Clusterer'

Fit the clusterer to feature data.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
Clusterer	Fitted clusterer instance (self).

predict abstractmethod

predict(X: ndarray) -> np.ndarray

Assign cluster labels to feature data.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
ndarray	Integer cluster labels of shape (n_samples,).

clustering

Clustering backend factory and registry.

CLUSTERER_REGISTRY module-attribute

CLUSTERER_REGISTRY: Dict[str, Type[Clusterer]] = {'kmeans': SklearnKMeansClusterer, 'minibatch_kmeans': SklearnMiniBatchClusterer, 'regular_space': SklearnRegularSpaceClusterer}

SklearnKMeansClusterer

SklearnKMeansClusterer(n_clusters: int, random_state: Optional[int] = None, **kwargs: Any)

Bases: Clusterer

Wrap sklearn.cluster.KMeans for AdaptivePy.

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of clusters.	required
random_state	int or None	Random seed passed to KMeans.	None
**kwargs	Any	Additional keyword arguments forwarded to KMeans.	{}

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return KMeans cluster centers.

model property

model: Any

Return the fitted KMeans instance.

fit

fit(X: ndarray) -> 'SklearnKMeansClusterer'

Fit KMeans on the provided feature matrix.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnKMeansClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Predict cluster labels for X.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.

SklearnMiniBatchClusterer

SklearnMiniBatchClusterer(n_clusters: int, random_state: Optional[int] = None, **kwargs: Any)

Bases: Clusterer

Wrap sklearn.cluster.MiniBatchKMeans for large datasets.

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of clusters.	required
random_state	int or None	Random seed passed to MiniBatchKMeans.	None
**kwargs	Any	Additional keyword arguments forwarded to MiniBatchKMeans.	{}

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return MiniBatchKMeans cluster centers.

model property

model: Any

Return the fitted MiniBatchKMeans instance.

fit

fit(X: ndarray) -> 'SklearnMiniBatchClusterer'

Fit MiniBatchKMeans on the provided feature matrix.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnMiniBatchClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Predict cluster labels for X.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.

SklearnRegularSpaceClusterer

SklearnRegularSpaceClusterer(min_dist: float, max_clusters: Optional[int] = None, random_state: Optional[int] = None)

Bases: Clusterer

Greedy regular-space clustering in feature space.

This implements a distance-threshold variant commonly used in MD analysis: cluster seeds are chosen iteratively so that no two centers are closer than min_dist. All frames are then assigned to their nearest center.

Parameters:

Name	Type	Description	Default
min_dist	float	Minimum Euclidean distance between cluster centers.	required
max_clusters	int or None	Optional upper bound on the number of clusters. If None, clustering continues until no frame is farther than min_dist from existing centers.	None
random_state	int or None	Seed for shuffling frame order when selecting new centers.	None

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return regular-space cluster centers.

model property

model: Any

Return a dict representation of the fitted regular-space model.

fit

fit(X: ndarray) -> 'SklearnRegularSpaceClusterer'

Select regular-space centers and assign all frames.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnRegularSpaceClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Assign labels by nearest regular-space center.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.

create_clusterer

create_clusterer(method: str, n_clusters: int, random_state: int | None = None, params: Dict[str, Any] | None = None) -> Clusterer

Instantiate a registered clustering backend.

Parameters:

Name	Type	Description	Default
method	str	Clustering method name (kmeans, minibatch_kmeans, regular_space).	required
n_clusters	int	Target number of clusters (used by k-means variants; mapped to max_clusters for regular-space when applicable).	required
random_state	int or None	Random seed for reproducibility.	None
params	dict or None	Additional backend-specific parameters.	None

Returns:

Type	Description
Clusterer	Unfitted clusterer instance.

Raises:

Type	Description
ValueError	If method is not registered.

fit_clusterer

fit_clusterer(clusterer: Clusterer, X) -> Clusterer

Fit a clusterer and return it for chaining.

Parameters:

Name	Type	Description	Default
clusterer	Clusterer	Unfitted clusterer instance.	required
X	ndarray	Feature matrix.	required

Returns:

Type	Description
Clusterer	Fitted clusterer.

sklearn_kmeans

KMeans clustering via scikit-learn.

SklearnKMeansClusterer

SklearnKMeansClusterer(n_clusters: int, random_state: Optional[int] = None, **kwargs: Any)

Bases: Clusterer

Wrap sklearn.cluster.KMeans for AdaptivePy.

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of clusters.	required
random_state	int or None	Random seed passed to KMeans.	None
**kwargs	Any	Additional keyword arguments forwarded to KMeans.	{}

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return KMeans cluster centers.

model property

model: Any

Return the fitted KMeans instance.

fit

fit(X: ndarray) -> 'SklearnKMeansClusterer'

Fit KMeans on the provided feature matrix.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnKMeansClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Predict cluster labels for X.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.

sklearn_minibatch

MiniBatchKMeans clustering via scikit-learn.

SklearnMiniBatchClusterer

SklearnMiniBatchClusterer(n_clusters: int, random_state: Optional[int] = None, **kwargs: Any)

Bases: Clusterer

Wrap sklearn.cluster.MiniBatchKMeans for large datasets.

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of clusters.	required
random_state	int or None	Random seed passed to MiniBatchKMeans.	None
**kwargs	Any	Additional keyword arguments forwarded to MiniBatchKMeans.	{}

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return MiniBatchKMeans cluster centers.

model property

model: Any

Return the fitted MiniBatchKMeans instance.

fit

fit(X: ndarray) -> 'SklearnMiniBatchClusterer'

Fit MiniBatchKMeans on the provided feature matrix.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnMiniBatchClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Predict cluster labels for X.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.

regular_space

Regular-space clustering for molecular dynamics feature data.

Frames are assigned to clusters such that each cluster center is at least min_dist away from all previously selected centers (in feature space). Remaining frames are assigned to the nearest center.

SklearnRegularSpaceClusterer

SklearnRegularSpaceClusterer(min_dist: float, max_clusters: Optional[int] = None, random_state: Optional[int] = None)

Bases: Clusterer

Greedy regular-space clustering in feature space.

This implements a distance-threshold variant commonly used in MD analysis: cluster seeds are chosen iteratively so that no two centers are closer than min_dist. All frames are then assigned to their nearest center.

Parameters:

Name	Type	Description	Default
min_dist	float	Minimum Euclidean distance between cluster centers.	required
max_clusters	int or None	Optional upper bound on the number of clusters. If None, clustering continues until no frame is farther than min_dist from existing centers.	None
random_state	int or None	Seed for shuffling frame order when selecting new centers.	None

cluster_centers_ property

cluster_centers_: Optional[ndarray]

Return regular-space cluster centers.

model property

model: Any

Return a dict representation of the fitted regular-space model.

fit

fit(X: ndarray) -> 'SklearnRegularSpaceClusterer'

Select regular-space centers and assign all frames.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix of shape (n_samples, n_features).	required

Returns:

Type	Description
SklearnRegularSpaceClusterer	Fitted clusterer.

predict

predict(X: ndarray) -> np.ndarray

Assign labels by nearest regular-space center.

Parameters:

Name	Type	Description	Default
X	ndarray	Feature matrix.	required

Returns:

Type	Description
ndarray	Cluster labels.

Raises:

Type	Description
RuntimeError	If fit has not been called.