Is this page helpful?

NearestNeighbors#

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

NearestNeighbors is an queries neighborhoods from a given set of datapoints. Currently, cuML supports k-NN queries, which define the neighborhood as the closest k neighbors to each query point.

Parameters:
n_neighborsint (default=5)

Default number of neighbors to query

radiusfloat (default=1.0)

Range of parameter space to use by default for radius_neighbors queries.

verboseint or boolean, default=False

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

algorithmstring (default=’auto’)

The query algorithm to use. Valid options are:

  • 'auto': to automatically select brute-force or random ball cover based on data shape and metric

  • 'rbc': for the random ball algorithm, which partitions the data space and uses the triangle inequality to lower the number of potential distances. Currently, this algorithm supports Haversine (2d) and Euclidean in 2d and 3d.

  • 'brute': for brute-force, slow but produces exact results

  • 'ivfflat': for inverted file, divide the dataset in partitions and perform search on relevant partitions only

  • 'ivfpq': for inverted file and product quantization, same as inverted list, in addition the vectors are broken in n_features/M sub-vectors that will be encoded thanks to intermediary k-means clusterings. This encoding provide partial information allowing faster distances calculations

metricstring (default=’euclidean’).

Distance metric to use. Supported metrics include: ‘l1’, ‘cityblock’, ‘taxicab’, ‘manhattan’, ‘euclidean’, ‘l2’, ‘sqeuclidean’, ‘canberra’, ‘minkowski’, ‘lp’, ‘chebyshev’, ‘linf’, ‘jensenshannon’, ‘cosine’, ‘braycurtis’, ‘jaccard’, ‘hellinger’, ‘correlation’, ‘inner_product’. The 'ivfflat' and 'ivfpq' algorithms only support: ‘euclidean’, ‘l2’, ‘sqeuclidean’, ‘cosine’, ‘correlation’, ‘inner_product’, whereas the 'rbc' algorithm only supports ‘euclidean’, ‘l2’, and ‘haversine’ (≤3 dimensions only). For sparse inputs, only the 'brute' algorithm is supported, with metrics: ‘l1’, ‘cityblock’, ‘taxicab’, ‘manhattan’, ‘euclidean’, ‘l2’, ‘canberra’, ‘minkowski’, ‘lp’, ‘chebyshev’, ‘linf’, ‘cosine’, ‘inner_product’, ‘jaccard’, ‘hellinger’.

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.

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.

Methods

radius_neighbors_graph(self[, X, radius])

Compute the (weighted) graph of neighbors within a radius.

Notes

For an additional example see the NearestNeighbors notebook.

For additional docs, see scikit-learn’s NearestNeighbors.

Pickling NearestNeighbors instances is supported for all algorithms. However, for RBC, IVFPQ or IVFFlat the index will currently be rebuilt upon load rather than serialized as part of the pickled binary. For approximate indices like IVFPQ or IVFFlat this may result in small differences between the original and reloaded models, as the generated indices may differ.

Examples

>>> import cudf
>>> from cuml.neighbors import NearestNeighbors
>>> from cuml.datasets import make_blobs

>>> X, _ = make_blobs(n_samples=5, centers=5,
...                   n_features=10, random_state=42)

>>> # build a cudf Dataframe
>>> X_cudf = cudf.DataFrame(X)

>>> # fit model
>>> model = NearestNeighbors(n_neighbors=3)
>>> model.fit(X)
NearestNeighbors(n_neighbors=3)

>>> # get 3 nearest neighbors
>>> distances, indices = model.kneighbors(X_cudf)

>>> # print results
>>> print(indices)
0  1  2
0  0  3  1
1  1  3  0
2  2  4  0
3  3  0  1
4  4  2  0
>>> print(distances)
        0          1          2
0  0.007812  24.786566  26.399996
1  0.000000  24.786566  30.045017
2  0.007812   5.458400  27.051241
3  0.000000  26.399996  27.543869
4  0.000000   5.458400  29.583437
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=None) → 'NearestNeighbors'[source]#

Fit GPU index for performing nearest neighbor queries.

Parameters:
Xarray-like (device or host) shape = (n_samples, n_features)

Dense or sparse matrix with dtype float32 or float64. Acceptable dense 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)

radius_neighbors_graph(self, X=None, radius=None)[source]#

Compute the (weighted) graph of neighbors within a radius.

Parameters:
Xarray-like, default=None

The query point or points. If not provided, neighbors of each indexed point are returned. In this case, the query point is not considered its own neighbor.

radiusfloat, default=None

Radius of neighborhoods. The default is the value passed to the constructor.

Returns:
Asparse-matrix of shape (n_queries, n_samples_fit)

The neighborhood graph, in CSR format.

Notes

This method is most efficient when the instance is fit with algorithm="rbc". Other algorithms will build a temporary RBC index per-call, which adds a small overhead.

Only euclidean/l2 metrics and dense inputs are currently supported.

Examples

>>> import cupy as cp
>>> from cuml.neighbors import NearestNeighbors
>>> X = cp.array([[0], [3], [1]])
>>> nn = NearestNeighbors().fit(X)
>>> A = nn.radius_neighbors_graph(X, radius=1.5)
>>> A.toarray()
array([[1., 0., 1.],
       [0., 1., 0.],
       [1., 0., 1.]])
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