Skip to contents

Reduce multiple values down to a single value

Source: R/summarise.R
summarise.Rd

Create one or more scalar variables summarising the variables of an existing data.frame. Grouped data.frames will result in one row in the output for each group.

Usage

summarise(.data, ..., .groups = NULL)

summarize(.data, ..., .groups = NULL)

Arguments

.data

A data.frame.

...

Name-value pairs of summary functions. The name will be the name of the variable in the result.

A name can also be given with :=, e.g. total := sum(x). A string on the left of := is a gluestick template which is filled in from the calling environment, so that a name can be built from a variable, e.g. "{var}_mean" := mean(x).

.groups

character(1). Grouping structure of the result.

  • "drop_last": drops the last level of grouping.

  • "drop": all levels of grouping are dropped.

  • "keep": keeps the same grouping structure as .data.

When .groups is not specified, it is chosen based on the number of rows of the results:

  • If all the results have 1 row, you get "drop_last".

  • If the number of rows varies, you get "keep".

In addition, a message informs you of that choice, unless the result is ungrouped, the option "poorman.summarise.inform" is set to FALSE.

The value can be:

  • A vector of length 1, e.g. min(x), n(), or sum(is.na(y)).

  • A vector of length n, e.g. quantile().

Details

summarise() and summarize() are synonyms.

Automatic names

An unnamed expression is named after its code, e.g. mean(disp), and .data$disp is named disp. When the code is too long to read as a name, it is abbreviated with .... A call keeps its function, e.g. mean(...), and an operator keeps as many of its two sides as fit in 60 characters, e.g. ... %>% select(a, b).

The names are those of dplyr, with these differences:

  • The limit of 60 characters is fixed. dplyr keeps some names of up to 63 characters whose right side is a call, such as a long name followed by + g().

  • Characters are counted rather than bytes, so names with accented or other multibyte characters are not abbreviated sooner.

  • ? and := are treated as calls rather than operators, e.g. `?`(...), as R prints them.

Variables made inside expressions

A variable assigned inside an expression, e.g. { tmp <- x * 2; tmp + 1 }, can be used by the later expressions of the same call. On grouped data, each group has its own variables, so a variable assigned while evaluating one group is never seen by the next group. This differs from dplyr 1.0.10, where such a variable can leak into the groups evaluated after it.

Results of incompatible types across groups

On grouped data, the results of an expression for each group are combined into one column. When two results have incompatible types, e.g. a character in one group and a double in another, there is an error which names the type of the results before the incompatible one and the type of the incompatible one, as in dplyr 1.0.10, with these differences:

  • A factor is named <factor> and a data frame <data.frame>. dplyr adds a hash of the levels of a factor and the types of the columns of a data frame, e.g. <data.frame< a: double b: character >>.

  • When factors and character vectors come before the incompatible result, the group named for the results before it can differ. For example, with a factor, "b" and 1 as the results of groups 1 to 3, dplyr names group 1 as <character> and poorman names group 2.

Examples

# A summary applied to ungrouped tbl returns a single row
mtcars %>%
  summarise(mean = mean(disp), n = n())
#>       mean  n
#> 1 230.7219 32

# Usually, you'll want to group first
mtcars %>%
  group_by(cyl) %>%
  summarise(mean = mean(disp), n = n())
#>   cyl     mean  n
#> 1   4 105.1364 11
#> 2   6 183.3143  7
#> 3   8 353.1000 14

# You can summarise to more than one value:
mtcars %>%
   group_by(cyl) %>%
   summarise(qs = quantile(disp, c(0.25, 0.75)), prob = c(0.25, 0.75))
#> `summarise()` has grouped output by 'cyl'. You can override using the `.groups` argument.
#>   cyl     qs prob
#> 1   4  78.85 0.25
#> 2   4 120.65 0.75
#> 3   6 160.00 0.25
#> 4   6 196.30 0.75
#> 5   8 301.75 0.25
#> 6   8 390.00 0.75

# You use a data frame to create multiple columns so you can wrap
# this up into a function:
my_quantile <- function(x, probs) {
  data.frame(x = quantile(x, probs), probs = probs)
}
mtcars %>%
  group_by(cyl) %>%
  summarise(my_quantile(disp, c(0.25, 0.75)))
#> `summarise()` has grouped output by 'cyl'. You can override using the `.groups` argument.
#>   cyl      x probs
#> 1   4  78.85  0.25
#> 2   4 120.65  0.75
#> 3   6 160.00  0.25
#> 4   6 196.30  0.75
#> 5   8 301.75  0.25
#> 6   8 390.00  0.75

# Each summary call removes one grouping level (since that group
# is now just a single row)
mtcars %>%
  group_by(cyl, vs) %>%
  summarise(cyl_n = n()) %>%
  group_vars()
#> `summarise()` has grouped output by 'cyl'. You can override using the `.groups` argument.
#> [1] "cyl"