# 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_neighbors** : Default number of neighbors to query **radius** : Range of parameter space to use by default for `radius_neighbors` queries. **verbose** : Sets logging level. It must be one of `cuml.common.logger.level_*`. See [Verbosity Levels](../../cuml/index.html.md#verbosity-levels) for more info. **algorithm** : 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 **metric** : 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’. **p** : 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_params** : 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, from 4 to 8 > - usePrecomputedTables : (bool) whether to use precomputed tables
With the default `nlist=8`, IVF-PQ requires at least `2**(n_bits + 1)` rows in `X` (512 for the default `n_bits=8`). Reducing `n_bits` reduces this minimum. **metric_params** : Additional keyword arguments for the metric function. **n_jobs** : Ignored, here for scikit-learn API compatibility. **output_type** : 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](../../cuml/index.html.md#output-data-type-configuration) for more info. ### Methods | [`radius_neighbors_graph`](#cuml.neighbors.NearestNeighbors.radius_neighbors_graph)(self[, X, radius]) | Compute the (weighted) graph of neighbors within a radius. | |----------------------------------------------------------------------------------------------|--------------------------------------------------------------| ### Notes For an additional example see [the NearestNeighbors notebook](https://github.com/NVIDIA/cuml/blob/main/notebooks/nearest_neighbors_demo.ipynb). For additional docs, see [scikit-learn’s NearestNeighbors](https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.NearestNeighbors.html#sklearn.neighbors.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 ```python >>> 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L206) 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/neighbors/nearest_neighbors.pyx#L620) Fit GPU index for performing nearest neighbor queries. * **Parameters:** **X** : 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. **y** : 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L222) Create a cuml estimator from a scikit-learn estimator. * **Parameters:** **model** : 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L191) 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/neighbors/nearest_neighbors.pyx#L701) Query the GPU index for the k nearest neighbors of column vectors in X. * **Parameters:** **X** : 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_neighbors** : 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_precision** : 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:** **distances** : The distances of the k-nearest neighbors for each column vector in X **indices** : The indices of the k-nearest neighbors for each column vector in X #### kneighbors_graph(self, X=None, n_neighbors=None, mode='connectivity')[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/neighbors/nearest_neighbors.pyx#L942) Find the k nearest neighbors of column vectors in X and return as a sparse matrix in CSR format. * **Parameters:** **X** : 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_neighbors** : Number of neighbors to search. If not provided, the n_neighbors from the model instance is used **mode** : 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:** **A** : 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/neighbors/nearest_neighbors.pyx#L1188) Compute the (weighted) graph of neighbors within a radius. * **Parameters:** **X** : 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. **radius** : Radius of neighborhoods. The default is the value passed to the constructor. * **Returns:** **A** : 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 ```pycon >>> 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]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L200) 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