Create, modify, and delete columns

mutate() creates new columns that are functions of existing variables. It can also modify (if the name is the same as an existing column) and delete columns (by setting their value to NULL).

# S3 method for class 'SummarizedExperiment'
mutate(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more 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 frame if ungrouped).
NULL, to remove the column.
A data frame or tibble, to create multiple columns in the output.

Value

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

Columns from .data will be preserved according to the .keep argument.
Existing columns that are modified by ... will always be returned in their original location.
New columns created through ... will be placed according to the .before and .after arguments.
The number of rows is not affected.
Columns given the value NULL will be removed.
Groups will be recomputed if a grouping variable is mutated.
Data frame attributes are preserved.

Useful mutate functions

+, -, log(), etc., for their usual mathematical meanings
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()

Grouped tibbles

Because mutating expressions are computed within groups, they may yield different results on grouped tibbles. This will be the case as soon as an aggregating, lagging, or ranking function is involved. 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 the latter normalises by the averages within species levels.

Methods

This function is a generic, which means that packages can provide implementations (methods) for other classes. See the documentation of individual methods for extra arguments and differences in behaviour.

Methods available in currently loaded packages: dplyr (data.frame), plotly (plotly), tidySummarizedExperiment (SummarizedExperiment) .

References

Hutchison, W.J., Keyes, T.J., The tidyomics Consortium. et al. The tidyomics ecosystem: enhancing omic data analyses. Nat Methods 21, 1166–1170 (2024). https://doi.org/10.1038/s41592-024-02299-2

Wickham, H., François, R., Henry, L., Müller, K., Vaughan, D. (2023). dplyr: A Grammar of Data Manipulation. R package version 2.1.4, https://CRAN.R-project.org/package=dplyr

Examples

data(pasilla)
pasilla |> mutate(logcounts=log2(counts))
#> # A SummarizedExperiment-tibble abstraction: Features=14599 | Samples=7 | 
#> #   Assays=counts, logcounts
#> #                                                    |------ COVARIATES ----|
#>        .feature    .sample | counts logcounts        | condition type       |
#>        <chr>       <chr>   | <chr>  <chr>            | <chr>     <chr>      |
#> 1      FBgn0000003 untrt1  | 0      -Inf             | untreated single_end |
#> 2      FBgn0000008 untrt1  | 92     6.52356195605701 | untreated single_end |
#> 3      FBgn0000014 untrt1  | 5      2.32192809488736 | untreated single_end |
#> 4      FBgn0000015 untrt1  | 0      -Inf             | untreated single_end |
#> 5      FBgn0000017 untrt1  | 4664   12.1873520732005 | untreated single_end |
#>        --------    ------- - ------ ---------        - --------- ----       -
#> 102189 FBgn0261571 trt3    | 0      -Inf             | treated   paired_end |
#> 102190 FBgn0261572 trt3    | 3      1.58496250072116 | treated   paired_end |
#> 102191 FBgn0261573 trt3    | 1908   10.8978454560055 | treated   paired_end |
#> 102192 FBgn0261574 trt3    | 3047   11.5731737846865 | treated   paired_end |
#> 102193 FBgn0261575 trt3    | 4      2                | treated   paired_end |