Add .vary parameter to expand_grid(), Fixes #1543

Author: JamesHWade

NEWS.md

@@ -5,6 +5,8 @@
 
 * tidyr now requires dplyr >=1.1.0 (#1568, @catalamarti).
 
+* `expand_grid()` gains a new `.vary` argument, allowing users to control whether combinations vary fastest or slowest (default). (#1543, @JamesHWade).
+
 # tidyr 1.3.1
 
 * `pivot_wider` now uses `.by` and `|>` syntax for the dplyr helper message to 

R/expand.R

@@ -162,30 +162,46 @@ nesting <- function(..., .name_repair = "check_unique") {
 #' `expand_grid()` is heavily motivated by [expand.grid()].
 #' Compared to `expand.grid()`, it:
 #'
-#' * Produces sorted output (by varying the first column the slowest, rather
-#'   than the fastest).
+#' * Produces sorted output (by varying the first column the slowest by default).
 #' * Returns a tibble, not a data frame.
 #' * Never converts strings to factors.
 #' * Does not add any additional attributes.
 #' * Can expand any generalised vector, including data frames.
+#' * Allows for fastest or slowest varying combinations.
 #'
 #' @param ... Name-value pairs. The name will become the column name in the
 #'   output.
 #' @inheritParams tibble::as_tibble
+#' @param .vary Character string specifying the order of combination variation.
+#'   Must be either "slowest" (default) or "fastest".
+#'   * "slowest": Varies the first column the slowest (default, compatible with
+#'      base R's expand.grid()).
+#'   * "fastest": Varies the first column the fastest (compatible with
+#'     purrr::cross() family).
+#'
 #' @return A tibble with one column for each input in `...`. The output
 #'   will have one row for each combination of the inputs, i.e. the size
-#'   be equal to the product of the sizes of the inputs. This implies
+#'   will be equal to the product of the sizes of the inputs. This implies
 #'   that if any input has length 0, the output will have zero rows.
+#'   The order of combinations depends on the `.vary` parameter.
+#'
 #' @export
 #' @examples
+#' # Default behavior (slowest varying)
 #' expand_grid(x = 1:3, y = 1:2)
-#' expand_grid(l1 = letters, l2 = LETTERS)
+#'
+#' # Fastest varying (like purrr::cross())
+#' expand_grid(x = 1:3, y = 1:2, .vary = "fastest")
+#'
+#' expand_grid(l1 = letters[1:3], l2 = LETTERS[1:2])
 #'
 #' # Can also expand data frames
 #' expand_grid(df = tibble(x = 1:2, y = c(2, 1)), z = 1:3)
+#'
 #' # And matrices
 #' expand_grid(x1 = matrix(1:4, nrow = 2), x2 = matrix(5:8, nrow = 2))
-expand_grid <- function(..., .name_repair = "check_unique") {
+expand_grid <- function(..., .name_repair = "check_unique", .vary = c("slowest", "fastest")) {
+  .vary <- rlang::arg_match(.vary)
   out <- grid_dots(...)
 
   names <- names2(out)
@@ -202,6 +218,7 @@ expand_grid <- function(..., .name_repair = "check_unique") {
 
   out <- vec_expand_grid(
     !!!out,
+    .vary = .vary,
     .name_repair = "minimal",
     .error_call = current_env()
   )

man/expand_grid.Rd

@@ -64,3 +64,11 @@
       Error:
       ! `..1` must be a vector, not a <lm> object.
 
+# expand_grid() throws an error for invalid .vary parameter
+
+    Code
+      expand_grid(x = 1:2, y = 1:2, .vary = "invalid")
+    Condition
+      Error in `expand_grid()`:
+      ! `.vary` must be one of "slowest" or "fastest", not "invalid".
+

tests/testthat/_snaps/expand.md

@@ -451,3 +451,103 @@ test_that("fct_unique() doesn't alter level order if `NA` is an existing level",
   expect_identical(fct_unique(x), x)
   expect_identical(levels(fct_unique(x)), c(NA, "x"))
 })
+
+
+# ------------------------------------------------------------------------------
+# .vary parameter
+
+test_that("expand_grid() respects .vary parameter", {
+  # Test default behavior (slowest varying)
+  out_default <- expand_grid(x = 1:3, y = 1:2)
+  expect_equal(
+    out_default,
+    tibble(
+      x = c(1, 1, 2, 2, 3, 3),
+      y = c(1, 2, 1, 2, 1, 2)
+    )
+  )
+
+  # Test fastest varying
+  out_fastest <- expand_grid(x = 1:3, y = 1:2, .vary = "fastest")
+  expect_equal(
+    out_fastest,
+    tibble(
+      x = c(1, 2, 3, 1, 2, 3),
+      y = c(1, 1, 1, 2, 2, 2)
+    )
+  )
+})
+
+test_that("expand_grid() .vary parameter works with more than two variables", {
+  out_slowest <- expand_grid(x = 1:2, y = 1:2, z = 1:2)
+  expect_equal(
+    out_slowest,
+    tibble(
+      x = c(1, 1, 1, 1, 2, 2, 2, 2),
+      y = c(1, 1, 2, 2, 1, 1, 2, 2),
+      z = c(1, 2, 1, 2, 1, 2, 1, 2)
+    )
+  )
+
+  out_fastest <- expand_grid(x = 1:2, y = 1:2, z = 1:2, .vary = "fastest")
+  expect_equal(
+    out_fastest,
+    tibble(
+      x = c(1, 2, 1, 2, 1, 2, 1, 2),
+      y = c(1, 1, 2, 2, 1, 1, 2, 2),
+      z = c(1, 1, 1, 1, 2, 2, 2, 2)
+    )
+  )
+})
+
+test_that("expand_grid() .vary parameter works with different input types", {
+  out_slowest <- expand_grid(x = 1:2, y = c("a", "b"), z = factor(c("low", "high")))
+  expect_equal(
+    out_slowest,
+    tibble(
+      x = c(1, 1, 1, 1, 2, 2, 2, 2),
+      y = c("a", "a", "b", "b", "a", "a", "b", "b"),
+      z = factor(c("low", "high", "low", "high", "low", "high", "low", "high"))
+    )
+  )
+
+  out_fastest <- expand_grid(x = 1:2, y = c("a", "b"), z = factor(c("low", "high")), .vary = "fastest")
+  expect_equal(
+    out_fastest,
+    tibble(
+      x = c(1, 2, 1, 2, 1, 2, 1, 2),
+      y = c("a", "a", "b", "b", "a", "a", "b", "b"),
+      z = factor(c("low", "low", "low", "low", "high", "high", "high", "high"))
+    )
+  )
+})
+
+test_that("expand_grid() .vary parameter works with data frames", {
+  df <- tibble(a = 1:2, b = c("x", "y"))
+  out_slowest <- expand_grid(df, z = 1:2)
+  expect_equal(
+    out_slowest,
+    tibble(
+      a = c(1, 1, 2, 2),
+      b = c("x", "x", "y", "y"),
+      z = c(1, 2, 1, 2)
+    )
+  )
+
+  out_fastest <- expand_grid(df, z = 1:2, .vary = "fastest")
+  expect_equal(
+    out_fastest,
+    tibble(
+      a = c(1, 2, 1, 2),
+      b = c("x", "y", "x", "y"),
+      z = c(1, 1, 2, 2)
+    )
+  )
+})
+
+test_that("expand_grid() throws an error for invalid .vary parameter", {
+  expect_snapshot(
+    expand_grid(x = 1:2, y = 1:2, .vary = "invalid"),
+    error = TRUE
+  )
+})