Further editing.

R/RcppExports.R

@@ -17,12 +17,12 @@ generic_build <- function(builder, data) {
     .Call('_BiocNeighbors_generic_build', PACKAGE = 'BiocNeighbors', builder, data)
 }
 
-generic_find_knn <- function(prebuilt_ptr, num_neighbors, chosen, num_threads, last_distance_only, report_index, report_distance) {
-    .Call('_BiocNeighbors_generic_find_knn', PACKAGE = 'BiocNeighbors', prebuilt_ptr, num_neighbors, chosen, num_threads, last_distance_only, report_index, report_distance)
+generic_find_knn <- function(prebuilt_ptr, num_neighbors, force_variable_neighbors, chosen, num_threads, last_distance_only, report_index, report_distance) {
+    .Call('_BiocNeighbors_generic_find_knn', PACKAGE = 'BiocNeighbors', prebuilt_ptr, num_neighbors, force_variable_neighbors, chosen, num_threads, last_distance_only, report_index, report_distance)
 }
 
-generic_query_knn <- function(prebuilt_ptr, query, num_neighbors, num_threads, last_distance_only, report_index, report_distance) {
-    .Call('_BiocNeighbors_generic_query_knn', PACKAGE = 'BiocNeighbors', prebuilt_ptr, query, num_neighbors, num_threads, last_distance_only, report_index, report_distance)
+generic_query_knn <- function(prebuilt_ptr, query, num_neighbors, force_variable_neighbors, num_threads, last_distance_only, report_index, report_distance) {
+    .Call('_BiocNeighbors_generic_query_knn', PACKAGE = 'BiocNeighbors', prebuilt_ptr, query, num_neighbors, force_variable_neighbors, num_threads, last_distance_only, report_index, report_distance)
 }
 
 generic_find_all <- function(prebuilt_ptr, chosen, thresholds, num_threads, report_index, report_distance) {

R/findDistance.R

@@ -1,6 +1,6 @@
-#' Find the distance to the k-th nearest neighbor
+#' Distance to the k-th nearest neighbor
 #' 
-#' Find the distance to the k-th nearest neighbor for each point in a dataset, using a variety of algorithms.
+#' Find the distance to the k-th nearest neighbor for each point in a dataset.
 #' 
 #' @inheritParams findKNN
 #' 
@@ -11,7 +11,7 @@
 #' @return
 #' Numeric vector of length equal to the number of points in \code{X} (or \code{subset}, if provided),
 #' containing the distance from each point to its \code{k}-th nearest neighbor.
-#' This is equivalent to but faster than taking the last distance of the output from \code{\link{findKNN}}.
+#' This is equivalent to but more memory efficient than using \code{\link{findKNN}} and subsetting to the last distance.
 #'
 #' @author
 #' Aaron Lun
@@ -34,16 +34,17 @@
 NULL
 
 #' @export
-setMethod("findDistance", c("matrix", "ANY"), function(X, k, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
+setMethod("findDistance", c("matrix", "ANY"), function(X, k, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
     ptr <- buildIndex(X, ..., BNPARAM=BNPARAM)
-    callGeneric(ptr, k=k, get.index=get.index, get.distance=get.distance, num.threads=num.threads, subset=subset, ...)
+    callGeneric(ptr, k=k, num.threads=num.threads, subset=subset, ...)
 })
 
 #' @export
-setMethod("findDistance", c("externalptr", "ANY"), function(X, k, get.index=TRUE, get.distance=TRUE, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
+setMethod("findDistance", c("externalptr", "ANY"), function(X, k, num.threads=1, subset=NULL, ..., BNPARAM=NULL) {
     generic_find_knn(
         X, 
-        num_neighbors=k, 
+        num_neighbors=as.integer(k), 
+        force_variable_neighbors=is(k, "AsIs"),
         chosen=subset, 
         num_threads=num.threads, 
         last_distance_only=TRUE,

R/findKNN.R

@@ -1,13 +1,14 @@
 #' Find k-nearest neighbors
 #' 
-#' Find the k-nearest neighbors of each point in a dataset, using a variety of algorithms.
+#' Find the k-nearest neighbors of each point in a dataset.
 #' 
 #' @param X A numeric matrix where rows correspond to data points and columns correspond to variables (i.e., dimensions).
 #' Alternatively, a prebuilt index from \code{\link{buildIndex}}.
 #' @param k A positive integer scalar specifying the number of nearest neighbors to retrieve.
 #'
 #' Alternatively, an integer vector of length equal to the number of points in \code{X}, specifying the number of neighbors to identify for each point.
 #' If \code{subset} is provided, this should have length equal to the length of \code{subset}.
+#' Users should wrap this vector in an \link{AsIs} class to distinguish length-1 vectors from integer scalars.
 #'
 #' All \code{k} should be less than or equal to the number of points in \code{X} minus 1, otherwise the former will be capped at the latter with a warning.
 #' @param get.index A logical scalar indicating whether the indices of the nearest neighbors should be recorded.
@@ -68,6 +69,8 @@
 #' @seealso
 #' \code{\link{buildIndex}}, to build an index ahead of time.
 #'
+#' \code{\link{findDistance}}, to efficiently obtain the distance to the k-th nearest neighbor.
+#'
 #' @aliases
 #' findKNN,matrix,ANY-method
 #' findKNN,externalptr,ANY-method
@@ -99,7 +102,8 @@ setMethod("findKNN", c("externalptr", "ANY"), function(X, k, get.index=TRUE, get
 
     output <- generic_find_knn(
         X, 
-        num_neighbors=k, 
+        num_neighbors=as.integer(k), 
+        force_variable_neighbors=is(k, "AsIs"),
         chosen=subset, 
         num_threads=num.threads, 
         last_distance_only=FALSE,

R/findNeighbors.R

@@ -1,6 +1,6 @@
-#' Find all neighbors in range
+#' Find neighbors within a threshold distance
 #'
-#' Find all neighboring data points within a certain distance of each point.
+#' Find all neighbors within a threshold distance of each point of a dataset.
 #'
 #' @inheritParams findKNN
 #' @param threshold A positive numeric scalar specifying the maximum distance at which a point is considered a neighbor.

R/queryDistance.R

@@ -1,6 +1,6 @@
-#' Query for the distance to the k-th nearest neighbor
+#' Distance to the k-th nearest neighbor to query points
 #'
-#' Query a dataset to determine the distance to the k-th nearest neighbor of each point in another dataset, using a variety of algorithms.
+#' Query a reference dataset to determine the distance to the k-th nearest neighbor of each point in a query dataset.
 #' 
 #' @inheritParams queryKNN
 #' 
@@ -11,7 +11,7 @@
 #' @return
 #' Numeric vector of length equal to the number of points in \code{query} (or \code{subset}, if provided),
 #' containing the distance from each point to its \code{k}-th nearest neighbor.
-#' This is equivalent to but faster than taking the last distance of the output of \code{\link{queryKNN}}.
+#' This is equivalent to but more memory efficient than using \code{\link{queryKNN}} and subsetting to the last distance.
 #'
 #' @author
 #' Aaron Lun
@@ -37,7 +37,7 @@ NULL
 #' @export
 setMethod("queryDistance", c("matrix", "ANY"), function(X, query, k, num.threads=1, subset=NULL, transposed=FALSE, ..., BNPARAM=NULL) {
     ptr <- buildIndex(X, transposed=transposed, ..., BNPARAM=BNPARAM)
-    callGeneric(ptr, query=query, k=k, get.index=get.index, get.distance=get.distance, num.threads=num.threads, subset=subset, transposed=transposed, ...)
+    callGeneric(ptr, query=query, k=k, num.threads=num.threads, subset=subset, transposed=transposed, ...)
 })
 
 #' @export
@@ -50,7 +50,8 @@ setMethod("queryDistance", c("externalptr", "ANY"), function(X, query, k, num.th
     generic_query_knn(
         X,
         query=query,
-        num_neighbors=k,
+        num_neighbors=as.integer(k), 
+        force_variable_neighbors=is(k, "AsIs"),
         num_threads=num.threads,
         last_distance_only=TRUE,
         report_index=FALSE,

R/queryKNN.R

@@ -1,12 +1,16 @@
-#' Query for the k-nearest neighbors
+#' Query k-nearest neighbors
 #'
-#' Query a dataset for the k-nearest neighbors of points in another dataset, using a variety of algorithms.
+#' Query a reference dataset for the k-nearest neighbors of each point in a query dataset.
 #' 
+#' @param X The reference dataset to be queried.
+#' This should be a numeric matrix where rows correspond to reference points and columns correspond to variables (i.e., dimensions).
+#' Alternatively, a prebuilt index from \code{\link{buildIndex}}.
 #' @inheritParams findKNN
 #' @param k A positive integer scalar specifying the number of nearest neighbors to retrieve.
 #'
 #' Alternatively, an integer vector of length equal to the number of points in \code{query}, specifying the number of neighbors to identify for each point.
 #' If \code{subset} is provided, this should have length equal to the length of \code{subset}.
+#' Users should wrap this vector in an \link{AsIs} class to distinguish length-1 vectors from integer scalars.
 #'
 #' All \code{k} should be less than or equal to the number of points in \code{X}, otherwise the former will be capped at the latter with a warning.
 #' @param query A numeric matrix of query points, containing the same number of columns as \code{X}.
@@ -53,6 +57,8 @@
 #' 
 #' @seealso
 #' \code{\link{buildIndex}}, to build an index ahead of time.
+#'
+#' \code{\link{queryDistance}}, to obtain the distance from each query point to its k-th nearest neighbor.
 #' 
 #' @aliases
 #' queryKNN,matrix,ANY-method
@@ -92,7 +98,8 @@ setMethod("queryKNN", c("externalptr", "ANY"), function(X, query, k, get.index=T
     output <- generic_query_knn(
         X,
         query=query,
-        num_neighbors=k,
+        num_neighbors=as.integer(k),
+        force_variable_neighbors=is(k, "AsIs"),
         num_threads=num.threads,
         last_distance_only=FALSE,
         report_index=!isFALSE(get.index),

R/queryNeighbors.R

@@ -1,14 +1,12 @@
-#' Query neighbors in range
+#' Query neighbors within a threshold distance
 #' 
-#' Find all neighboring data points within a certain distance of a query point.
+#' Find all points in a reference dataset that lie within a threshold distance of each point in a query dataset.
 #' 
-#' @inheritParams findKNN 
-#' @param query A numeric matrix of query points, containing the same number of columns as \code{X}.
+#' @inheritParams queryKNN
 #' @param threshold A positive numeric scalar specifying the maximum distance at which a point is considered a neighbor.
 #' Alternatively, a vector containing a different distance threshold for each query point.
-#' @param transposed A logical scalar indicating whether \code{X} and \code{query} are transposed, 
-#' in which case both matrices are assumed to contain dimensions in the rows and data points in the columns.
-#' @param subset An integer, logical or character vector indicating the rows of \code{query} (or columns, if \code{transposed=TRUE}) for which the neighbors should be identified.
+#' @param get.index A logical scalar indicating whether the indices of the neighbors should be recorded.
+#' @param get.distance A logical scalar indicating whether distances to the neighbors should be recorded.
 #' 
 #' @details
 #' This function identifies all points in \code{X} that within \code{threshold} of each point in \code{query}.

inst/NEWS.Rd

@@ -16,6 +16,9 @@ The removal of this guarantee makes it easier to extend \pkg{BiocNeighbors} to n
 
 \item All functions (\code{findKNN()}, \code{queryNeighbors()}, etc.) will no longer coerce `X` to a matrix, to avoid the headache of S4 dispatch ambiguity.
 Users should coerce their data into matrix format before supplying it to these functions.
+
+\item The \code{last=} option in \code{findKNN()} and \code{queryKNN()} has been replaced by the \code{findDistance()} and \code{queryDistance()} functions instead.
+This provides a much more intuitive method for the typical use of \code{last=}, i.e., to obtain the distance to the k-th nearest neighbor.
 }}
 
 \section{Version 1.10.0}{\itemize{