mutate {dplyr} | R Documentation

## Add new variables

### Description

`mutate()` adds new variables and preserves existing; `transmute()` drops existing variables.

### Usage

    mutate(.data, ...)

    transmute(.data, ...)

### Arguments

`.data` | A tbl. All main verbs are S3 generics and provide methods for `tbl_df()`, `dtplyr::tbl_dt()` and `dbplyr::tbl_dbi()`.
`...` | Name-value pairs of expressions. Use `NULL` to drop a variable. These arguments are automatically quoted and evaluated in the context of the data frame. They support unquoting and splicing. See `vignette("programming")` for an introduction to these concepts.

### Value

An object of the same class as `.data`.

### Useful functions

- `+`, `-` etc

- `log()`

- `lead()`, `lag()`

- `dense_rank()`, `min_rank()`, `percent_rank()`, `row_number()`, `cume_dist()`, `ntile()`

- `cumsum()`, `cummean()`, `cummin()`, `cummax()`, `cumany()`, `cumall()`

- `na_if()`, `coalesce()`

- `if_else()`, `recode()`, `case_when()`

### Scoped mutation and transmutation

The three scoped variants of `mutate()` (`mutate_all()`, `mutate_if()` and `mutate_at()`) and the three variants of `transmute()` (`transmute_all()`, `transmute_if()`, `transmute_at()`) make it easy to apply a transformation to a selection of variables.

### Tidy data

When applied to a data frame, row names are silently dropped. To preserve, convert to an explicit variable with `tibble::rownames_to_column()`.

### See Also

Other single table verbs: `arrange`, `filter`, `select`, `slice`, `summarise`

### Examples

    # Newly created variables are available immediately
    mtcars %>% as_tibble() %>% mutate(
      cyl2 = cyl * 2,
      cyl4 = cyl2 * 2
    )

    # You can also use mutate() to remove variables and
    # modify existing variables
    mtcars %>% as_tibble() %>% mutate(
      mpg = NULL,
      disp = disp * 0.0163871 # convert to litres
    )

    # window functions are useful for grouped mutates
    mtcars %>%
     group_by(cyl) %>%
     mutate(rank = min_rank(desc(mpg)))
    # see `vignette("window-functions")` for more details

    # You can drop variables by setting them to NULL
    mtcars %>% mutate(cyl = NULL)

    # mutate() vs transmute --------------------------
    # mutate() keeps all existing variables
    mtcars %>%
      mutate(displ_l = disp / 61.0237)

    # transmute keeps only the variables you create
    mtcars %>%
      transmute(displ_l = disp / 61.0237)

    # mutate() supports quasiquotation. You can unquote quosures, which
    # can refer to both contextual variables and variable names:
    var <- 100
    as_tibble(mtcars) %>% mutate(cyl = !! quo(cyl * var))

[Package dplyr version 0.7.4 Index]