Switch to new knncolle libraries with OpenMP/thread-based parallelization.

DESCRIPTION

@@ -1,24 +1,18 @@
 Package: BiocNeighbors
-Version: 1.21.2
-Date: 2022-12-17
+Version: 1.99.0
+Date: 2024-09-05
 Title: Nearest Neighbor Detection for Bioconductor Packages
 Authors@R: c(person("Aaron", "Lun", role=c("aut", "cre", "cph"),
     email="[email protected]"))
 Imports: 
     Rcpp, 
-    S4Vectors, 
-    BiocParallel, 
-    stats, 
-    methods, 
-    Matrix
+    methods
 Suggests: 
+    BiocParallel, 
     testthat, 
     BiocStyle, 
     knitr, 
-    rmarkdown, 
-    FNN, 
-    RcppAnnoy, 
-    RcppHNSW
+    rmarkdown
 biocViews: Clustering, Classification
 Description: Implements exact and approximate methods for nearest neighbor 
     detection, in a framework that allows them to be easily switched within 
@@ -29,7 +23,10 @@ Description: Implements exact and approximate methods for nearest neighbor
     Parallelization is achieved for all methods by using BiocParallel. Functions 
     are also provided to search for all neighbors within a given distance. 
 License: GPL-3
-LinkingTo: Rcpp, RcppHNSW
+LinkingTo:
+    Rcpp, 
+    assorthead
 VignetteBuilder: knitr
-SystemRequirements: C++11
-RoxygenNote: 7.1.1
+SystemRequirements: C++17
+RoxygenNote: 7.3.2
+Encoding: UTF-8

NAMESPACE

@@ -1,96 +1,39 @@
 # Generated by roxygen2: do not edit by hand
 
-export(AnnoyIndex)
-export(AnnoyIndex_path)
-export(AnnoyIndex_search_mult)
 export(AnnoyParam)
-export(AnnoyParam_directory)
-export(AnnoyParam_ntrees)
-export(AnnoyParam_search_mult)
-export(ExhaustiveIndex)
 export(ExhaustiveParam)
-export(HnswIndex)
-export(HnswIndex_ef_search)
-export(HnswIndex_path)
 export(HnswParam)
-export(HnswParam_directory)
-export(HnswParam_ef_construction)
-export(HnswParam_ef_search)
-export(HnswParam_nlinks)
-export(KmknnIndex)
-export(KmknnIndex_cluster_centers)
-export(KmknnIndex_cluster_info)
 export(KmknnParam)
-export(KmknnParam_kmeans_args)
-export(VptreeIndex)
-export(VptreeIndex_nodes)
 export(VptreeParam)
-export(bndata)
 export(bndistance)
-export(bnorder)
-export(buildAnnoy)
-export(buildExhaustive)
-export(buildHnsw)
 export(buildIndex)
-export(buildKmknn)
-export(buildVptree)
-export(findAnnoy)
-export(findExhaustive)
-export(findHnsw)
+export(defineBuilder)
+export(findDistance)
 export(findKNN)
-export(findKmknn)
 export(findMutualNN)
 export(findNeighbors)
-export(findVptree)
-export(queryAnnoy)
-export(queryExhaustive)
-export(queryHnsw)
+export(queryDistance)
 export(queryKNN)
-export(queryKmknn)
 export(queryNeighbors)
-export(queryVptree)
-export(rangeFindExhaustive)
-export(rangeFindKmknn)
-export(rangeFindVptree)
-export(rangeQueryExhaustive)
-export(rangeQueryKmknn)
-export(rangeQueryVptree)
-exportClasses(AnnoyIndex)
 exportClasses(AnnoyParam)
-exportClasses(BiocNeighborIndex)
 exportClasses(BiocNeighborParam)
-exportClasses(ExhaustiveIndex)
 exportClasses(ExhaustiveParam)
-exportClasses(HnswIndex)
 exportClasses(HnswParam)
-exportClasses(KmknnIndex)
 exportClasses(KmknnParam)
-exportClasses(VptreeIndex)
 exportClasses(VptreeParam)
 exportMethods("[[")
 exportMethods("[[<-")
-exportMethods(bndata)
-exportMethods(bndistance)
-exportMethods(bnorder)
 exportMethods(buildIndex)
-exportMethods(dim)
-exportMethods(dimnames)
+exportMethods(defineBuilder)
+exportMethods(findDistance)
 exportMethods(findKNN)
 exportMethods(findNeighbors)
+exportMethods(queryDistance)
 exportMethods(queryKNN)
 exportMethods(queryNeighbors)
 exportMethods(show)
-import(BiocParallel)
 import(methods)
-importClassesFrom(S4Vectors,character_OR_NULL)
-importFrom(BiocParallel,SerialParam)
-importFrom(BiocParallel,bpmapply)
-importFrom(BiocParallel,bpnworkers)
-importFrom(Matrix,t)
 importFrom(Rcpp,sourceCpp)
-importFrom(S4Vectors,setValidity2)
-importFrom(methods,is)
 importFrom(methods,new)
 importFrom(methods,show)
-importFrom(stats,kmeans)
 useDynLib(BiocNeighbors)

R/AllClasses.R

@@ -7,34 +7,13 @@ setClass("BiocNeighborParam", contains="VIRTUAL", slots=c(distance="character"))
 setClass("ExhaustiveParam", contains="BiocNeighborParam")
 
 #' @export
-setClass("KmknnParam", contains="BiocNeighborParam", slots=c(kmeans.args="list"))
+setClass("KmknnParam", contains="BiocNeighborParam")
 
 #' @export
 setClass("VptreeParam", contains="BiocNeighborParam")
 
 #' @export
