Add a full documentation page specific to .by

Author: DavisVaughan

R/by.R

@@ -4,15 +4,28 @@
 #'
 #' @param .by `r lifecycle::badge("experimental")`
 #'
-#'   <[`tidy-select`][dplyr_tidy_select]> Optionally, select columns to group
-#'   by. This grouping will only be active for the duration of this verb.
-#'
-#'   Can't be used when the data is already a grouped or rowwise data frame.
+#'   <[`tidy-select`][dplyr_tidy_select]> Optionally, a selection of columns to
+#'   temporarily group by using an inline alternative to [group_by()]. For
+#'   details and examples, see [?dplyr_by][dplyr_by].
 #'
 #' @name args_by
 #' @keywords internal
 NULL
 
+#' Grouping with `.by`
+#'
+#' ```{r, echo = FALSE, results = "asis"}
+#' result <- rlang::with_options(
+#'   knitr::knit_child("man/rmd/by.Rmd"),
+#'   dplyr.summarise.inform = TRUE
+#' )
+#' cat(result, sep = "\n")
+#' ```
+#'
+#' @name dplyr_by
+#' @keywords internal
+NULL
+
 compute_by <- function(by,
                        data,
                        ...,

man/args_by.Rd

@@ -0,0 +1,118 @@
+---
+output: html_document
+editor_options: 
+  chunk_output_type: console
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+There are two ways to group in dplyr:
+
+-   Persistent grouping with [group_by()]
+
+-   Temporary grouping with `.by`
+
+This help page is dedicated to explaining where and why you might want to use the latter.
+The most important reason to use `.by` is that you *never* have to remember to use [ungroup()] after it.
+The grouping is always temporary, meaning that if an ungrouped data frame goes in, then an ungrouped data frame comes out, regardless of the number of grouping columns that are specified.
+
+The following dplyr verbs support `.by`:
+
+-   [mutate()]
+
+-   [summarise()]
+
+-   [filter()]
+
+-   [slice()] and its variants, such as [slice_head()]
+
+Let's take a look at the two grouping approaches using this `expenses` data set, which tracks costs accumulated across various `id`s and `region`s:
+
+```{r}
+expenses <- tibble(
+  id = c(1, 2, 1, 3, 1, 2, 3),
+  region = c("A", "A", "A", "B", "B", "A", "A"),
+  cost = c(25, 20, 19, 12, 9, 6, 6)
+)
+expenses
+```
+
+Imagine that you wanted to compute the average cost per region.
+You'd probably write something like this:
+
+```{r}
+expenses %>%
+  group_by(region) %>%
+  summarise(cost = mean(cost))
+```
+
+As of dplyr 1.1.0, an additional option is available that lets you specify the grouping *inline* within the verb:
+
+```{r}
+expenses %>%
+  summarise(cost = mean(cost), .by = region)
+```
+
+This great idea comes from [data.table](https://CRAN.R-project.org/package=data.table), where the equivalent syntax looks something like `expenses[, .(cost = mean(cost)), by = region]`.
+
+Grouping with `.by` is temporary, meaning that since `expenses` was an ungrouped data frame, the result after applying `.by` will also always be an ungrouped data frame, full stop.
+Compare that with `group_by() %>% summarise()`, where `summarise()` generally peels off 1 layer of grouping by default, with a message that it is doing so if there were originally more than one grouping columns:
+
+```{r}
+expenses %>%
+  group_by(id, region) %>%
+  summarise(cost = mean(cost))
+```
+
+This behavior is sometimes useful to sequentially "roll up" a data frame that has been grouped by multiple columns, but often you just want to group temporarily.
+Traditionally, you'd either `ungroup()` after the `summarise()` or explicitly set `.groups = "drop"` to achieve this:
+
+```{r}
+expenses %>%
+  group_by(id, region) %>%
+  summarise(cost = mean(cost), .groups = "drop")
+```
+
+Because `.by` grouping is temporary, you don't need to worry about ungrouping and it never needs to emit a message to remind you what is happening:
+
+```{r}
+expenses %>%
+  summarise(cost = mean(cost), .by = c(id, region))
+```
+
+Note that we specified multiple columns to group by using the [tidy-select][dplyr_tidy_select] syntax `c(id, region)`.
+If you have a character vector of column names you'd like to group by, you can do so with `.by = all_of(my_cols)`.
+
+To prevent surprising results, you can't use `.by` on an existing grouped data frame:
+
+```{r, error=TRUE}
+expenses %>% 
+  group_by(id) %>%
+  summarise(cost = mean(cost), .by = c(id, region))
+```
+
+So far we've focused on the usage of `.by` with `summarise()`, but `.by` works with a number of other dplyr verbs.
+For example, you could append the mean cost per region onto the original data frame as a new column rather than computing a summary:
+
+```{r}
+expenses %>%
+  mutate(cost_by_region = mean(cost), .by = region)
+```
+
+Or you could slice out the maximum cost per combination of id and region:
+
+```{r}
+expenses %>%
+  slice_max(cost, n = 1, by = c(id, region))
+```
+
+Again, note that the result of this `slice_max()` is an ungrouped data frame, which is probably what you'd expect here.
+Compare that to the `group_by()` approach, which uses persistent grouping and returns another grouped data frame:
+
+```{r}
+expenses %>%
+  group_by(id, region) %>%
+  slice_max(cost, n = 1)
+```