BiocNeighbors 1.16.0
Another application of the KMKNN or VP tree algorithms is to identify all neighboring points within a certain distance1 of the current point. We first mock up some data:
nobs <- 10000
ndim <- 20
data <- matrix(runif(nobs*ndim), ncol=ndim)
We apply the findNeighbors()
function to data
:
fout <- findNeighbors(data, threshold=1)
head(fout$index)
## [[1]]
## [1] 3281 3800 9501 305 3348 1 7117 3228 8747 3546 1804 5994 459
##
## [[2]]
## [1] 4409 9121 2 4900 9993 8530 6660 552
##
## [[3]]
## [1] 1213 826 3 8024
##
## [[4]]
## [1] 8757 4 3970 9262 4544 9748 4192 6736
##
## [[5]]
## [1] 2503 5 6141 9335 6297
##
## [[6]]
## [1] 3495 189 3990 6932 7645 196 6 9801 2322 3870 4752 6676 2936 6634 1791
## [16] 5639
head(fout$distance)
## [[1]]
## [1] 0.9857754 0.9773650 0.9404854 0.9942944 0.9602573 0.0000000 0.9042534
## [8] 0.9057015 0.9827123 0.9829827 0.9421145 0.9948691 0.9284862
##
## [[2]]
## [1] 0.7362391 0.8710882 0.0000000 0.9453632 0.9450004 0.9423378 0.9883144
## [8] 0.9083264
##
## [[3]]
## [1] 0.9818455 0.9696333 0.0000000 0.9957525
##
## [[4]]
## [1] 0.8947910 0.0000000 0.9874296 0.9334158 0.9535041 0.8979282 0.9647687
## [8] 0.9784890
##
## [[5]]
## [1] 0.9429062 0.0000000 0.9992934 0.9802357 0.9899397
##
## [[6]]
## [1] 0.9297604 0.9988726 0.9913927 0.9459340 0.9868624 0.9648743 0.0000000
## [8] 0.9485164 0.9924528 0.9817077 0.9238364 0.9036224 0.9262775 0.9869924
## [15] 0.9553448 0.8357605
Each entry of the index
list corresponds to a point in data
and contains the row indices in data
that are within threshold
.
For example, the 3rd point in data
has the following neighbors:
fout$index[[3]]
## [1] 1213 826 3 8024
… with the following distances to those neighbors:
fout$distance[[3]]
## [1] 0.9818455 0.9696333 0.0000000 0.9957525
Note that, for this function, the reported neighbors are not sorted by distance. The order of the output is completely arbitrary and will vary depending on the random seed. However, the identity of the neighbors is fully deterministic.
The queryNeighbors()
function is also provided for identifying all points within a certain distance of a query point.
Given a query data set:
nquery <- 1000
ndim <- 20
query <- matrix(runif(nquery*ndim), ncol=ndim)
… we apply the queryNeighbors()
function:
qout <- queryNeighbors(data, query, threshold=1)
length(qout$index)
## [1] 1000
… where each entry of qout$index
corresponds to a row of query
and contains its neighbors in data
.
Again, the order of the output is arbitrary but the identity of the neighbors is deterministic.
Most of the options described for findKNN()
are also applicable here.
For example:
subset
to identify neighbors for a subset of points.get.distance
to avoid retrieving distances when unnecessary.BPPARAM
to parallelize the calculations across multiple workers.raw.index
to return the raw indices from a precomputed index.Note that the argument for a precomputed index is precomputed
:
pre <- buildIndex(data, BNPARAM=KmknnParam())
fout.pre <- findNeighbors(BNINDEX=pre, threshold=1)
qout.pre <- queryNeighbors(BNINDEX=pre, query=query, threshold=1)
Users are referred to the documentation of each function for specific details.
sessionInfo()
## R version 4.2.1 Patched (2022-07-09 r82577)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur ... 10.16
##
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
##
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_GB/en_US.UTF-8
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] BiocParallel_1.32.0 BiocNeighbors_1.16.0 knitr_1.40
## [4] BiocStyle_2.26.0
##
## loaded via a namespace (and not attached):
## [1] Rcpp_1.0.9 magrittr_2.0.3 BiocGenerics_0.44.0
## [4] lattice_0.20-45 R6_2.5.1 rlang_1.0.6
## [7] fastmap_1.1.0 stringr_1.4.1 tools_4.2.1
## [10] parallel_4.2.1 grid_4.2.1 xfun_0.34
## [13] cli_3.4.1 jquerylib_0.1.4 htmltools_0.5.3
## [16] yaml_2.3.6 digest_0.6.30 bookdown_0.29
## [19] Matrix_1.5-1 BiocManager_1.30.19 S4Vectors_0.36.0
## [22] sass_0.4.2 codetools_0.2-18 cachem_1.0.6
## [25] evaluate_0.17 rmarkdown_2.17 stringi_1.7.8
## [28] compiler_4.2.1 bslib_0.4.0 stats4_4.2.1
## [31] jsonlite_1.8.3
The default here is Euclidean, but again, we can set distance="Manhattan"
in the BNPARAM
object if so desired.↩︎