Add fct_reordern() (Fix #16)

NAMESPACE

@@ -30,6 +30,7 @@ export(fct_relabel)
 export(fct_relevel)
 export(fct_reorder)
 export(fct_reorder2)
+export(fct_reordern)
 export(fct_rev)
 export(fct_shift)
 export(fct_shuffle)

NEWS.md

@@ -1,4 +1,6 @@
 # forcats (development version)
+* `fct_reordern()` is a new function to order based on an arbitrary number of
+  values (@billdenney, #16)
 
 # forcats 0.5.2
 

R/reorder.R

@@ -17,6 +17,8 @@
 #' @param .desc Order in descending order? Note the default is different
 #'   between `fct_reorder` and `fct_reorder2`, in order to
 #'   match the default ordering of factors in the legend.
+#' @importFrom stats median
+#' @family Reordering
 #' @export
 #' @examples
 #' df <- tibble::tribble(
@@ -73,6 +75,26 @@ fct_reorder2 <- function(.f, .x, .y, .fun = last2, ..., .desc = TRUE) {
   lvls_reorder(.f, order(summary, decreasing = .desc))
 }
 
+#' Reorder factor levels by sorting along multiple variables
+#' 
+#' @param .f A factor (or character vector).
+#' @param ordered Passed to \code{\link{fct_inorder}()}
+#' @inheritDotParams base::order
+#' @family Reordering
+#' @examples
+#' A <- c(3, 3, 2, 1)
+#' B <- c("A", "B", "C", "D")
+#' fct_reordern(c("A", "B", "C", "D"), A, B)
+#' fct_reordern(c("A", "B", "C", "D"), dplyr::desc(A), dplyr::desc(B))
+#' fct_reordern(c("A", "B", "C", "D"), A, dplyr::desc(B))
+#' @export
+fct_reordern <- function(.f, ..., ordered = NA) {
+  f <- check_factor(.f)
+  new_order <- base::order(...)
+  idx <- as.integer(f)[new_order]
+  lvls_reorder(f, idx = idx[!duplicated(idx)], ordered = ordered)
+}
+
 check_single_value_per_group <- function(x, fun_arg, call = caller_env()) {
   # This is a bit of a weak test, but should detect the most common case
   # where `.fun` returns multiple values.

_pkgdown.yml

@@ -25,6 +25,7 @@ reference:
     - fct_relevel
     - fct_inorder
     - fct_reorder
+    - fct_reordern
     - fct_infreq
     - fct_shuffle
     - fct_rev

tests/testthat/test-reorder.R

@@ -93,3 +93,29 @@ test_that("fct_inseq gives error for non-numeric levels", {
   f <- factor(c("c", "a", "a", "b"))
   expect_error(levels(fct_inseq(f)), "level must be coercible to numeric")
 })
+
+test_that("fct_reordern works for all scenarios (fix #16)", {
+  A <- c(3, 3, 2, 1)
+  B <- c("A", "B", "C", "D")
+  f <- c("A", "B", "C", "D")
+  f_factor_ordered <- factor(f, ordered = TRUE)
+  expect_equal(
+    fct_reordern(f, A, B),
+    factor(f, levels = c("D", "C", "A", "B"))
+  )
+  # Ensure interaction with dplyr::desc() is accurate.
+  desc <- function(x) -xtfrm(x)
+  expect_equal(
+    fct_reordern(f, A, desc(B)),
+    factor(f, levels = c("D", "C", "B", "A"))
+  )
+  # Checks of ordering
+  expect_equal(
+    fct_reordern(f, A, B, ordered = NA),
+    factor(f, levels = c("D", "C", "A", "B"))
+  )
+  expect_equal(
+    fct_reordern(f, A, B, ordered = TRUE),
+    factor(f, levels = c("D", "C", "A", "B"), ordered = TRUE)
+  )
+})