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. Seevignette("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 transmuation

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))