Join two data frames on a spatial relationship

Attaches the columns of y to each row of x that it relates to, the way merge() attaches them on a shared key. The geometry of x is kept and the geometry of y is dropped.

Usage

ga_join(
  x,
  y,
  predicate = ga_sparse_intersects,
  ...,
  suffix = c("_x", "_y"),
  left = TRUE
)

Arguments

x, y

data frames, each with one GeoArrow geometry column

predicate

a sparse predicate, by default ga_sparse_intersects()

suffix

the pair of suffixes added to column names found in both frames

left

whether to keep rows of x that match nothing

Value

an Arrow table with the columns of x followed by the non geometry columns of y

Details

A row of x matching several rows of y is repeated once per match, so the result is usually longer than x. With left = TRUE a row matching nothing is kept once with NA in every column from y; with left = FALSE it is dropped.

predicate is any of the sparse predicates, such as ga_sparse_within() or ga_sparse_touches(). It is called once as predicate(x_geometry, y_geometry), so points in polygons is ga_sparse_within() and polygons holding points is ga_sparse_contains().

Columns the two frames share are suffixed rather than overwritten. Both frames need exactly one GeoArrow geometry column.

See also

Other topology: ga_contains(), ga_coordinate_position(), ga_dimension(), ga_filter(), ga_is_empty(), ga_relate(), ga_sparse_intersects(), ga_sparse_pairs()

Examples

nc <- as.data.frame(read_shapefile(
  system.file("shape/nc.shp", package = "sf")
))
counties <- nc[c("NAME", "geometry")]
sites <- data.frame(
  site = c("a", "b"),
  geometry = geoarrow::as_geoarrow_vctr(
    ga_xy(c(-78.6, -80.8), c(35.8, 35.2))
  )
)

# which county each site falls in
ga_join(sites, counties, ga_sparse_within)
#> Table
#> 2 rows x 3 columns
#> $site <string>
#> $geometry: geoarrow.point <crs <unspecified>>
#> $NAME <string>

# every pair of neighbouring counties
head(ga_join(counties, counties, ga_sparse_touches)[c("NAME_x", "NAME_y")], 3)
#> Table
#> 3 rows x 2 columns
#> $NAME_x <string>
#> $NAME_y <string>