mutate function - RDocumentation (2024)


mutate() adds new variables and preserves existing ones;transmute() adds new variables and drops existing ones.New variables overwrite existing variables of the same name.Variables can be removed by setting their value to NULL.


mutate(.data, ...)

# S3 method for data.framemutate( .data, ..., .keep = c("all", "used", "unused", "none"), .before = NULL, .after = NULL)

transmute(.data, ...)


An object of the same type as .data. The output has the followingproperties:



A data frame, data frame extension (e.g. a tibble), or alazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, formore details.


<data-masking> Name-value pairs.The name gives the name of the column in the output.

The value can be:

  • A vector of length 1, which will be recycled to the correct length.

  • A vector the same length as the current group (or the whole data frameif ungrouped).

  • NULL, to remove the column.

  • A data frame or tibble, to create multiple columns in the output.


mutate function - RDocumentation (1)Control which columns from .data are retained in the output. Groupingcolumns and columns created by ... are always kept.

  • "all" retains all columns from .data. This is the default.

  • "used" retains only the columns used in ... to create newcolumns. This is useful for checking your work, as it displays inputsand outputs side-by-side.

  • "unused" retains only the columns not used in ... to create newcolumns. This is useful if you generate new columns, but no longer needthe columns used to generate them.

  • "none" doesn't retain any extra columns from .data. Only the groupingvariables and columns created by ... are kept.

.before, .after

mutate function - RDocumentation (2)<tidy-select> Optionally, control where new columnsshould appear (the default is to add to the right hand side). Seerelocate() for more details.

Useful mutate functions

  • +, -, log(), etc., for their usual mathematical meanings

  • lead(), lag()

  • dense_rank(), min_rank(), percent_rank(), row_number(),cume_dist(), ntile()

  • c*msum(), cummean(), cummin(), cummax(), cumany(), cumall()

  • na_if(), coalesce()

  • if_else(), recode(), case_when()

Grouped tibbles

Because mutating expressions are computed within groups, they mayyield different results on grouped tibbles. This will be the caseas soon as an aggregating, lagging, or ranking function isinvolved. Compare this ungrouped mutate:

starwars %>% select(name, mass, species) %>% mutate(mass_norm = mass / mean(mass, na.rm = TRUE))

With the grouped equivalent:

starwars %>% select(name, mass, species) %>% group_by(species) %>% mutate(mass_norm = mass / mean(mass, na.rm = TRUE))

The former normalises mass by the global average whereas thelatter normalises by the averages within species levels.


These function are generics, which means that packages can provideimplementations (methods) for other classes. See the documentation ofindividual methods for extra arguments and differences in behaviour.

Methods available in currently loaded packages:

  • mutate(): dplyr:::methods_rd("mutate").

  • transmute(): dplyr:::methods_rd("transmute").

See Also

Other single table verbs: arrange(),filter(),rename(),select(),slice(),summarise()


Run this code

# Newly created variables are available immediatelystarwars %>% select(name, mass) %>% mutate( mass2 = mass * 2, mass2_squared = mass2 * mass2 )# As well as adding new variables, you can use mutate() to# remove variables and modify existing variables.starwars %>% select(name, height, mass, homeworld) %>% mutate( mass = NULL, height = height * 0.0328084 # convert to feet )# Use across() with mutate() to apply a transformation# to multiple columns in a tibble.starwars %>% select(name, homeworld, species) %>% mutate(across(!name, as.factor))# see more in ?across# Window functions are useful for grouped mutates:starwars %>% select(name, mass, homeworld) %>% group_by(homeworld) %>% mutate(rank = min_rank(desc(mass)))# see `vignette("window-functions")` for more details# By default, new columns are placed on the far right.# Experimental: you can override with `.before` or `.after`df <- tibble(x = 1, y = 2)df %>% mutate(z = x + y)df %>% mutate(z = x + y, .before = 1)df %>% mutate(z = x + y, .after = x)# By default, mutate() keeps all columns from the input data.# Experimental: You can override with `.keep`df <- tibble(x = 1, y = 2, a = "a", b = "b")df %>% mutate(z = x + y, .keep = "all") # the defaultdf %>% mutate(z = x + y, .keep = "used")df %>% mutate(z = x + y, .keep = "unused")df %>% mutate(z = x + y, .keep = "none") # same as transmute()# Grouping ----------------------------------------# The mutate operation may yield different results on grouped# tibbles because the expressions are computed within groups.# The following normalises `mass` by the global average:starwars %>% select(name, mass, species) %>% mutate(mass_norm = mass / mean(mass, na.rm = TRUE))# Whereas this normalises `mass` by the averages within species# levels:starwars %>% select(name, mass, species) %>% group_by(species) %>% mutate(mass_norm = mass / mean(mass, na.rm = TRUE))# Indirection ----------------------------------------# Refer to column names stored as strings with the `.data` pronoun:vars <- c("mass", "height")mutate(starwars, prod = .data[[vars[[1]]]] * .data[[vars[[2]]]])# Learn more in ?dplyr_data_masking

Run the code above in your browser using DataLab

mutate function - RDocumentation (2024)


Top Articles
Latest Posts
Article information

Author: The Hon. Margery Christiansen

Last Updated:

Views: 6095

Rating: 5 / 5 (50 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: The Hon. Margery Christiansen

Birthday: 2000-07-07

Address: 5050 Breitenberg Knoll, New Robert, MI 45409

Phone: +2556892639372

Job: Investor Mining Engineer

Hobby: Sketching, Cosplaying, Glassblowing, Genealogy, Crocheting, Archery, Skateboarding

Introduction: My name is The Hon. Margery Christiansen, I am a bright, adorable, precious, inexpensive, gorgeous, comfortable, happy person who loves writing and wants to share my knowledge and understanding with you.