queryKmknn {BiocNeighbors} | R Documentation |
Use the KMKNN algorithm to query a dataset for nearest neighbors of points in another dataset.
queryKmknn(X, query, k, 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. |
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 |
A KmknnIndex object from running |
transposed |
A logical scalar indicating whether the |
subset |
A vector indicating the rows of |
raw.index |
A logical scalar indicating whether column indices to the reordered data in |
... |
Further arguments to pass to |
This function uses the same algorithm described in findKmknn
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 queryKmknn
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 buildKmknn
directly to precompute the clustering.
Note that when precomputed
is supplied, the value of X
is ignored.
Advanced users can also set raw.index=TRUE
, which returns indices of neighbors in the reordered data set in precomputed
.
This may be useful when dealing with multiple queries to a common precomputed object.
See comments in ?findKmknn
regarding the warnings when tied distances are observed.
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
.
If raw.index=TRUE
, the values in index
refer to columns of KmknnIndex_clustered_data(precomputed)
.
Aaron Lun
Y <- matrix(rnorm(100000), ncol=20) Z <- matrix(rnorm(20000), ncol=20) out <- queryKmknn(Y, query=Z, k=25) head(out$index) head(out$distance)