Lookup function for a single COMID from S3 GeoParquet (optionally restricted to one HUC2). Queries one COMID from an S3-hosted, HUC2-partitioned GeoParquet dataset and returns an sf object. If `huc2` is provided, only that partition is scanned (fastest). If not, the function tries a glob over all HUC2 partitions and falls back to a shallower pattern if needed. The function: - loads DuckDB httpfs (S3) extension, - pushes an equality filter on `COMID` for row-group/file pruning, - converts WKB geometry to sf with the CRS you provide (default EPSG:4326).
Usage
lc_get_watershed(
comid,
huc2 = NA_character_,
huc2_filter = NULL,
bucket = "dmap-data-commons-ow",
prefix = "data/streamcat/LakeCatWatersheds/",
region = "us-east-1",
install_missing = FALSE,
keep_open = FALSE,
verbose = TRUE,
progress = TRUE,
threads = 4,
enable_object_cache = TRUE,
skip_describe = FALSE,
skip_counts = TRUE,
sf_crs = 4326,
retries = 5,
retry_base_delay = 0.5,
retry_max_delay = 8,
url_style = c("path", "virtual_hosted"),
s3_endpoint = NULL
)Arguments
- comid
Scalar COMID to query (numeric or character, required).
- huc2
Optional two-digit HUC2 string (e.g., "01") to restrict search to one partition.
- huc2_filter
Optional character vector of HUC2s to read (e.g., c("01","05")) for multi-partition pruning.
- bucket
Character(1). S3 bucket (default "dmap-data-commons-ow").
- prefix
Character(1). S3 prefix under the bucket (default "data/streamcat/LakeCatWatersheds/").
- region
Character(1). S3 region (default "us-east-1").
- install_missing
Logical. Install missing packages (duckdb, DBI, sf, wk) if needed (default FALSE).
- keep_open
Logical. Keep the DuckDB connection open (default FALSE). Note: the connection is not returned.
- verbose
Logical. Print progress messages (default TRUE).
- progress
Logical. Show a simple progress bar (default TRUE).
- threads
Integer or NULL. If set, `PRAGMA threads` for DuckDB (parallelism).
- enable_object_cache
Logical. Enable DuckDB object cache to speed repeated queries (default TRUE).
- skip_describe
Logical. Skip DESCRIBE step (default FALSE).
- skip_counts
Logical. Skip HUC2 counts step (default TRUE; no longer returned).
- sf_crs
Integer or character. CRS for the output sf object (default 4326).
- retries
Integer. Number of retries for transient S3/HTTP errors (default 5).
- retry_base_delay
Numeric. Initial exponential backoff delay in seconds (default 0.5).
- retry_max_delay
Numeric. Maximum backoff delay per attempt in seconds (default 8).
- url_style
Character. S3 URL style used by DuckDB httpfs, one of "path" or "virtual_hosted". Passed to `match.arg()`, default "path".
- s3_endpoint
Optional character(1). Custom S3 endpoint hostname (e.g., "s3.amazonaws.com"). NULL uses the default for the selected region.