queryAnnoy {BiocNeighbors} | R Documentation

## Query nearest neighbors

### Description

Use the Annoy algorithm to query a dataset for nearest neighbors of points in another dataset.

### Usage

    queryAnnoy(X, query, k, get.index=TRUE, get.distance=TRUE, BPPARAM=SerialParam(),
        precomputed=NULL, transposed=FALSE, subset=NULL, ...)

### Arguments

`X` | A numeric matrix where rows correspond to data points and columns correspond to variables (i.e., dimensions).
`query` | A numeric matrix of query points, containing different data points in the rows but the same number and ordering of dimensions in the columns.
`k` | A positive integer scalar specifying the number of nearest neighbors to retrieve.
`get.index` | A logical scalar indicating whether the indices of the nearest neighbors should be recorded.
`get.distance` | A logical scalar indicating whether distances to the nearest neighbors should be recorded.
`BPPARAM` | A BiocParallelParam object indicating how the search should be parallelized.
`precomputed` | An AnnoyIndex object from running `buildAnnoy` on `X`.
`transposed` | A logical scalar indicating whether the `query` is transposed, in which case `query` is assumed to contain dimensions in the rows and data points in the columns.
`subset` | A vector indicating the rows of `query` (or columns, if `transposed=TRUE`) for which the nearest neighbors should be identified.
`...` | Further arguments to be passed to `buildAnnoy` if `precomputed=NULL`.

### Details

This function uses the same algorithm described in `findAnnoy` to identify points in `X` that are nearest neighbors of each point in `query`. This requires both `X` and `query` to have the same number of dimensions. Moreover, the upper bound for `k` is set at the number of points in `X`.

By default, nearest neighbors are identified for all data points within `query`. If `subset` is specified, nearest neighbors are only detected for the query points in the subset. This yields the same result as (but is more efficient than) subsetting the output matrices after running `queryKNN` on the full `query` (i.e., with `subset=NULL`).

If `transposed=TRUE`, this function assumes that `query` is already transposed, which saves a bit of time by avoiding an unnecessary transposition. Turning off `get.index` or `get.distance` may also provide a slight speed boost when these returned values are not of interest. Using `BPPARAM` will also split the search by query points across multiple processes.

If multiple queries are to be performed to the same `X`, it may be beneficial to use `buildAnnoy` directly to precompute the clustering. Note that when `precomputed` is supplied, the value of `X` is ignored.

### 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

`buildAnnoy` to build the index beforehand.

`findAnnoy` to identify k-NNs within `X`.

### Examples

    Y <- matrix(rnorm(100000), ncol=20)
    Z <- matrix(rnorm(20000), ncol=20)
    out <- queryAnnoy(Y, query=Z, k=25)
    head(out$index)
    head(out$distance)

[Package BiocNeighbors version 1.0.0 Index]