Working with spatial data

spdgt.core provides functions to read spatial data as sf objects and to generate download URLs for sharing data with colleagues or other tools.

The spatial hierarchy

SpeedGoat organizes spatial data in a four-level hierarchy:

region -> DAU -> GMU -> subunit

Regions are the broadest boundaries (e.g., state-wide areas)
DAUs (data analysis units) are species-specific and versioned
GMUs (game management units) are species-specific
Subunits are the smallest units, often used as sampling units

Each level can be read as polygons or point centroids.

Reading spatial data

Every spatial level has a _sf function that returns an sf object in WGS84 (EPSG:4326):

library(spdgt.core)

# Polygons (default)
regions <- lkup_read_region_sf()
gmus <- lkup_read_gmu_sf(species_id = 1)
subunits <- lkup_read_subunit_sf(dau_id = 10)

# Centroids
region_pts <- lkup_read_region_sf(geometry = "point")
gmu_pts <- lkup_read_gmu_sf(species_id = 1, geometry = "point")

The returned sf object has the same columns as the tabular version plus a geometry column. You can plot, transform, or join it using any sf operation:

library(sf)

# Reproject to UTM
gmus_utm <- st_transform(gmus, crs = 32612)

# Plot
plot(gmus["name"])

DAU spatial data

lkup_read_dau_sf() works differently from the other _sf functions. Because DAU boundaries are derived from their constituent GMUs, the function reads GMU polygons and dissolves them into DAU boundaries:

daus <- lkup_read_dau_sf(species_id = 1)

This is more computationally intensive than the other spatial reads but produces the correct DAU boundaries.

Filtering spatial reads

All _sf functions accept the same filters as their tabular counterparts:

# Filter by name
lkup_read_region_sf(name = "North")

# Filter by species and include related resources
lkup_read_gmu_sf(species_id = 1, includes = "species")

# Combine filters
lkup_read_subunit_sf(gmu_id = 5, name = "Sub A")

The lkup_share_* functions generate a temporary authenticated URL that you can send to colleagues or use in other tools. The URL provides direct access to the data without requiring authentication:

# Tabular formats
lkup_share_region(format = "csv")
lkup_share_gmu(format = "parquet", species_id = 1)

# Spatial format (must use JSON for GeoJSON output)
lkup_share_gmu(format = "json", geometry = "polygon", species_id = 1)
lkup_share_subunit(format = "json", geometry = "point")

When sharing spatial data, the format must be "json" to produce valid GeoJSON.

Reading shared data

Use lkup_read_shared() to import data from a share URL back into R:

url <- lkup_share_region(format = "csv")
regions <- lkup_read_shared(url, type = "csv")

# JSON (returns tibble by default, or list with as_data_frame = FALSE)
url_json <- lkup_share_region(format = "json")
regions_json <- lkup_read_shared(url_json, type = "json")

# Parquet (requires the arrow package)
url_pq <- lkup_share_gmu(format = "parquet", species_id = 1)
gmus <- lkup_read_shared(url_pq, type = "parquet")

Pagination

By default, all read and share functions omit pagination (pages = list(omit = 1)), returning all records. For large datasets, you can paginate: