mojolearn.HDBSCAN#

class mojolearn.HDBSCAN(min_cluster_size=5, min_samples=None, cluster_selection_epsilon=0.0, max_cluster_size=0, metric='euclidean', alpha=1.0, cluster_selection_method='eom', allow_single_cluster=False, prediction_data=False)[source]#

Bases: NumericModeMixin

Hierarchical density-based clustering (HDBSCAN).

Follows cuML’s cuml.cluster.HDBSCAN: builds the mutual reachability graph from exact nearest neighbors, its minimum spanning tree and the condensed cluster tree, then selects clusters by excess of mass or by leaf. Points in no cluster are labeled -1 (noise). X is read as float32; only the Euclidean metric is supported. A NaN or infinity in X, or fewer than 2 rows, raises an error.

Parameters:

  • min_cluster_size (int, default 5) – Smallest group of points that counts as a cluster. Must be between 2 and the number of rows.

  • min_samples (int or None, default None) – Number of neighbors used for the core distance. None means min_cluster_size, as in cuML and scikit-learn. Must be between 1 and the number of rows.

  • cluster_selection_epsilon (float, default 0.0) – A selected cluster born below this distance is merged into its first ancestor born above it. 0.0 disables merging. Must be finite and non-negative.

  • max_cluster_size (int, default 0) – Largest cluster the excess-of-mass selection may return. 0 means no limit.

  • metric ({‘euclidean’}, default ‘euclidean’) – Distance metric. Any other value raises ValueError.

  • alpha (float, default 1.0) – Distance scaling in the robust single linkage. Must be positive and finite.

  • cluster_selection_method ({‘eom’, ‘leaf’}, default ‘eom’) – ‘eom’ selects by excess of mass; ‘leaf’ selects the leaves of the condensed tree.

  • allow_single_cluster (bool, default False) – Allow the result to be a single cluster.

  • prediction_data (bool, default False) – Keep the condensed tree and build prediction data during fit, so approximate_predict, membership_vector, all_points_membership_vectors and save can be used. The clustering itself is the same either way.

Variables:

  • labels_ (Array of shape (n_samples,), int32) – Cluster of each training point, 0 .. n_clusters_ - 1, or -1 for noise. Numbered as cuML numbers them.

  • probabilities_ (Array of shape (n_samples,), float32) – Strength of each point’s membership in its cluster, 0 for noise.

  • core_distances_ (Array of shape (n_samples,), float32) – Distance from each point to its min_samples-th nearest neighbor, not counting the point itself.

  • n_clusters_ (int) – Number of clusters found.

  • n_outliers_ (int) – Number of noise points.

  • n_boruvka_rounds_ (int) – Number of Boruvka rounds the minimum spanning tree took.

  • n_condensed_clusters_ (int) – Number of clusters in the condensed tree.

  • n_features_in_ (int) – Number of features seen during fit.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> model = mojolearn.HDBSCAN(min_cluster_size=10, prediction_data=True).fit(X)
>>> labels = model.labels_
>>> new_labels, strengths = mojolearn.hdbscan.approximate_predict(model, X[:10])
__init__(min_cluster_size=5, min_samples=None, cluster_selection_epsilon=0.0, max_cluster_size=0, metric='euclidean', alpha=1.0, cluster_selection_method='eom', allow_single_cluster=False, prediction_data=False)[source]#

Methods

fit(X[, y])

Cluster X.

fit_predict(X[, y])

Cluster X and return labels_.

get_params([deep])

load(path)

Load a model written by save.

numeric_mode_used()

The numeric mode this estimator runs in.

save(path)

Save the fitted model to path as an .npz file.

set_params(**params)

Set constructor parameters.

vendor_used()

The GPU backend this estimator runs on.
fit(X, y=None)[source]#

Cluster X.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training data, read as float32.

  • y (ignored) – Present for scikit-learn API compatibility.

Returns:

self (HDBSCAN) – The fitted estimator.

Raises:

  • TypeError – If an integer parameter is not an int, alpha or cluster_selection_epsilon is not a number, or prediction_data is not a bool.

  • ValueError – For an unknown metric or cluster_selection_method, or a negative or non-finite cluster_selection_epsilon.

fit_predict(X, y=None)[source]#

Cluster X and return labels_.

Returns:

labels (Array of shape (n_samples,), int32)

save(path)[source]#

Save the fitted model to path as an .npz file.

The file holds what approximate_predict, membership_vector and all_points_membership_vectors read, including the training data. Load it with load, or with mojolearn.host_model(path) to predict new points on a machine with no GPU.

Parameters:

path (str or path-like) – Destination file.

Raises:

ValueError – If the model is not fitted, was fitted without prediction_data=True, or metric or cluster_selection_method is not given by name.

classmethod load(path)[source]#

Load a model written by save.

Arrays keep their saved dtypes. The result works with approximate_predict, membership_vector and all_points_membership_vectors.

Parameters:

path (str or path-like) – File written by HDBSCAN.save.

Returns:

model (HDBSCAN)

Raises:

ValueError – If the file is of another format or estimator, or is truncated or inconsistent.