From 050a867c795cc37cbdef43cd6566f1309b40e7a0 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Tue, 3 Jan 2023 14:44:26 -0600
Subject: [PATCH] Improve fct_reorder() examples

Fixes #255
---
 R/reorder.R        | 42 +++++++++++++++++++-----------------------
 man/fct_reorder.Rd | 42 +++++++++++++++++++-----------------------
 2 files changed, 38 insertions(+), 46 deletions(-)

diff --git a/R/reorder.R b/R/reorder.R
index 0ebc2a95..12320c31 100644
--- a/R/reorder.R
+++ b/R/reorder.R
@@ -19,36 +19,32 @@
 #'   match the default ordering of factors in the legend.
 #' @export
 #' @examples
-#' df <- tibble::tribble(
-#'   ~color,     ~a, ~b,
-#'   "blue",      1,  2,
-#'   "green",     6,  2,
-#'   "purple",    3,  3,
-#'   "red",       2,  3,
-#'   "yellow",    5,  1
-#' )
-#' df$color <- factor(df$color)
-#' fct_reorder(df$color, df$a, min)
-#' fct_reorder2(df$color, df$a, df$b)
-#'
+#' # fct_reorder() -------------------------------------------------------------
+#' # Useful when a categorical variable is mapped to position
 #' boxplot(Sepal.Width ~ Species, data = iris)
 #' boxplot(Sepal.Width ~ fct_reorder(Species, Sepal.Width), data = iris)
-#' boxplot(Sepal.Width ~ fct_reorder(Species, Sepal.Width, .desc = TRUE), data = iris)
+#'
+#' # or with
+#' library(ggplot2)
+#' ggplot(iris, aes(fct_reorder(Species, Sepal.Width), Sepal.Width)) +
+#'   geom_boxplot()
+#'
+#' # fct_reorder2() -------------------------------------------------------------
+#' # Useful when a categorical variable is mapped to color, size, shape etc
 #'
 #' chks <- subset(ChickWeight, as.integer(Chick) < 10)
 #' chks <- transform(chks, Chick = fct_shuffle(Chick))
 #'
-#' if (require("ggplot2")) {
-#'   ggplot(chks, aes(Time, weight, colour = Chick)) +
-#'     geom_point() +
-#'     geom_line()
+#' # Without reordering it's hard to match line to legend
+#' ggplot(chks, aes(Time, weight, colour = Chick)) +
+#'   geom_point() +
+#'   geom_line()
 #'
-#'   # Note that lines match order in legend
-#'   ggplot(chks, aes(Time, weight, colour = fct_reorder2(Chick, Time, weight))) +
-#'     geom_point() +
-#'     geom_line() +
-#'     labs(colour = "Chick")
-#' }
+#' # With reordering it's much easier
+#' ggplot(chks, aes(Time, weight, colour = fct_reorder2(Chick, Time, weight))) +
+#'   geom_point() +
+#'   geom_line() +
+#'   labs(colour = "Chick")
 fct_reorder <- function(.f, .x, .fun = median, ..., .desc = FALSE) {
   f <- check_factor(.f)
   stopifnot(length(f) == length(.x))
diff --git a/man/fct_reorder.Rd b/man/fct_reorder.Rd
index 4afef0c3..1afff250 100644
--- a/man/fct_reorder.Rd
+++ b/man/fct_reorder.Rd
@@ -40,34 +40,30 @@ a non-position aesthetic. \code{last2()} and \code{first2()} are helpers for \co
 \code{last2()} finds the last value of \code{y} when sorted by \code{x}; \code{first2()} finds the first value.
 }
 \examples{
-df <- tibble::tribble(
-  ~color,     ~a, ~b,
-  "blue",      1,  2,
-  "green",     6,  2,
-  "purple",    3,  3,
-  "red",       2,  3,
-  "yellow",    5,  1
-)
-df$color <- factor(df$color)
-fct_reorder(df$color, df$a, min)
-fct_reorder2(df$color, df$a, df$b)
-
+# fct_reorder() -------------------------------------------------------------
+# Useful when a categorical variable is mapped to position
 boxplot(Sepal.Width ~ Species, data = iris)
 boxplot(Sepal.Width ~ fct_reorder(Species, Sepal.Width), data = iris)
-boxplot(Sepal.Width ~ fct_reorder(Species, Sepal.Width, .desc = TRUE), data = iris)
+
+# or with
+library(ggplot2)
+ggplot(iris, aes(fct_reorder(Species, Sepal.Width), Sepal.Width)) +
+  geom_boxplot()
+
+# fct_reorder2() -------------------------------------------------------------
+# Useful when a categorical variable is mapped to color, size, shape etc
 
 chks <- subset(ChickWeight, as.integer(Chick) < 10)
 chks <- transform(chks, Chick = fct_shuffle(Chick))
 
-if (require("ggplot2")) {
-  ggplot(chks, aes(Time, weight, colour = Chick)) +
-    geom_point() +
-    geom_line()
+# Without reordering it's hard to match line to legend
+ggplot(chks, aes(Time, weight, colour = Chick)) +
+  geom_point() +
+  geom_line()
 
-  # Note that lines match order in legend
-  ggplot(chks, aes(Time, weight, colour = fct_reorder2(Chick, Time, weight))) +
-    geom_point() +
-    geom_line() +
-    labs(colour = "Chick")
-}
+# With reordering it's much easier
+ggplot(chks, aes(Time, weight, colour = fct_reorder2(Chick, Time, weight))) +
+  geom_point() +
+  geom_line() +
+  labs(colour = "Chick")
 }