-setClass("AnnoyParam", contains="BiocNeighborParam", slots=c(ntrees="integer", dir="character", search.mult="numeric")) 
+setClass("AnnoyParam", contains="BiocNeighborParam", slots=c(ntrees="integer", search.mult="numeric")) 
 
 #' @export
-setClass("HnswParam", contains="BiocNeighborParam", slots=c(nlinks="integer", ef.construction="integer", dir="character", ef.search="integer")) 
-
-# Defines the BiocNeighborIndex class and derivatives.
-
-#' @export
-#' @importClassesFrom S4Vectors character_OR_NULL
-setClass("BiocNeighborIndex", contains="VIRTUAL", slots=c(data="matrix", NAMES="character_OR_NULL", distance="character"))
-
-#' @export
-setClass("ExhaustiveIndex", contains="BiocNeighborIndex")
-
-#' @export
-setClass("KmknnIndex", contains="BiocNeighborIndex", slots=c(centers="matrix", info="list", order="integer"))
-
-#' @export
-setClass("VptreeIndex", contains="BiocNeighborIndex", slots=c(order="integer", nodes="list"))
-
-#' @export
-setClass("AnnoyIndex", contains="BiocNeighborIndex", slots=c(path="character", search.mult="numeric"))
-
-#' @export
-setClass("HnswIndex", contains="BiocNeighborIndex", slots=c(path="character", ef.search="integer"))
+setClass("HnswParam", contains="BiocNeighborParam", slots=c(nlinks="integer", ef.construction="integer", ef.search="integer")) 

R/AllGenerics.R

@@ -1,46 +1,51 @@
 #' @export
 #' @rdname buildIndex
-setGeneric("buildIndex", signature=c("BNPARAM"), 
-    function(X, ..., BNPARAM) 
-        standardGeneric("buildIndex")
-)
+setGeneric("buildIndex", signature=c("X", "BNPARAM"), function(X, transposed=FALSE, ..., BNPARAM=NULL) standardGeneric("buildIndex"))
 
 #' @export
-#' @rdname findKNN-methods
-setGeneric("findKNN", signature=c("BNINDEX", "BNPARAM"), 
-    function(X, k, ..., BNINDEX, BNPARAM) 
-        standardGeneric("findKNN")
-)
+#' @rdname defineBuilder 
+setGeneric("defineBuilder", signature="BNPARAM", function(BNPARAM) standardGeneric("defineBuilder"))
 
-#' @export
-#' @rdname queryKNN-methods
-setGeneric("queryKNN", signature=c("BNINDEX", "BNPARAM"), 
-    function(X, query, k, ..., BNINDEX, BNPARAM) 
-        standardGeneric("queryKNN")
-)
+# This is explicitly a S4 generic so that developers can extend it at the R
+# level, not at the C++ level. We need to support dispatch on both X and
+# BNPARAM as X could be an arbitrary index structure (i.e., not an external
+# pointer). If we only dispatched on BNPARAM, a user could call the method with
+# a prebuilt X that doesn't match the BNPARAM. This means that the developer of
+# the BNPARAM method would be responsible for figuring out what to do with a X
+# that they don't know anything about, which is pretty weird.
 
 #' @export
-#' @rdname findNeighbors-methods
-setGeneric("findNeighbors", signature=c("BNINDEX", "BNPARAM"), 
-    function(X, threshold, ..., BNINDEX, BNPARAM)
-        standardGeneric("findNeighbors")
-)
+#' @rdname findKNN
+setGeneric("findKNN", signature=c("X", "BNPARAM"), function(X, k, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
+    standardGeneric("findKNN")
+})
 
 #' @export
-#' @rdname queryNeighbors-methods
-setGeneric("queryNeighbors", signature=c("BNINDEX", "BNPARAM"), 
-    function(X, query, threshold, ..., BNINDEX, BNPARAM)
-        standardGeneric("queryNeighbors")
-)
+#' @rdname queryKNN
+setGeneric("queryKNN", signature=c("X", "BNPARAM"), function(X, query, k, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, transposed=FALSE, ..., BNPARAM=NULL) {
+    standardGeneric("queryKNN")
+})
 
 #' @export
-setGeneric("bnorder", function(x) standardGeneric("bnorder"))
+#' @rdname findNeighbors
+setGeneric("findNeighbors", signature=c("X", "BNPARAM"), function(X, threshold, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
+    standardGeneric("findNeighbors")
+})
 
 #' @export
-setGeneric("bndata", function(x) standardGeneric("bndata"))
+#' @rdname queryNeighbors
+setGeneric("queryNeighbors", signature=c("X", "BNPARAM"), function(X, query, threshold, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, transposed=FALSE, ..., BNPARAM=NULL) {
+    standardGeneric("queryNeighbors")
+})
 
 #' @export
-setGeneric("bndistance", function(x) standardGeneric("bndistance"))
+#' @rdname findDistance
+setGeneric("findDistance", signature=c("X", "BNPARAM"), function(X, k, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
+    standardGeneric("findDistance")
+})
 
-# Generic purely for internal use, to help in defining other S4 methods.
-setGeneric("spill_args", function(x) standardGeneric("spill_args"))
+#' @export
+#' @rdname queryDistance
+setGeneric("queryDistance", signature=c("X", "BNPARAM"), function(X, query, k, num.threads=1, subset=NULL, transposed=FALSE, ..., BNPARAM=NULL) {
+    standardGeneric("queryDistance")
+})