Support reverse ranking in frank() (#7874)

* updated changes

* ..

* .

* ..

* ..

* corected typo

* finalize PR

---------

Co-authored-by: Benjamin Schwendinger <benjaminschwe@gmail.com>

Author: venom1204

NEWS.md

@@ -44,6 +44,8 @@
 
 11. `setorderv()` now accepts a named vector for the `order` argument. When provided, the names are used to identify the columns, allowing the `cols` argument to be omitted, [#6932](https://github.com/Rdatatable/data.table/issues/6932). Thanks to @MichaelChirico for the suggestion and @venom1204 for the implementation.
 
+12. `frank()` gains an `order` argument (matching `frankv()`) and now intercepts the unary minus symbol (e.g., `frank(-dates)`) to support reverse ranking even for types where unary `-` is not defined in R, such as `Date` or `character` vectors, [#5489](https://github.com/Rdatatable/data.table/issues/5489). Thanks @hope-data-science for the request and @venom1204 for the implementation.
+
 ### BUG FIXES
 
 1. `fread()` with `skip=0` and `(header=TRUE|FALSE)` no longer skips the first row when it has fewer fields than subsequent rows, [#7463](https://github.com/Rdatatable/data.table/issues/7463). Thanks @emayerhofer for the report and @ben-schwen for the fix.

R/frank.R

@@ -73,27 +73,41 @@ frankv = function(x, cols=seq_along(x), order=1L, na.last=TRUE, ties.method=c("a
   ans
 }
 
-frank = function(x, ..., na.last=TRUE, ties.method=c("average", "first", "last", "random", "max", "min", "dense")) {
+frank = function(x, ..., order=1L, na.last=TRUE, ties.method=c("average", "first", "last", "random", "max", "min", "dense")) {
+  order_missing = missing(order)
+  has_prefix = FALSE
+  q_x = substitute(x)
+  if (is.call(q_x) && length(q_x) == 2L && (q_x[[1L]] == quote(`-`) || q_x[[1L]] == quote(`+`))) {
+    has_prefix = TRUE
+    if (order_missing) order = if (q_x[[1L]] == quote(`-`)) -1L else 1L
+    x = eval(q_x[[2L]], parent.frame())
+  }
+
   cols = substitute(list(...))[-1L]
   if (identical(as.character(cols), "NULL")) {
     cols  = NULL
-    order = 1L
   } else if (length(cols)) {
     cols=as.list(cols)
-    order=rep(1L, length(cols))
+    if (length(order) == 1L) order = rep(as.integer(order), length(cols))
+
     for (i in seq_along(cols)) {
       v=as.list(cols[[i]])
-      if (length(v) > 1L && v[[1L]] == "+") v=v[[-1L]]
-      else if (length(v) > 1L && v[[1L]] == "-") {
+      if (length(v) > 1L && (v[[1L]] == "+" || v[[1L]] == "-")) {
+        has_prefix = TRUE
+        if (order_missing && v[[1L]] == "-") order[i] = -1L
         v=v[[-1L]]
-        order[i] = -1L
       }
       cols[[i]]=as.character(v)
     }
     cols=unlist(cols, use.names=FALSE)
   } else {
     cols=colnames(x)
-    order=if (is.null(cols)) 1L else rep(1L, length(cols))
+    if (!is.null(cols) && length(order) == 1L) {
+      order = rep(as.integer(order), length(cols))
+    }
+  }
+  if (has_prefix && !order_missing) {
+    warningf("Both prefix sign and 'order' argument are provided; 'order' will take precedence.")
   }
   frankv(x, cols=cols, order=order, na.last=na.last, ties.method=ties.method)
 

inst/tests/tests.Rraw

@@ -21952,3 +21952,25 @@ test(2385.04, setorderv(DT, order=c(x=1L, x=-1L)), error="order argument has nam
 test(2385.05, setorderv(DT, order=c(x=2L)), error="Must be +1 or -1")
 DT = data.table(a=c(2,1,2), b=3:1)
 test(2385.06, setorderv(copy(DT), order=c(a=1L)), setorderv(copy(DT), cols="a", order=1L))
+
+# #5489 frank could support reverse ranking
+dates = as.Date(c("1992-02-27", "1992-02-27", "1992-01-14", "1992-02-28", "1992-02-01"))
+test(2386.01, frank(-dates, ties.method="min"), frankv(dates, order=-1L, ties.method="min"))
+ct = as.POSIXct(c("2020-01-03 10:00:00", "2020-01-03 10:00:00", "2020-01-01 08:00:00", "2020-01-05 12:00:00", "2020-01-02 09:00:00"))
+test(2386.02, frank(-ct, ties.method="min"), frankv(ct, order=-1L, ties.method="min"))
+idates = as.IDate(c("2020-01-03", "2020-01-03", "2020-01-01", "2020-01-05", "2020-01-02"))
+test(2386.03, frank(-idates), frankv(idates, order=-1L))
+it = as.ITime(c("10:00:00", "10:00:00", "08:00:00", "12:00:00", "09:00:00"))
+test(2386.04, frank(-it), frankv(it, order=-1L))
+DT = data.table(x=c(2,1,2,1,3), y=c(5,4,3,2,1))
+test(2386.05, frank(DT, -x, y), frankv(DT, cols=c("x", "y"), order=c(-1L, 1L)))
+DT_global = data.table(a=c(1,2,1), b=c(1,1,2))
+test(2386.06, frank(DT_global, order=-1L), frankv(DT_global, order=-1L))
+warn = "Both prefix sign and 'order' argument are provided; 'order' will take precedence."
+test(2386.07, frank(-dates, order=1L), frankv(dates, order=1L), warning=warn)
+test(2386.08, frank(DT, -x, y, order=c(1L, -1L)), frankv(DT, cols=c("x", "y"), order=c(1L, -1L)), warning=warn)
+test(2386.09, frank(DT, -x, y, order=-1L), frankv(DT, cols=c("x", "y"), order=-1L), warning=warn)
+test(2386.10, frank(-dates, order=-1L), frankv(dates, order=-1L), warning=warn)
+test(2386.11, frank(+dates), frankv(dates, order=1L))
+chars = c("b", "a", "c", "a")
+test(2386.12, frank(-chars), frankv(chars, order=-1L))

man/frank.Rd

@@ -12,7 +12,7 @@
 }
 
 \usage{
-frank(x, \dots, na.last=TRUE, ties.method=c("average",
+frank(x, \dots, order=1L, na.last=TRUE, ties.method=c("average",
   "first", "last", "random", "max", "min", "dense"))
 
 frankv(x, cols=seq_along(x), order=1L, na.last=TRUE,
@@ -21,17 +21,19 @@ frankv(x, cols=seq_along(x), order=1L, na.last=TRUE,
 
 }
 \arguments{
-  \item{x}{ A vector, or list with all its elements identical in length or \code{data.frame} or \code{data.table}. }
-  \item{\dots}{ Only for \code{list}s, \code{data.frame}s and \code{data.table}s. The columns to calculate ranks based on. Do not quote column names. If \code{\dots} is missing, all columns are considered by default. To sort by a column in descending order prefix \code{"-"}, e.g., \code{frank(x, a, -b, c)}. \code{-b} works when \code{b} is of type \code{character} as well.}
+  \item{x}{ A vector, or list with all its elements identical in length or \code{data.frame} or \code{data.table}. For vector input, unary \code{+} and \code{-} request ascending and descending order, respectively, including for types such as \code{character} and \code{Date} where unary \code{-} is not defined. }
+  \item{\dots}{ Only for \code{list}s, \code{data.frame}s and \code{data.table}s. The columns to calculate ranks based on. Do not quote column names. If \code{\dots} is missing, all columns are considered by default. Prefix a column with \code{"+"} or \code{"-"} for ascending or descending order, e.g., \code{frank(x, a, -b, c)}. Prefixes work when \code{b} is of type \code{character} or \code{Date} as well.}
   \item{cols}{ A \code{character} vector of column names (or numbers) of \code{x}, for which to obtain ranks. }
-  \item{order}{ An \code{integer} vector with only possible values of 1 and -1, corresponding to ascending and descending order. The length of \code{order} must be either 1 or equal to that of \code{cols}. If \code{length(order) == 1}, it is recycled to \code{length(cols)}. }
+  \item{order}{ An \code{integer} vector with only possible values of 1 and -1, corresponding to ascending and descending order. The length of \code{order} must be either 1 or equal to that of \code{cols}. If \code{length(order) == 1}, it is recycled to \code{length(cols)}. In \code{frank}, an explicitly supplied \code{order} takes precedence over any unary or column prefix and produces a warning. }
   \item{na.last}{ Control treatment of \code{NA}s. If \code{TRUE}, missing values in the data are put last; if \code{FALSE}, they are put first; if \code{NA}, they are removed; if \code{"keep"} they are kept with rank \code{NA}. }
   \item{ties.method}{ A character string specifying how ties are treated, see \code{Details}. }
 }
 \details{
   To be consistent with other \code{data.table} operations, \code{NA}s are considered identical to other \code{NA}s (and \code{NaN}s to other \code{NaN}s), unlike \code{base::rank}. Therefore, for \code{na.last=TRUE} and \code{na.last=FALSE}, \code{NA}s (and \code{NaN}s) are given identical ranks, unlike \code{\link[base]{rank}}.
 
-  \code{frank} is not limited to vectors. It accepts \code{data.table}s (and \code{list}s and \code{data.frame}s) as well. It accepts unquoted column names (with names preceded with a \code{-} sign for descending order, even on character vectors), for e.g., \code{frank(DT, a, -b, c, ties.method="first")} where \code{a,b,c} are columns in \code{DT}. The equivalent in \code{frankv} is the \code{order} argument.
+  \code{frank} is not limited to vectors. It accepts \code{data.table}s (and \code{list}s and \code{data.frame}s) as well. It accepts unquoted column names prefixed with \code{+} or \code{-} for ascending or descending order, for e.g., \code{frank(DT, a, -b, c, ties.method="first")} where \code{a,b,c} are columns in \code{DT}.
+
+  For vectors, \code{frank(+x)} and \code{frank(-x)} request ascending and descending order without applying the unary operator to \code{x}. This supports types where unary \code{-} is not defined, such as \code{Date} and \code{character}. When \code{order} is omitted, these vector signs and column prefixes determine direction.
 
   In addition to the \code{ties.method} values possible using base's \code{\link[base]{rank}}, it also provides another additional argument \code{"dense"} which returns the ranks without any gaps in the ranking. See examples.
 }
@@ -66,6 +68,11 @@ frank(DT, ties.method="first", na.last="keep") # equivalent of above using frank
 frank(DT, x, -y, ties.method="first")
 # equivalent of above using frankv
 frankv(DT, order=c(1L, -1L), ties.method="first")
+
+dates = as.Date("2022-10-19") + c(1, 3, 2, 4)
+frank(dates)      # ascending
+frank(-dates)     # descending (intercepts '-' to avoid error)
+frank(dates, order=-1L) # also descending
 }
 \seealso{
   \code{\link{data.table}}, \code{\link{setkey}}, \code{\link{setorder}}