Skip to main content
v2026.11,986 entries · CC-BY 4.0

mutate Function in R: Syntax, .by, .keep and Examples

Add or change data frame columns with dplyr mutate(): syntax, grouped calculations with .by, .keep options, NULL and common errors.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

Short answer: mutate() is the dplyr function that adds new columns to a data frame, or changes existing ones, while keeping every row. You write one or more name = expression pairs; the expression is evaluated using the data frame’s own columns. This guide is for researchers and analysts who have a data frame in R and need to derive a variable from existing ones (a unit conversion, a centred score, a per-group value) and check that the result is what they intended.

What mutate() is used for in research

Most analysis datasets need derived variables before any model or table: converting units, computing a change score, centring a measure within a cohort, recoding a category, or flagging records. mutate() does this without reducing the number of rows. The official reference describes the result as having the same type as the input, with the same number of rows, modified existing columns keeping their position, and new columns added on the right by default (dplyr reference, mutate(), read 2026-11-08).

It is different from summarise(), which collapses rows. If you need one row per group, see grouping in R; if you need a conditional recode inside a mutate() call, see case_when in R.

Install or access

mutate() is part of the dplyr package, which is also loaded by the tidyverse meta-package. Install it once from CRAN and load it in each session:

install.packages("dplyr")
library(dplyr)

Your data must already be in R as a data frame or tibble. If it is not, start with how to import data in R.

Step-by-step: add a column with mutate()

The examples below use airquality, a data set that ships with R. They are illustrative; the point is the pattern, not the values.

Signature

For a data frame the documented usage is:

mutate(.data, ..., .by = NULL, .keep = c("all", "used", "unused", "none"), .before = NULL, .after = NULL)

1. Add one column

  1. Pass the data frame as the first argument (or pipe it in).
  2. Give the new column a name and an expression:
    airquality |> mutate(temp_c = (Temp - 32) * 5 / 9)

    The pipe |> is the form used in the current dplyr documentation; %>% also works once dplyr is loaded.

  3. Assign the result to an object if you want to keep it: aq2 <- airquality |> mutate(...). mutate() returns a new data frame; it does not modify airquality in place.

2. Add several columns in one call

Separate the pairs with commas. Later expressions can use columns created earlier in the same call:

airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, temp_c_rounded = round(temp_c, 1))

3. Overwrite or delete a column

Using an existing column name replaces that column in its current position. Setting a column to NULL removes it (the reference states that columns given the value NULL are removed):

airquality |> mutate(Temp = (Temp - 32) * 5 / 9, Wind = NULL)

4. Control where the new column appears

.before and .after take a column name or position; by default new columns go on the right-hand side:

airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, .before = 1)
airquality |> mutate(temp_c = (Temp - 32) * 5 / 9, .after = Temp)

5. Choose which columns to keep with .keep

.keep value Columns returned
"all" (default) All columns from the input, plus new ones
"used" Only the input columns used in your expressions, plus new ones
"unused" Only the input columns not used in your expressions, plus new ones
"none" No extra input columns, only the new ones

Per the reference, grouping columns and columns created in ... are always kept. transmute() does the same job as mutate(.keep = "none"); the dplyr documentation marks transmute() as superseded, so prefer .keep = "none" in new code.

6. Compute per group with .by (or group_by)

Expressions in mutate() are evaluated within each group, so the same expression gives a different answer on grouped and ungrouped data. The reference describes .by as an alternative to group_by() that applies to this one operation only:

airquality |> mutate(ozone_centred = Ozone - mean(Ozone, na.rm = TRUE), .by = Month)

Here the mean is calculated separately for each Month. Without .by, the mean would be over the whole data set. With group_by(Month) before mutate() you get the same grouped calculation, but the grouping stays on the result until you call ungroup(); with .by it does not persist. The reference also lists window functions (ranking, lead(), lag(), cumulative functions) as especially useful in grouped mutates.

7. Apply one expression to many columns

The reference shows across() inside mutate() for this. A sketch:

airquality |> mutate(across(c(Ozone, Solar.R), \(x) x / 1000, .names = "{.col}_k"))

Output and how to read it

  • Row count is unchanged. If the number of rows changes, the cause is a different function in your pipeline (for example filter() or summarise()), not mutate().
  • New columns sit on the right unless you used .before or .after; overwritten columns stay where they were.
  • Missing values propagate. Ozone in airquality contains NA values, so an expression such as Ozone - mean(Ozone) returns NA unless you set na.rm = TRUE inside mean().
  • Check the grouping. Printing a grouped tibble shows a Groups: line. If you did not mean to leave the data grouped, call ungroup() or use .by.
  • Spot-check a few rows by hand against the source values, particularly for derived variables that feed a statistical model.

Troubleshooting

Could not find function “mutate”

dplyr is not loaded. Run library(dplyr) (or library(tidyverse)) first; if R reports that the package is missing, run install.packages("dplyr").

The new column length does not match

The documented accepted values are a length-1 value (recycled to every row), a vector the same length as the current group (or the whole data frame if ungrouped), NULL, or a data frame. A vector of any other length is not an accepted input, so make sure it is length 1 or matches the group size.

The result is the same for every group

You computed a summary on ungrouped data. Add .by = your_group_column or a preceding group_by().

Later steps behave oddly after mutate()

The data may still be grouped from an earlier group_by(). Check the printed Groups: line and use ungroup().

You expected the original data to change

Assign the output (df <- df |> mutate(...)); the function returns a modified copy.

Free alternatives

dplyr is free and open source. Within base R, the options below need no extra package. For a worked comparison of transform() and mutate(), see transformation in R.

Approach What it does Source note
transform() (base R) Evaluates tag=value expressions inside the data frame; matching columns are replaced, others appended R manual, transform; its Warning section says it is intended for interactive use and recommends standard subsetting for programming
within() (base R) Listed in the R manual as a more flexible approach than transform() R manual, See Also of transform
mutate() (dplyr) Adds or modifies columns, with .by, .keep, .before, .after dplyr reference

FAQ

What does the mutate function do in R?

It creates new columns or modifies existing ones in a data frame using expressions of the existing columns, and returns a data frame with the same number of rows.

What is the difference between mutate() and transmute()?

mutate() keeps all existing columns by default; transmute() keeps only the columns you compute. The dplyr documentation states that transmute() is superseded because mutate(.keep = "none") does the same thing.

How do I use mutate() by group?

Use .by = column inside mutate() for a one-off grouped calculation, or group_by() before it (followed by ungroup()).

How do I delete a column with mutate()?

Assign NULL to it: mutate(df, col = NULL).

Can mutate() make several columns at once?

Yes: list several name = expression pairs separated by commas, or use across() to apply one function to many columns.

Sources

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about mutate Function in R: Syntax, .by, .keep and Examples

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →