mojolearn.KNeighborsClassifier#

class mojolearn.KNeighborsClassifier(n_neighbors=5, query_tile=0, *, weights='uniform', metric='euclidean', algorithm='brute', p=2)#

Classifier that votes among the k nearest training points.

For each query, the classes of its n_neighbors nearest training points are counted and the most frequent wins; a tie goes to the lowest class in sorted order, as in cuML and scikit-learn. With weights='distance' each neighbor’s vote is weighted by 1 / distance. Neighbor search is exact brute force, as in NearestNeighbors.

Parameters:

  • n_neighbors (int, default 5) – Number of neighbors that vote. Must be between 1 and the number of training samples.

  • query_tile (int, default 0) – As in NearestNeighbors: memory use only, never the answer.

  • weights ({‘uniform’, ‘distance’} or None, default ‘uniform’) – ‘uniform’ (or None) gives every neighbor one vote. ‘distance’ follows scikit-learn: weight 1 / d, and when a query has neighbors at distance exactly zero, those neighbors get weight 1 and the others in that row get 0. A callable raises ValueError. ‘distance’ with metric='inner_product' raises ValueError (an inner product is a similarity, not a distance).

  • metric (str, default ‘euclidean’) – As in NearestNeighbors with algorithm='brute'.

  • algorithm ({‘brute’, ‘auto’}, default ‘brute’) – Exact brute force. ‘rbc’ raises ValueError here; use NearestNeighbors(algorithm='rbc').kneighbors and vote on the result instead.

  • p (float, default 2) – As in NearestNeighbors.

  • numeric_mode ({‘identical’, ‘fast’}, optional) – As in NearestNeighbors. ‘fast’ is available on Apple GPUs only.

Variables:

  • classes_ (list of int, or list of lists for a 2-D y) – Sorted unique labels per output, as Python ints (a list, not an ndarray).

  • outputs_2d_ (bool) – Whether y had more than one output column.

  • n_samples_fit_ (int) – Number of training samples.

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

  • used_query_tile_ (int) – Query batch size the last prediction ran with.

Examples

>>> import numpy as np, mojolearn
>>> rng = np.random.default_rng(0)
>>> X = rng.random((1000, 8), dtype=np.float32)
>>> y = (X[:, 0] > 0.5).astype(np.int32)
>>> clf = mojolearn.KNeighborsClassifier(n_neighbors=5).fit(X, y)
>>> labels = clf.predict(X[:10])
>>> proba = clf.predict_proba(X[:10])

See also

KNeighborsRegressor

User guide: Neighbors and vector search

Choosing an estimator

Methods

fit(X, y)

Store the training points and their labels.

get_params([deep])

kneighbors(X[, n_neighbors, return_distance])

Find the nearest fitted points to each query, nearest first.

load(path)

Load a model written by save.

numeric_mode_used()

The numeric mode this estimator runs in.

predict(X)

Predict the class of each query by neighbor vote.

predict_proba(X)

Return each query's vote fractions per class.

save(path)

Save the fitted model to an .npz file.

set_params(**params)

Set constructor parameters.

vendor_used()

The GPU backend this estimator runs on.

Attributes

classes_

Sorted unique labels seen at fit, as a list of ints; a list of such lists for a 2-D y.
save(path)#

Save the fitted model to an .npz file.

The file holds the training points, labels, classes and parameters. mojolearn.host_model(path) can predict from it on a CPU with no GPU.

Parameters:

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

Raises:

RuntimeError – If the model is not fitted.

classmethod load(path)#

Load a model written by save.

classes_ is rebuilt from the saved labels as fit builds it; a file whose stored classes disagree with its labels raises ValueError.

Parameters:

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

Returns:

KNeighborsClassifier – A fitted model, ready for predict.

fit(X, y)#

Store the training points and their labels.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training points; converted to float32.

  • y (array-like of int, shape (n_samples,) or (n_samples, n_outputs)) – Integer class labels of any values (negative values and gaps are fine) within the int32 range. A 2-D y votes each column separately. Float labels raise ValueError; cast them to int first (cuML requires int32 labels too).

Returns:

self

property classes_#

Sorted unique labels seen at fit, as a list of ints; a list of such lists for a 2-D y.

predict(X)#

Predict the class of each query by neighbor vote.

Parameters:

X (array-like of shape (n_queries, n_features)) – Query points; converted to float32.

Returns:

Array of int64, shape (n_queries,) or (n_queries, n_outputs) – The voted labels, in the original label values; 2-D when y was 2-D.

Raises:

ValueError – If the model is not fitted, X has the wrong number of features, or n_neighbors exceeds the number of training samples.

predict_proba(X)#

Return each query’s vote fractions per class.

Parameters:

X (array-like of shape (n_queries, n_features)) – Query points; converted to float32.

Returns:

Array of float32, shape (n_queries, n_classes), or a list of them – Columns follow classes_ order. For a 2-D y, one array per output, as cuML and scikit-learn return it.

kneighbors(X, n_neighbors=None, return_distance=True)#

Find the nearest fitted points to each query, nearest first.

Distances are the chosen metric’s (‘euclidean’ returns true, not squared, distances). Ties in distance are broken by the lower index, matching scikit-learn’s layout and ordering.

On a GPU the fitted points are copied to the device at the first call after fit and reused by later calls. Changing the array passed to fit in place after that is not seen; call fit again instead (as with cuML, whose fit copies the data to the device).

Parameters:

  • X (array-like of shape (n_queries, n_features)) – Query points; converted to float32.

  • n_neighbors (int, optional) – Neighbors per query; defaults to the constructor’s n_neighbors. Must be between 1 and n_samples_fit_.

  • return_distance (bool, default True) – Return the distances as well as the indices.

Returns:

  • distances (Array of shape (n_queries, n_neighbors), float32) – Returned only when return_distance is True.

  • indices (Array of shape (n_queries, n_neighbors), int64) – Row indices into the fitted data.

Raises:

ValueError – If the model is not fitted, X has the wrong number of features, or n_neighbors is out of range.

numeric_mode_used()#

The numeric mode this estimator runs in.

Returns:

str – 'identical' or 'fast', read from the compiled binary the estimator uses, not from the argument it was given.

set_params(**params)#

Set constructor parameters. The estimator is rebuilt through its constructor, so every constructor check runs again and any fitted state is dropped, as a new setting invalidates it.

vendor_used()#

The GPU backend this estimator runs on.

Returns:

str – 'metal', 'cuda' or 'hip', read from the compiled binary the estimator uses.