better corners docs

.github/workflows/tests.yml

@@ -30,7 +30,8 @@ jobs:
       - name: Install bcftools
         if: startsWith(matrix.os, 'ubuntu')
         run: |
-          sudo apt-get install bcftools build-essential libcurl4-gnutls-dev libxml2-dev libssl-dev
+          sudo apt-get update
+          sudo apt-get install bcftools build-essential libcurl4-gnutls-dev libxml2-dev libssl-dev libharfbuzz-dev libfribidi-dev
 
       - name: Install package
         run: |

lostruct/DESCRIPTION

@@ -9,7 +9,7 @@ LazyData: true
 Imports:
     RSpectra,
     data.table
-RoxygenNote: 5.0.1
+RoxygenNote: 7.2.3
 Suggests:
     knitr,
     testthat,

lostruct/R/corners.R

@@ -1,15 +1,35 @@
 #' Find Points in a 2D Cloud Closest to the "Corners"
 #'
-#' Finds the k "extreme points" that lie closest to the minimal enclosing circle,
-#' and returns a matrix with k columns containing the portion of points 
-#' that lie closest to those extreme points.
+#' Finds the 'k' "extreme points" (the "corners") that lie closest
+#' to the minimal circle enclosing the input collection of points
+#' in two dimensions, and returns for each of these corners
+#' which of the input points are closest to that corner.
+#' The return value is a matrix with 'k' columns,
+#' whose 'i'-th column contains the indices of those points
+#' that lie closest to the 'i'-th corner.
+#'
+#' If the output is 'out', then 'out[,i]' is a vector of
+#' length 'nrow(xy) * prop' for which 'xy[ out[,i], ]' is
+#' the coordinates of the closest points to the 'i'th corner.
+#' The rows of 'out' are in no particular order.
+#'
 #' If k is larger than the number of points on the minimal enclosing circle,
-#' adds the closest points to that circle that are not in previously added points' neighborhoods
-#' until k is reached.
+#' this adds the closest points to that circle that are not in previously
+#' added points' neighborhoods until k is reached.
+#' If k is less than 3, this will behave as if k=3.
 #'
 #' @param xy A two-column numeric matrix of coordinates.
 #' @param prop The proportion of points to return for each corner.
-#' @return A three column integer matrix giving the indices of the corresponding points.
+#' @param k The number of corners (should be at least 3).
+#' @return A k-column integer matrix whose i-th column gives the indices of the points closest to the i-th corner.
+#'
+#' @examples
+#' xy <- runif(200) |> matrix(ncol=2)
+#' out <- corners(xy, k=4, prop=0.05)
+#' \dontrun{
+#' plot(xy)
+#' for (i in 1:4) points(xy[out[,i],], col=i, pch=20, cex=2)
+#' }
 #' @export
 corners <- function (xy, prop, k=3) {
     xy <- as.matrix(xy)