group-by.SpatVector: Group a 'SpatVector' by one or more variables

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

Group a SpatVector by one or more variables

Description

Most data operations are done on groups defined by variables. group_by.SpatVector() adds new attributes to an existing SpatVector indicating the corresponding groups. See Methods.

Usage

## S3 method for class 'SpatVector'
group_by(.data, ..., .add = FALSE, .drop = group_by_drop_default(.data))

## S3 method for class 'SpatVector'
ungroup(x, ...)

Arguments

.data, x	A SpatVector object. See Methods.
...	<data-masking> In group_by(), variables or computations to group by. Computations are always done on the ungrouped data frame. To perform computations on the grouped data, you need to use a separate mutate() step before the group_by(). Computations are not allowed in nest_by(). In ungroup(), variables to remove from the grouping.
.add	When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.
.drop	Drop groups formed by factor levels that don't appear in the data? The default is TRUE except when .data has been previously grouped with .drop = FALSE. See group_by_drop_default() for details.

Details

See Details on dplyr::group_by().

Value

A SpatVector object with an additional attribute.

Methods

Implementation of the generic dplyr::group_by() family functions for SpatVector objects.

When mixing terra and dplyr syntax on a grouped SpatVector (i.e, subsetting a SpatVector like v[1:3,1:2]) the groups attribute can be corrupted. tidyterra would try to re-group the SpatVector. This would be triggered the next time you use a dplyr verb on your SpatVector.

Note also that some operations (as terra::spatSample()) would create a new SpatVector. In these cases, the result won't preserve the groups attribute. Use group_by() to re-group.

See Also

dplyr::group_by(), dplyr::ungroup()

Other dplyr verbs that operate on group of rows: count.SpatVector(), rowwise.SpatVector(), summarise.SpatVector()

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

Examples

library(terra)
f <- system.file("ex/lux.shp", package = "terra")
p <- vect(f)

by_name1 <- p |> group_by(NAME_1)

# grouping doesn't change how the SpatVector looks
by_name1

# But add metadata for grouping: See the coercion to tibble

# Not grouped
p_tbl <- as_tibble(p)
class(p_tbl)
head(p_tbl, 3)

# Grouped
by_name1_tbl <- as_tibble(by_name1)
class(by_name1_tbl)
head(by_name1_tbl, 3)

# It changes how it acts with the other dplyr verbs:
by_name1 |> summarise(
  pop = mean(POP),
  area = sum(AREA)
)

# Each call to summarise() removes a layer of grouping
by_name2_name1 <- p |> group_by(NAME_2, NAME_1)

by_name2_name1
group_data(by_name2_name1)

by_name2 <- by_name2_name1 |> summarise(n = dplyr::n())
by_name2
group_data(by_name2)

# To removing grouping, use ungroup
by_name2 |>
  ungroup() |>
  summarise(n = sum(n))

# By default, group_by() overrides existing grouping
by_name2_name1 |>
  group_by(ID_1, ID_2) |>
  group_vars()

# Use add = TRUE to instead append
by_name2_name1 |>
  group_by(ID_1, ID_2, .add = TRUE) |>
  group_vars()

# You can group by expressions: this is a short-hand
# for a mutate() followed by a group_by()
p |>
  group_by(ID_COMB = ID_1 * 100 / ID_2) |>
  relocate(ID_COMB, .before = 1)

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