queryNeighbors: Query neighbors
In kmknn: k-Means for k-Nearest Neighbors

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/queryNeighbors.R

Find all neighboring data points within a certain distance of a query point with the KMKNN algorithm.

1
2
3

queryNeighbors(X, query, threshold, get.index=TRUE, get.distance=TRUE, 
    BPPARAM=SerialParam(), precomputed=NULL, transposed=FALSE, subset=NULL,
    raw.index=FALSE)

`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.
`threshold`	A positive numeric scalar specifying the maximum distance at which a point is considered a neighbor.
`get.index`	A logical scalar indicating whether the indices of the neighbors should be recorded.
`get.distance`	A logical scalar indicating whether distances to the neighbors should be recorded.
`BPPARAM`	A BiocParallelParam object indicating how the search should be parallelized.
`precomputed`	The precomputed output of `precluster` 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 neighbors should be identified.
`raw.index`	A logial scalar indicating whether raw column indices to `precomputed$data` should be returned.

This function uses the same algorithm described in findKNN to identify points in X that are neighbors (i.e., within a distance threshold) of each point in query. This requires both X and query to have the same number of dimensions.

By default, neighbors are identified for all data points within query. If subset is specified, 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 queryNeighbors 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 precluster directly to precompute the clustering. Advanced users can also set raw.index=TRUE, which yields results equivalent to running queryKNN with X=t(precomputed$data). This may be useful when dealing with multiple queries to a common precomputed object.

A list is returned containing:

index, if get.index=TRUE. This is a list of integer vectors where each entry corresponds to a point (denoted here as i) in query. The vector for i contains the set of row indices of all points in X that lie within threshold of point i. Points in each vector are not ordered, and i will always be included in its own set.
distance, if get.distance=TRUE. This is a list of numeric vectors where each entry corresponds to a point (as above) and contains the distances of the neighbors from i. Elements of each vector in distance match to elements of the corresponding vector in index.

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.

If raw.index=TRUE, the values in index refer to columns of precomputed$data.

Aaron Lun

precluster, findNeighbors

Y <- matrix(rnorm(100000), ncol=20)
Z <- matrix(rnorm(20000), ncol=20)
out <- queryNeighbors(Y, query=Z, threshold=1)
head(out$index)
head(out$distance)