queryKNN {BiocNeighbors} | R Documentation

## Query k-nearest neighbors

### Description

Find the k-nearest neighbors in one data set for each point in another query data set, using exact or approximate algorithms.

### Usage

    queryKNN(..., BNINDEX=NULL, BNPARAM=NULL)

### Arguments

`...` | Further arguments to pass to specific methods, including: `X`, a numeric data matrix where rows are points and columns are dimensions. `query`, a numeric query matrix where rows are points and columns are dimensions. `k`, an integer scalar for the number of nearest neighbors. `subset`, a vector specifying the subset of points in `X` to search. `get.index`, a logical scalar indicating whether to return row indices of the neighbors. `get.distance`, a logical scalar indicating whether to return distances to neighbors. `BPPARAM`, a BiocParallelParam object for parallelization. `transposed`, a logical scalar indicating whether `query` is transposed, i.e., with columns as points. Of these, only `query` and `k` are strictly mandatory.
`BNINDEX` | A BiocNeighborIndex object, or `NULL`.
`BNPARAM` | A BiocNeighborParam object, or `NULL` if `BININDEX` is supplied.

### Details

The class of `BNINDEX` and `BNPARAM` will determine whether dispatch is performed to `queryKmknn` or `queryAnnoy`. Only one of these arguments needs to be defined to resolve dispatch. However, if both are defined, they cannot specify different algorithms.

If `BNINDEX` is supplied, `X` does not need to be specified. In fact, any value of `X` will be ignored as all necessary information for the search is already present in `BNINDEX`.

### Value

A list is returned containing:

- `index`, if `get.index=TRUE`. This is an integer matrix where each row corresponds to a point (denoted here as i) in `query`. The row for i contains the row indices of `X` that are the nearest neighbors to point i, sorted by increasing distance from i.

- `distance`, if `get.distance=TRUE`. This is a numeric matrix where each row corresponds to a point (as above) and contains the sorted distances of the neighbors from i.

If `subset` is not `NULL`, each row of the above matrices refers to a point in the subset, in the same order as supplied in `subset`.

### Author(s)

Aaron Lun

### See Also

`queryKmknn` and `queryAnnoy` for specific methods.

### Examples

    Y <- matrix(rnorm(100000), ncol=20)
    Z <- matrix(rnorm(10000), ncol=20)
    str(k.out <- queryKNN(Y, Z, k=10))
    str(a.out <- queryKNN(Y, Z, k=10, BNPARAM=AnnoyParam()))

    k.dex <- buildKmknn(Y)
    str(k.out2 <- queryKNN(Y,Z,  k=10, BNINDEX=k.dex, BNPARAM=NULL))
    str(k.out3 <- queryKNN(Y,Z,  k=10, BNINDEX=k.dex, BNPARAM=KmknnParam()))

    a.dex <- buildAnnoy(Y)
    str(a.out2 <- queryKNN(Y,Z,  k=10, BNINDEX=a.dex, BNPARAM=NULL))
    str(a.out3 <- queryKNN(Y,Z,  k=10, BNINDEX=a.dex, BNPARAM=AnnoyParam()))

[Package BiocNeighbors version 1.0.0 Index]