mutate( )

Add or transform columns in a data frame. mutate() is from the dplyr package, which is part of the tidyverse.

Original Documentation ↗ dplyr Cheatsheet ↗

Required Library

install.packages("tidyverse")
library(tidyverse)

Syntax

df %>% mutate(new_col = expression)

df %>% mutate(new_col = expression) adds a new column to a data frame. The expression on the right can reference any existing column by name.

df %>% mutate(new_col = expression, another_col = expression)

df %>% mutate(col1 = ..., col2 = ...) adds multiple columns in a single call. Later expressions can reference columns created earlier in the same mutate().

df %>% mutate(..., .keep = "all", .before = NULL, .after = NULL)

df %>% mutate(..., .keep = "all") controls which columns are kept in the result. The default "all" retains every column, including unmodified ones. The optional .before / .after arguments control where new columns are inserted.

Coding convention — never round inside mutate()

Store full-precision values in all columns. Apply signif() or round() only inside cat() when printing a final result. Rounding a column that feeds into later calculations accumulates error.

Argument Overview

Required arguments must be included when using a function while optional arguments can be included on demand.

.data data frame | tibble Required

The data frame to modify. In a pipe (%>% or %>%), this is passed automatically from the left-hand side — you do not write it explicitly.

# .data is passed automatically by the pipe:
capsules %>% mutate(fill_mass_mg = mass_filled_mg - mass_empty_mg)

Data Types: data.frame | tibble

… — name–expression pairs name = expr Required

One or more expressions of the form new_column_name = expression. The right-hand side can reference any column in .data by name, and can also reference columns created earlier in the same mutate() call. Separate multiple expressions with commas.

mutate(
  fill_mass_mg = mass_filled_mg - mass_empty_mg,   # uses two existing columns
  ibu_mg       = fill_mass_mg * ibu_per_mg_powder  # references the column just created above
)

Data Types: any expression that returns a vector the same length as the data frame, or a single value (recycled to all rows)

.keep character Optional

Controls which columns from .data appear in the output alongside the new/modified columns.

Value	Behaviour
`"all"`	Keep all original columns (default)
`"used"`	Keep only columns referenced in the expressions
`"unused"`	Keep only columns not referenced
`"none"`	Drop all original columns (equivalent to `transmute()`)

Data Types: character — one of “all”, “used”, “unused”, “none”

.before / .after column name | integer Optional

Controls where the new columns are inserted. By default new columns are appended on the right.

capsules %>% mutate(fill_mass_mg = mass_filled_mg - mass_empty_mg, .after = mass_filled_mg)

Data Types: unquoted column name or integer position

Examples

Capsule content uniformity — computing fill mass and % label claim

Flagging out-of-specification results

Use mutate() with ifelse() to add a pass/fail column based on a criterion.

Concentration units conversion