Is this page helpful?

KNeighborsClassifier#

class cuml.neighbors.KNeighborsClassifier( *, n_neighbors=5, algorithm='auto', metric='euclidean', weights='uniform', p=2, algo_params=None, metric_params=None, n_jobs=None, verbose=False, output_type=None, )#

K-Nearest Neighbors Classifier is an instance-based learning technique, that keeps training samples around for prediction, rather than trying to learn a generalizable set of model parameters.

Parameters:

n_neighborsint (default=5)

Default number of neighbors to query

algorithmstring (default=’auto’)

The query algorithm to use. Currently, only ‘brute’ is supported.

metricstring (default=’euclidean’).

Distance metric to use.

weights{‘uniform’, ‘distance’} or callable, default=’uniform’

Weight function used in prediction. Possible values:

‘uniform’ : uniform weights. All points in each neighborhood are weighted equally.
‘distance’ : weight points by the inverse of their distance. In this case, closer neighbors of a query point will have a greater influence than neighbors which are further away.
[callable] : a user-defined function which accepts an array of distances, and returns an array of the same shape containing the weights.

pfloat (default=2)

Parameter for the Minkowski metric. When p = 1, this is equivalent to manhattan distance (l1), and euclidean distance (l2) for p = 2. For arbitrary p, minkowski distance (lp) is used.

algo_paramsdict, optional (default=None)

Used to configure the nearest neighbor algorithm to be used. If set to None, parameters will be generated automatically. Parameters for algorithm 'brute' when inputs are sparse:

batch_size_index : (int) number of rows in each batch of index array

batch_size_query : (int) number of rows in each batch of query array

Parameters for algorithm 'ivfflat':

nlist: (int) number of cells to partition dataset into

nprobe: (int) at query time, number of cells used for search

Parameters for algorithm 'ivfpq':

nlist: (int) number of cells to partition dataset into

nprobe: (int) at query time, number of cells used for search

M: (int) number of subquantizers

n_bits: (int) bits allocated per subquantizer

usePrecomputedTables : (bool) whether to use precomputed tables

metric_paramsdict, optional (default = None)

Additional keyword arguments for the metric function.

n_jobsint (default = None)

Ignored, here for scikit-learn API compatibility.

verboseint or boolean, default=False

Sets logging level. It must be one of cuml.common.logger.level_*. See Verbosity Levels for more info.

output_type{None, ‘input’, ‘cupy’, ‘numpy’, ‘cudf’, ‘pandas’}, default=None

Return results and set estimator attributes to the indicated output type. If None, the output type set at the module level (cuml.global_settings.output_type) will be used. See Output Data Type Configuration for more info.

Attributes:

outputs_2d_: KNeighborsClassifier.outputs_2d_(self)

Methods

`fit`(self, X, y)	Fit a GPU index for k-nearest neighbors classifier model.
`predict`(self, X)	Use the trained k-nearest neighbors classifier to predict the labels for X
`predict_proba`(self, X)	Use the trained k-nearest neighbors classifier to predict the label probabilities for X

Notes

For additional docs, see scikitlearn’s KNeighborsClassifier.

Examples

>>> from cuml.neighbors import KNeighborsClassifier
>>> from cuml.datasets import make_blobs
>>> from cuml.model_selection import train_test_split

>>> X, y = make_blobs(n_samples=100, centers=5,
...                   n_features=10, random_state=5)
>>> X_train, X_test, y_train, y_test = train_test_split(
...     X, y, train_size=0.80, random_state=5)

>>> knn = KNeighborsClassifier(n_neighbors=10)

>>> knn.fit(X_train, y_train)
KNeighborsClassifier(n_neighbors=10)
>>> knn.predict(X_test)
array([1., 2., 2., 3., 4., 2., 4., 4., 2., 3., 1., 4., 3., 1., 3., 4., 3., # noqa: E501
    4., 1., 3.], dtype=float32)

as_sklearn()[source]#

Convert this estimator into an equivalent scikit-learn (or scikit-learn extension) estimator.

Returns:

sklearn.base.BaseEstimator: A scikit-learn compatible estimator instance that mirrors the trained state of the current estimator.

fit(self, X, y) → 'KNeighborsClassifier'[source]#

Fit a GPU index for k-nearest neighbors classifier model.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
yarray-like (device or host) shape = (n_samples, 1): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.

classmethod from_sklearn(model)[source]#

Create a cuml estimator from a scikit-learn estimator.

Parameters:

modelsklearn.base.BaseEstimator: A compatible scikit-learn (or scikit-learn extension) estimator.

Returns:

cls: A new instance of this cuml estimator class that mirrors the state of the input estimator.

Notes

output_type of the estimator is set to “numpy” by default, as these cannot be inferred from training arguments. If something different is required, then please use cuml’s output_type configuration utilities.

get_params(deep=True)[source]#: Returns a dict of all params owned by this class. If the child class has appropriately overridden the _get_param_names method and does not need anything other than what is there in this method, then it doesn’t have to override this method

kneighbors( self, X=None, n_neighbors=None, return_distance=True, *, two_pass_precision=False, )[source]#

Query the GPU index for the k nearest neighbors of column vectors in X.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
n_neighborsInteger: Number of neighbors to search. If not provided, the n_neighbors from the model instance is used (default=10)
return_distance: Boolean: If False, distances will not be returned
two_pass_precisionbool, optional (default = False): When set to True, a slow second pass will be used to improve the precision of results returned for searches using L2-derived metrics. FAISS uses the Euclidean distance decomposition trick to compute distances in this case, which may result in numerical errors for certain data. In particular, when several samples are close to the query sample (relative to typical inter-sample distances), numerical instability may cause the computed distance between the query and itself to be larger than the computed distance between the query and another sample. As a result, the query is not returned as the nearest neighbor to itself. If this flag is set to true, distances to the query vectors will be recomputed with high precision for all retrieved samples, and the results will be re-sorted accordingly. Note that for large values of k or large numbers of query vectors, this correction becomes impractical in terms of both runtime and memory. It should be used with care and only when strictly necessary (when precise results are critical and samples may be tightly clustered).

Returns:

distancescuDF, CuPy or NumPy object depending on cuML’s output typeconfiguration, shape =(n_samples, n_features): The distances of the k-nearest neighbors for each column vector in X
indicescuDF, CuPy or NumPy object depending on cuML’s output typeconfiguration, shape =(n_samples, n_features): The indices of the k-nearest neighbors for each column vector in X

kneighbors_graph( self, X=None, n_neighbors=None, mode='connectivity', )[source]#

Find the k nearest neighbors of column vectors in X and return as a sparse matrix in CSR format.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
n_neighborsInteger: Number of neighbors to search. If not provided, the n_neighbors from the model instance is used
modestring (default=’connectivity’): Values in connectivity matrix: ‘connectivity’ returns the connectivity matrix with ones and zeros, ‘distance’ returns the edges as the distances between points with the requested metric.

Returns:

Asparse graph in CSR format, shape = (n_samples, n_samples_fit): n_samples_fit is the number of samples in the fitted data where A[i, j] is assigned the weight of the edge that connects i to j. Values will either be ones/zeros or the selected distance metric. Return types are either cupy’s CSR sparse graph (device) or numpy’s CSR sparse graph (host)

property outputs_2d_#: Whether the output is 2d

predict(self, X)[source]#

Use the trained k-nearest neighbors classifier to predict the labels for X

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.

Returns:

X_newcuDF, CuPy or NumPy object depending on cuML’s output type configuration, shape = (n_samples, 1)

Labels predicted

For more information on how to configure cuML’s output type, refer to: Output Data Type Configuration.

predict_proba(self, X)[source]#

Use the trained k-nearest neighbors classifier to predict the label probabilities for X

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.

Returns:

X_newcuDF, CuPy or NumPy object depending on cuML’s output type configuration, shape = (n_samples, 1)

Labels probabilities

For more information on how to configure cuML’s output type, refer to: Output Data Type Configuration.

score(X, y, sample_weight=None, **kwargs)[source]#

Scoring function for classifier estimators based on mean accuracy.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
yarray-like (device or host) shape = (n_samples, 1): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
sample_weightarray-like (device or host) shape = (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.

Returns:

scorefloat: Accuracy of self.predict(X) wrt. y (fraction where y == pred_y)

set_params(**params)[source]#: Accepts a dict of params and updates the corresponding ones owned by this class. If the child class has appropriately overridden the _get_param_names method and does not need anything other than what is, there in this method, then it doesn’t have to override this method