filter-joins.SpatVector: Filtering joins for 'SpatVector' objects

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

Filtering joins for SpatVector objects

Description

Filtering joins filter rows from x based on the presence or absence of matches in y:

• semi_join() return all rows from x with a match in y.

• anti_join() return all rows from x without a match in y.

See dplyr::semi_join() for details.

Usage

## S3 method for class 'SpatVector'
semi_join(x, y, by = NULL, copy = FALSE, ...)

## S3 method for class 'SpatVector'
anti_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

x	A SpatVector created with terra::vect().
y	A data frame or other object coercible to a data frame. If a SpatVector of sf object is provided it would return an error (see terra::intersect() for performing spatial joins).
by	A join specification created with join_by(), or a character vector of variables to join by. If NULL, the default, ⁠*_join()⁠ will perform a natural join, using all variables in common across x and y. A message lists the variables so that you can check they're correct; suppress the message by supplying by explicitly. To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b. To join by multiple variables, use a join_by() specification with multiple expressions. For example, join_by(a == b, c == d) will match x$a to y$b and x$c to y$d. If the column names are the same between x and y, you can shorten this by listing only the variable names, like join_by(a, c). join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins. For simple equality joins, you can alternatively specify a character vector of variable names to join by. For example, by = c("a", "b") joins x$a to y$a and x$b to y$b. If variable names differ between x and y, use a named character vector like by = c("x_a" = "y_a", "x_b" = "y_b"). To perform a cross-join, generating all combinations of x and y, see cross_join().
copy	If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.
...	Other parameters passed onto methods.

Value

A SpatVector object.

terra equivalent

terra::merge()

Methods

Implementation of the generic dplyr::semi_join() family

SpatVector

The geometry column has a sticky behavior. This means that the result would have always the geometry of x for the records that matches the join conditions.

See Also

dplyr::semi_join(), dplyr::anti_join(), terra::merge()

Other dplyr verbs that operate on pairs Spat*/data.frame: bind_cols.SpatVector, bind_rows.SpatVector, mutate-joins.SpatVector

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

Examples

library(terra)
library(ggplot2)

# Vector
v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

# A data frame
df <- data.frame(
  cpro = sprintf("%02d", 1:10),
  x = runif(10),
  y = runif(10),
  letter = rep_len(LETTERS[1:3], length.out = 10)
)

v

# Semi join
semi <- v %>% semi_join(df)

semi

autoplot(semi, aes(fill = iso2)) + ggtitle("Semi Join")


# Anti join

anti <- v %>% anti_join(df)

anti

autoplot(anti, aes(fill = iso2)) + ggtitle("Anti Join")

tidyterra documentation built on April 15, 2025, 1:15 a.m.