mutate.Spat: Create, modify, and delete cell values/layers/attributes of...

In tidyterra: 'tidyverse' Methods and 'ggplot2' Helpers for 'terra' Objects

Create, modify, and delete cell values/layers/attributes of ⁠Spat*⁠ objects

Description

mutate() adds new layers/attributes and preserves existing ones on a ⁠Spat*⁠ object.

Usage

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

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

Arguments

.data	A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().
...	<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.
.keep	Control which columns from .data are retained in the output. Grouping columns 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 new columns. This is useful for checking your work, as it displays inputs and outputs side-by-side. "unused" retains only the columns not used in ... to create new columns. This is useful if you generate new columns, but no longer need the columns used to generate them. "none" doesn't retain any extra columns from .data. Only the grouping variables and columns created by ... are kept.
.before, .after	<tidy-select> Optionally, control where new columns should appear (the default is to add to the right hand side). See relocate() for more details.
.by	<tidy-select> Optionally, a selection of columns to group by for just this operation, functioning as an alternative to group_by(). For details and examples, see ?dplyr_by.

Value

A ⁠Spat*⁠ object of the same class than .data. See Methods.

terra equivalent

Some terra methods for modifying cell values: terra::ifel(), terra::classify(), terra::clamp(), terra::app(), terra::lapp(), terra::tapp()

Methods

Implementation of the generic dplyr::mutate() method.

SpatRaster

Add new layers and preserves existing ones. The result is a SpatRaster with the same extent, resolution and CRS than .data. Only the values (and possibly the number) of layers is modified.

SpatVector

The result is a SpatVector with the modified (and possibly renamed) attributes on the function call.

See Also

dplyr::mutate() methods.

terra provides several ways to modify ⁠Spat*⁠ objects:

• terra::ifel().

• terra::classify().

• terra::clamp().

• terra::app(), terra::lapp(), terra::tapp().

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

Other dplyr verbs that operate on columns: glimpse.Spat, pull.Spat, relocate.Spat, rename.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group-by.SpatVector, mutate-joins.SpatVector, pull.Spat, relocate.Spat, rename.Spat, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)

# SpatRaster method
f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")
spatrast <- rast(f)

mod <- spatrast |>
  mutate(exp_lyr1 = exp(tavg_04 / 10)) |>
  select(tavg_04, exp_lyr1)

mod
plot(mod)

# SpatVector method
f <- system.file("extdata/cyl.gpkg", package = "tidyterra")
v <- vect(f)

v |>
  mutate(cpro2 = paste0(cpro, "-CyL")) |>
  select(cpro, cpro2)

tidyterra documentation built on March 11, 2026, 9:08 a.m.