tidyterra (version 1.3.0)

group_by.SpatVector: 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 SpatVector
group_by(.data, ..., .add = FALSE, .drop = group_by_drop_default(.data))
# S3 method for SpatVector
ungroup(x, ...)

Value

A SpatVector object with updated grouping metadata.

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.

Methods

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

Grouping metadata

Mixing terra and dplyr syntax on a grouped or row-wise SpatVector, for example by subsetting with v[1:3, 1:2], can corrupt its grouping metadata. tidyterra attempts to restore this metadata the next time you use a dplyr verb on the object.

Some operations, such as terra::spatSample(), create a new SpatVector without preserving grouping metadata. Call group_by.SpatVector() or rowwise.SpatVector() again, as appropriate.

Details

See Details on dplyr::group_by().

See Also

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

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

Other dplyr grouping methods: group_data.SpatVector(), group_map.SpatVector(), group_nest.SpatVector(), group_split.SpatVector(), group_trim.SpatVector()

Examples

# \donttest{

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

by_name1 <- p |> group_by(NAME_1)

# Grouping does not change how the SpatVector looks.
by_name1

# But it adds 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 remove 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 append instead.
by_name2_name1 |>
  group_by(ID_1, ID_2, .add = TRUE) |>
  group_vars()

# You can group by expressions. This is shorthand for a mutate() followed
# by a group_by().
p |>
  group_by(ID_COMB = ID_1 * 100 / ID_2) |>
  relocate(ID_COMB, .before = 1)
# }