mutate: Create or transform variables

In poorman: A Poor Man's Dependency Free Recreation of 'dplyr'

Create or transform variables

Description

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

Usage

mutate(.data, ...)

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

transmute(.data, ...)

Arguments

.data	A data.frame.
...	Name-value pairs of expressions, each with length 1L. The name of each argument will be the name of a new column and the value will be its corresponding value. Use a NULL value in mutate to drop a variable. New variables overwrite existing variables of the same name. 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).
.keep	This argument allows you to control which columns from .data are retained in the output: "all", the default, retains all variables. "used" keeps any variables used to make new variables; it's useful for checking your work as it displays inputs and outputs side-by-side. "unused" keeps only existing variables not used to make new variables. "none", only keeps grouping keys (like transmute()). Grouping variables are always kept, unconditional to .keep.
.before, .after	<poor-select> Optionally, control where new columns should appear (the default is to add to the right hand side). See relocate() 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()

• cumsum(), cummin(), cummax()

• na_if(), coalesce()

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

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

mutate(mtcars, mpg2 = mpg * 2)
mtcars %>% mutate(mpg2 = mpg * 2)
mtcars %>% mutate(mpg2 = mpg * 2, cyl2 = cyl * 2)

# Newly created variables are available immediately
mtcars %>% mutate(mpg2 = mpg * 2, mpg4 = mpg2 * 2)

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

# By default, new columns are placed on the far right.
# You can override this with `.before` or `.after`.
df <- data.frame(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.
# You can override with `.keep`
df <- data.frame(
  x = 1, y = 2, a = "a", b = "b",
  stringsAsFactors = FALSE
)
df %>% mutate(z = x + y, .keep = "all") # the default
df %>% mutate(z = x + y, .keep = "used")
df %>% mutate(z = x + y, .keep = "unused")
df %>% mutate(z = x + y, .keep = "none") # same as transmute()

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

poorman documentation built on Oct. 29, 2026, 1:07 a.m.