Delete unneeded function; add help file for orderstats

Author: baddstats

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: spatstat.utils
-Version: 1.18-0
-Date: 2020-11-14
+Version: 1.19-0
+Date: 2020-12-19
 Title: Utility Functions for 'spatstat'
 Authors@R: c(person("Adrian", "Baddeley", 
                     role = c("aut", "cre"),

NAMESPACE

@@ -153,7 +153,6 @@ export("revcumsum")
 export("reverse.xypolygon")    
 export("rhs.of.formula")
 export("rhs.of.formula<-")
-export("romansort")
 export("samefunction")
 export("sensiblevarname")
 export("short.deparse")

R/utiltext.R

@@ -3,7 +3,7 @@
 #'
 #'   Utilities for text output, etc
 #'
-#'   $Revision: 1.7 $ $Date: 2020/02/06 07:35:31 $
+#'   $Revision: 1.8 $ $Date: 2020/12/19 08:45:05 $
 #'
 
 # text magic
@@ -469,30 +469,6 @@ fontify <- function(x, font="italic") {
   return(NULL)
 }
 
-romansort <- local({
-
-  # sort character strings in order of Roman alphabet
-  
-  romansort <- function(x) {
-    if(!is.character(x)) return(sort(x))
-    x <- as.vector(x)
-    ## convert each 'word' to a vector of single characters
-    cc <- strsplit(x, "")
-    ## find position of each character in Roman alphabet
-    mm <- lapply(cc, match, table=c(letters, LETTERS))
-    mmax <- max(unlist(mm), na.rm=TRUE)
-    ## encode
-    nn <- sapply(mm, powercode, base=mmax)
-    ## find ordering
-    oo <- order(nn, na.last=TRUE)
-    return(x[oo])
-  }
-
-  powercode <- function(x, base) sum(x * base^rev((seq_len(length(x))-1)))
-
-  romansort
-})
-
 variablesintext <- function(x) all.vars(as.expression(parse(text=x)))
 
 ## convert numeric matrix to character, and blank out lower sub-diagonal.

inst/doc/packagesizes.txt

@@ -13,3 +13,4 @@ date version nhelpfiles nobjects ndatasets Rlines srclines
 "2018-10-19" "1.12-0" 30 169 0 3303 1944
 "2018-10-31" "1.13-0" 30 169 0 3304 1944
 "2020-11-14" "1.18-0" 31 171 0 3354 1965
+"2020-12-19" "1.19-0" 32 170 0 3330 1965

man/orderstats.Rd

@@ -0,0 +1,84 @@
+\name{orderstats}
+\alias{orderstats}
+\alias{orderwhich}
+\title{
+  Compute Order Statistics
+}
+\description{
+  Compute the \code{k}-th smallest value in a dataset,
+  or find which entry in a dataset is the \code{k}-th smallest.
+}
+\usage{
+orderstats(x, k, decreasing = FALSE)
+orderwhich(x, k, decreasing = FALSE)
+}
+\arguments{
+  \item{x}{
+    Data whose order statistics will be computed. A numeric vector.
+  }
+  \item{k}{
+    Rank. An integer, or vector of integers.
+  }
+  \item{decreasing}{
+    Logical value specifing whether a rank of 1
+    is assigned to the highest value (\code{decreasing=TRUE})
+    or the lowest value (\code{decreasing=FALSE}, the default).
+  }
+}
+\details{
+  These are low-level functions for efficiently computing order statistics:
+  \code{orderstats(x, k)} returns the \code{k}-th smallest value in \code{x},
+  and \code{orderwhich(x, k)} returns the \emph{position} of the
+  \code{k}-th smallest value in \code{x}.
+
+  Given a dataset of values \eqn{x_1, \dots, x_n}{x[1], ..., x[n]},
+  the \emph{order statistic} of rank \eqn{k} is the \eqn{k}-th smallest
+  value in the dataset. The order statistic of rank 1 is the smallest
+  value, and the order statistic of rank \eqn{n} is the largest value.
+  The order statistic of rank \eqn{k} is denoted \eqn{x_{[k]}}{x([k])}.
+
+  The full sequence of order statistics
+  \deqn{
+    x_{[1]} \le x_{[2]} \le \dots \le x_{[n]}
+  }{
+    x([1]) <= x([2]) <= ... <= x([n])
+  }
+  can simply be obtained by sorting the original values
+  into increasing order.
+
+  The command \code{orderstats(x, k)} is equivalent to
+  \code{\link{sort}(x)[k]}; it calculates the
+  \code{k}-th smallest value in \code{x}. 
+
+  The command \code{orderwhich(x, k)} is equivalent to
+  \code{\link{order}(x)[k]}. It identifies the \emph{position} of the
+  \code{k}-th smallest value in \code{x}, that is, it returns the
+  index \code{j} such that \code{x[j]} is the \code{k}-th smallest value
+  in \code{x}.
+  
+  The functions \code{orderstats} and \code{orderwhich} are more
+  efficient than using \code{sort} and \code{order}
+  when it is only desired to calculate a few of the
+  order statistics (for example, only the smallest and second-smallest
+  values in the dataset).
+}
+\value{
+  \code{orderstats} returns a vector of the same kind as \code{x},
+  with the same length as \code{k}.
+  \code{orderwhich} returns an integer vector 
+  with the same length as \code{k}.
+}
+\author{
+  \adrian.
+}
+\seealso{
+  \code{\link{sort}}, \code{\link{order}}.
+}
+\examples{
+  x <- runif(10)
+  orderstats(x, 2)
+  sort(x)[2]
+  orderwhich(x, 2:3)
+  order(x)[2:3]
+}
+\keyword{math}

man/spatstat.utils-internal.Rd

@@ -65,8 +65,6 @@
 \alias{NNdist2segments}
 \alias{numalign}
 \alias{nzpaste}
-\alias{orderstats}
-\alias{orderwhich}
 \alias{\%orifnull\%}  %DoNotExport
 %NAMESPACE export("%orifnull%")
 \alias{padtowidth}
@@ -172,8 +170,6 @@ niceround(x, m)
 NNdist2segments(xp, yp, x0, y0, x1, y1, bigvalue)
 numalign(i, nmax, zero)
 nzpaste(\dots, sep, collapse)
-orderstats(x, k, decreasing)
-orderwhich(x, k, decreasing)
 a \%orifnull\% b
 padtowidth(a, b, justify)
 passthrough(.Fun, \dots, .Fname)

tests/tekst.R

@@ -56,5 +56,4 @@ simplenumber(1/3, unit="km")
 simplenumber(2/3, unit="km")
 simplenumber(-2, unit="km")
 
-romansort(c("Eb", "Au"))
 makeCutLabels(0:3)