Package 'duckspatial'

Description

as_duckspatial_df() creates a lazy spatial data frame (duckspatial_df) from various inputs. When x is a table name (character) or an existing DuckDB table (tbl_duckdb_connection), the function creates a zero-copy representation of the data directly from the database without loading it into memory. This is the canonical way to "register" or wrap existing persistent spatial tables.

CRS Persistence: duckspatial reads native DuckDB 1.5.0+ CRS metadata and, for compatibility with files written by older versions of duckspatial, CRS metadata stored in column comments. DuckDB files saved in pre-1.5.0 format without duckspatial-managed comments will not have CRS information and will default to NA with a warning.

Usage

as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'duckspatial_df'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'sf'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'tbl_duckdb_connection'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'tbl_lazy'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'character'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

## S3 method for class 'data.frame'
as_duckspatial_df(x, conn = NULL, crs = NULL, geom_col = NULL, ...)

Arguments

Value

A duckspatial_df object

Description

Convert a duckspatial_df to a nanoarrow_array_stream

Usage

as_nanoarrow_array_stream.duckspatial_df(x, ..., schema = NULL, native = FALSE)

Arguments

Value

A nanoarrow_array_stream

Description

Materializes a lazy duckspatial_df object by executing the underlying DuckDB query. Supports multiple output formats.

Usage

## S3 method for class 'duckspatial_df'
collect(x, ..., as = NULL)

ddbs_collect(x, ..., as = c("sf", "tibble", "raw", "geoarrow"))

Arguments

Value

Collected data in the specified format

Data in the specified format

Examples

## Not run: 
library(duckspatial)

# Load lazy spatial data
nc <- ddbs_open_dataset(system.file("shape/nc.shp", package = "sf"))

# Perform lazy operations
result <- nc |> dplyr::filter(AREA > 0.1)

# Collect to sf (default)
result_sf <- ddbs_collect(result)
plot(result_sf["AREA"])

# Collect as tibble without geometry (fast)
result_tbl <- ddbs_collect(result, as = "tibble")

# Collect with raw WKB bytes
result_raw <- ddbs_collect(result, as = "raw")

# Collect as geoarrow for Arrow workflows
result_ga <- ddbs_collect(result, as = "geoarrow")

## End(Not run)

Description

Applies an affine transformation to geometries using a 2x3 or 3x4 matrix.

Usage

ddbs_affine(
  x,
  matrix,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson",
  package = "duckspatial")
)

## 2D translation (shift x by 1, y by 2)
mat_2d <- matrix(c(1, 0, 1,
                   0, 1, 2), nrow = 2, byrow = TRUE)
ddbs_affine(argentina_ddbs, mat_2d)

## 2D scaling (scale x by 2, y by 3)
mat_scale <- matrix(c(2, 0, 0,
                      0, 3, 0), nrow = 2, byrow = TRUE)
ddbs_affine(argentina_ddbs, mat_scale)

## 3D transformation
mat_3d <- matrix(c(1, 0, 0, 1,
                   0, 1, 0, 2,
                   0, 0, 1, 0), nrow = 3, byrow = TRUE)
ddbs_affine(argentina_ddbs, mat_3d)

## End(Not run)

Description

Convert spatial geometries to common interchange formats using DuckDB spatial serialization functions.

• ddbs_as_text() – Convert geometries to Well-Known Text (WKT)

• ddbs_as_wkb() – Convert geometries to Well-Known Binary (WKB)

• ddbs_as_hexwkb() – Convert geometries to hexadecimal Well-Known Binary (HEXWKB)

• ddbs_as_geojson() – Convert geometries to GeoJSON

Usage

ddbs_as_text(x, conn = NULL)

ddbs_as_wkb(x, conn = NULL)

ddbs_as_hexwkb(x, conn = NULL)

ddbs_as_geojson(x, conn = NULL)

Arguments

Details

These functions are thin wrappers around DuckDB spatial serialization functions (ST_AsText, ST_AsWKB, ST_AsHEXWKB, and ST_AsGeoJSON).

They are useful for exporting geometries into widely supported formats for interoperability with external spatial tools, databases, and web services.

Value

Depending on the function:

• ddbs_as_text() returns a character vector of WKT geometries

• ddbs_as_wkb() returns a list of raw vectors (binary WKB)

• ddbs_as_hexwkb() returns a character vector of HEXWKB strings

• ddbs_as_geojson() returns a character vector of GeoJSON strings

Examples

## Not run: 
library(duckspatial)

argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", package = "duckspatial")
)

ddbs_as_text(argentina_ddbs)
ddbs_as_wkb(argentina_ddbs)
ddbs_as_hexwkb(argentina_ddbs)
ddbs_as_geojson(argentina_ddbs)

## End(Not run)

Description

Converts a data frame with coordinate columns into spatial point geometries.

Usage

ddbs_as_points(
  x,
  coords = c("lon", "lat"),
  crs = "EPSG:4326",
  remove = TRUE,
  na.fail = TRUE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE,
  ...
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(duckspatial)

## create sample data with coordinates
cities_df <- data.frame(
  city = c("Buenos Aires", "Córdoba", "Rosario"),
  lon = c(-58.3816, -64.1811, -60.6393),
  lat = c(-34.6037, -31.4201, -32.9468),
  population = c(3075000, 1391000, 1193605)
)

# option 1: convert data frame to sf object
cities_ddbs <- ddbs_as_points(cities_df)

# specify custom coordinate column names and keep them in output
cities_df2 <- data.frame(
  city = c("Mendoza", "Tucumán"),
  longitude = c(-68.8272, -65.2226),
  latitude = c(-32.8895, -26.8241)
)

ddbs_as_points(cities_df2, coords = c("longitude", "latitude"), remove = FALSE)


## option 2: convert table in duckdb to spatial table

# create a duckdb connection and write data
conn <- duckspatial::ddbs_create_conn()
DBI::dbWriteTable(conn, "cities_tbl", cities_df, overwrite = TRUE)

# convert to spatial table in database
ddbs_as_points(
    x = "cities_tbl",
    conn = conn,
    name = "cities_spatial",
    overwrite = TRUE
)

# read the spatial table
ddbs_read_table(conn, "cities_spatial")

## End(Not run)

Description

Returns the minimal rectangle that encloses the geometry

Usage

ddbs_bbox(
  x,
  by_feature = FALSE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

A bbox numeric vector with by_feature = FALSE A data.frame or ⁠lazy tbl⁠ when by_feature = TRUE

Examples

## Not run: 
## load packages
library(duckspatial)

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

# option 1: passing sf objects
ddbs_bbox(argentina_ddbs)

## option 2: passing the names of tables in a duckdb db

# creates a duckdb write sf to it
conn <- duckspatial::ddbs_create_conn()
ddbs_write_table(conn, argentina_ddbs, "argentina_tbl", overwrite = TRUE)

output2 <- ddbs_bbox(
    conn = conn,
    x = "argentina_tbl",
    name = "argentina_bbox"
)

DBI::dbReadTable(conn, "argentina_bbox")

## End(Not run)

Description

Perform geometric set operations between two sets of geometries.

Usage

ddbs_intersection(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_difference(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_sym_difference(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_crop(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

These functions perform different geometric set operations:

ddbs_intersection

Returns the geometric intersection of two sets of geometries, producing the area, line, or point shared by both.

ddbs_crop

Returns the geometric intersection of two sets of geometries, using the bounding box of y, rather than its original geometry

ddbs_difference

Returns the portion of the first geometry that does not overlap with the second geometry.

ddbs_sym_difference

Returns the portions of both geometries that do not overlap with each other. Equivalent to ⁠(A - B) UNION (B - A)⁠.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
library(duckspatial)
library(sf)

# Create two overlapping polygons for testing
poly1 <- st_polygon(list(matrix(c(
  0, 0,
  4, 0,
  4, 4,
  0, 4,
  0, 0
), ncol = 2, byrow = TRUE)))

poly2 <- st_polygon(list(matrix(c(
  2, 2,
  6, 2,
  6, 6,
  2, 6,
  2, 2
), ncol = 2, byrow = TRUE)))

x <- st_sf(id = 1, geometry = st_sfc(poly1), crs = 4326)
y <- st_sf(id = 2, geometry = st_sfc(poly2), crs = 4326)

# Visualize the input polygons
plot(st_geometry(x), col = "lightblue", main = "Input Polygons")
plot(st_geometry(y), col = "lightcoral", add = TRUE, alpha = 0.5)

# Intersection: only the overlapping area (2,2 to 4,4)
result_intersect <- ddbs_intersection(x, y)
plot(st_geometry(result_intersect), col = "purple", 
     main = "Intersection")

# Difference: part of x not in y (L-shaped area)
result_diff <- ddbs_difference(x, y)
plot(st_geometry(result_diff), col = "lightblue", 
     main = "Difference (x - y)")

# Symmetric Difference: parts of both that don't overlap
result_symdiff <- ddbs_sym_difference(x, y)
plot(st_geometry(result_symdiff), col = "orange", 
     main = "Symmetric Difference")

# Using with database connection
conn <- ddbs_create_conn(dbdir = "memory")

ddbs_write_vector(conn, x, "poly_x")
ddbs_write_vector(conn, y, "poly_y")

# Perform operations with connection
ddbs_intersection("poly_x", "poly_y", conn)
ddbs_difference("poly_x", "poly_y", conn)
ddbs_sym_difference("poly_x", "poly_y", conn)

# Save results to database table
ddbs_difference("poly_x", "poly_y", conn, name = "diff_result")

## End(Not run)

Description

Returns the boundary of geometries as a new geometry, e.g., the edges of polygons or the start/end points of lines.

Usage

ddbs_boundary(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

# read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

# store in duckdb
ddbs_write_table(conn, argentina_ddbs, "argentina")

# boundary
b <- ddbs_boundary(x = "argentina", conn)

## End(Not run)

Description

Computes a polygon that represents all locations within a specified distance from the original geometry

Usage

ddbs_buffer(
  x,
  distance,
  num_triangles = 8L,
  cap_style = "CAP_ROUND",
  join_style = "JOIN_ROUND",
  mitre_limit = 1,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_vector(conn, argentina_ddbs, "argentina")

## basic buffer
ddbs_buffer(conn = conn, "argentina", distance = 1)

## buffer with custom parameters
ddbs_buffer(conn = conn, "argentina", distance = 1, 
            num_triangles = 16, cap_style = "CAP_SQUARE")

## buffer without using a connection
ddbs_buffer(argentina_ddbs, distance = 1)

## End(Not run)

Description

Constructs polygon or multipolygon geometries from a collection of linestrings, handling intersections and creating unified areas. Returns POLYGON or MULTIPOLYGON (not wrapped in a geometry collection). Requires MULTILINESTRING input - for single linestrings, use ddbs_make_polygon().

Usage

ddbs_build_area(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

See Also

ddbs_make_polygon(), ddbs_polygonize()

Other polygon construction: ddbs_make_polygon(), ddbs_polygonize()

Description

Returns the geometric center (centroid) of a geometry as a point, representing its average position.

Usage

ddbs_centroid(
  x,
  method = "centroid",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_vector(conn, argentina_ddbs, "argentina")

## centroid
ddbs_centroid("argentina", conn)

## centroid without using a connection
ddbs_centroid(argentina_ddbs)

## End(Not run)

Description

Executes the accumulated query and stores the result in a DuckDB temporary table. The result remains lazy (a duckspatial_df) but points to the materialized data, avoiding repeated computation of complex query plans.

Usage

ddbs_compute(x, ..., name = NULL, temporary = TRUE)

Arguments

Details

This is useful when you want to:

• Cache intermediate results for reuse across multiple subsequent operations

• Simplify complex query plans before heavy operations like spatial joins

• Force execution at a specific point without pulling data into R memory

Value

A new duckspatial_df pointing to the materialized table

Examples

## Not run: 
library(duckspatial)
library(dplyr)

# Load lazy spatial data
countries <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", package = "duckspatial")
)

# Complex pipeline - ddbs_compute() caches intermediate result
cached <- countries |>
  filter(CNTR_ID %in% c("DE", "FR", "IT")) |>
  ddbs_compute()  # Execute and store in temp table

# Check query plan - should reference temp table
show_query(cached)

# Further operations continue from cached result
result <- cached |>
  ddbs_filter(other_layer, predicate = "intersects") |>
  st_as_sf()

## End(Not run)

Description

Returns the concave hull that tightly encloses the geometry, capturing its overall shape more closely than a convex hull.

Usage

ddbs_concave_hull(
  x,
  ratio = 0.5,
  allow_holes = TRUE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)
library(sf)

# create points data
n <- 5
points_ddbs <- data.frame(
  id = 1,
  x = runif(n, min = -180, max = 180),
  y = runif(n, min = -90, max = 90)
) |>
  ddbs_as_spatial(coords = c("x", "y")) |>
  ddbs_combine()

# option 1: passing ddbs or sf objects
output1 <- duckspatial::ddbs_concave_hull(points_ddbs, mode = "sf")

plot(output1)


# option 2: passing the name of a table in a duckdb db

# creates a duckdb
conn <- duckspatial::ddbs_create_conn()

# write sf to duckdb
ddbs_write_vector(conn, points_ddbs, "points_tbl")

# spatial join
output2 <- duckspatial::ddbs_concave_hull(
 conn = conn,
 x = "points_tbl",
 mode = "sf"
)

plot(output2)


## End(Not run)

Description

Returns the convex hull that encloses the geometry, forming the smallest convex polygon that contains all points of the geometry.

Usage

ddbs_convex_hull(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)
library(sf)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

# read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

# option 1: passing sf objects
output1 <- duckspatial::ddbs_convex_hull(x = argentina_ddbs, mode = "sf")

plot(output1["CNTR_NAME"])#' # store in duckdb

# option 2: passing the name of a table in a duckdb db

# creates a duckdb
conn <- duckspatial::ddbs_create_conn()

# write sf to duckdb
ddbs_write_vector(conn, argentina_ddbs, "argentina_tbl")

# spatial join
output2 <- duckspatial::ddbs_convex_hull(
 conn = conn,
 x = "argentina_tbl",
 mode = "sf"
)

plot(output2["CNTR_NAME"])

## End(Not run)

Description

It creates a DuckDB connection, and then it installs and loads the spatial extension

Usage

ddbs_create_conn(
  dbdir = "memory",
  threads = NULL,
  memory_limit_gb = NULL,
  upgrade = FALSE,
  ...,
  duckdb_storage_version = duckspatial_storage_default()
)

Arguments

Value

A duckdb_connection

Examples

## Not run: 
# load packages
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

# create a duckdb database in disk  (with spatial extension)
conn <- ddbs_create_conn(dbdir = "tempdir")

# create a connection with 1 thread and 2GB memory limit
conn <- ddbs_create_conn(threads = 1, memory_limit_gb = 2)
ddbs_stop_conn(conn)

## End(Not run)

Description

Check and create schema

Usage

ddbs_create_schema(conn, name, quiet = FALSE)

Arguments

Value

TRUE (invisibly) for successful schema creation

Examples

## load packages
## Not run: 
library(duckspatial)
library(duckdb)

## connect to in memory database
conn <- ddbs_create_conn(dbdir = "memory")

## create a new schema
ddbs_create_schema(conn, "new_schema")

## check schemas
dbGetQuery(conn, "SELECT * FROM information_schema.schemata;")

## disconnect from db
ddbs_stop_conn(conn)

## End(Not run)

Description

This is an S3 generic that extracts CRS information from various spatial objects.

Usage

ddbs_crs(x, ...)

## S3 method for class 'duckspatial_df'
ddbs_crs(x, ...)

## S3 method for class 'sf'
ddbs_crs(x, ...)

## S3 method for class 'tbl_duckdb_connection'
ddbs_crs(x, ...)

## S3 method for class 'character'
ddbs_crs(x, conn, ...)

## S3 method for class 'duckdb_connection'
ddbs_crs(x, name, ...)

## S3 method for class 'numeric'
ddbs_crs(x, ...)

## S3 method for class 'crs'
ddbs_crs(x, ...)

## S3 method for class 'data.frame'
ddbs_crs(x, ...)

## Default S3 method:
ddbs_crs(x, ...)

Arguments

Value

CRS object from sf package

Examples

## Not run: 
## load packages
library(duckdb)
library(duckspatial)
library(sf)

# Method 1: duckspatial_df objects
nc <- ddbs_open_dataset(system.file("shape/nc.shp", package = "sf"))
ddbs_crs(nc)

# Method 2: sf objects
nc_sf <- st_read(system.file("shape/nc.shp", package = "sf"))
ddbs_crs(nc_sf)

# Method 3: table name in database
conn <- ddbs_create_conn(dbdir = "memory")
ddbs_write_table(conn, nc_sf, "nc_table")
ddbs_crs(conn, "nc_table")
ddbs_stop_conn(conn)

## End(Not run)

Description

Get list of GDAL drivers and file formats

Usage

ddbs_drivers(conn = NULL)

Arguments

Value

data.frame

Examples

## Not run: 
## load package
library(duckspatial)

## database setup
conn <- ddbs_create_conn()

## check drivers
ddbs_drivers(conn)

## End(Not run)

Description

Removes the geometry column from a duckspatial_df object, returning a lazy tibble without spatial information.

Usage

ddbs_drop_geometry(x)

Arguments

Value

A lazy tibble backed by dbplyr

Examples

## Not run: 
## load package
library(duckspatial)

## read data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson",
  package = "duckspatial")
)

## drop geometry column
countries_tbl <- ddbs_drop_geometry(countries_ddbs)

## End(Not run)

Description

Decomposes multi-part or complex geometries into individual simple geometry components, returning one row per component geometry

Usage

ddbs_dump(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## aggregate rivers by name
rivers_agg_ddbs <- ddbs_union_agg(rivers_ddbs, by = "RIVER_NAME")

## dump into individual geometries
ddbs_dump(rivers_agg_ddbs)

## End(Not run)

Description

Returns the first or last point of a LINESTRING geometry. These functions only work with LINESTRING geometries (not MULTILINESTRING or other geometry types).

Usage

ddbs_line_startpoint(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_line_endpoint(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

These functions wrap DuckDB Spatial's ST_StartPoint and ST_EndPoint. Input geometries must be of type LINESTRING (MULTILINESTRING is not supported). For each input feature, the first or last coordinate of the LINESTRING is returned as a POINT geometry.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## store in duckdb
ddbs_write_vector(conn, rivers_ddbs, "rivers")

## extract start points
ddbs_line_startpoint(conn = conn, "rivers")

## extract end points
ddbs_line_endpoint(conn = conn, "rivers")

## without using a connection
ddbs_line_startpoint(rivers_ddbs)
ddbs_line_endpoint(rivers_ddbs)

## End(Not run)

Description

Returns the minimum axis-aligned rectangle that fully contains the geometry.

Usage

ddbs_envelope(
  x,
  by_feature = FALSE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

ST_Envelope returns the minimum bounding rectangle (MBR) of a geometry as a polygon. For points and lines, this creates a rectangular polygon that encompasses the geometry. For polygons, it returns the smallest rectangle that contains the entire polygon.

When by_feature = FALSE, all geometries are combined and a single envelope is returned that encompasses the entire dataset.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(duckspatial)

# read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

# input as sf, and output as sf
env <- ddbs_envelope(x = argentina_ddbs, by_feature = TRUE)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

# store in duckdb
ddbs_write_table(conn, argentina_ddbs, "argentina")

# envelope for each feature
env <- ddbs_envelope("argentina", conn, by_feature = TRUE)

# single envelope for entire dataset
env_all <- ddbs_envelope("argentina", conn, by_feature = FALSE)

# create a new table with envelopes
ddbs_envelope("argentina", conn, name = "argentina_bbox", by_feature = TRUE)

## End(Not run)

Description

Returns the outer boundary (exterior ring) of polygon geometries. For multi-polygons, returns the exterior ring of each individual polygon.

Usage

ddbs_exterior_ring(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_vector(conn, countries_ddbs, "countries")

## extract exterior ring
ddbs_exterior_ring(conn = conn, "countries")

## extract exterior ring without using a connection
ddbs_exterior_ring(countries_ddbs)

## End(Not run)

Description

Filters geometries based on a spatial relationship with another geometry, such as intersection, containment, or proximity.

Usage

ddbs_filter(
  x,
  y,
  predicate = "intersects",
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  distance = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

Spatial Join Predicates:

A spatial predicate is really just a function that evaluates some spatial relation between two geometries and returns true or false, e.g., “does a contain b” or “is a within distance x of b”. Here is a quick overview of the most commonly used ones, taking two geometries a and b:

• "ST_Intersects": Whether a intersects b

• "ST_Contains": Whether a contains b

• "ST_ContainsProperly": Whether a contains b without b touching a's boundary

• "ST_Within": Whether a is within b

• "ST_Overlaps": Whether a overlaps b

• "ST_Touches": Whether a touches b

• "ST_Equals": Whether a is equal to b

• "ST_Crosses": Whether a crosses b

• "ST_Covers": Whether a covers b

• "ST_CoveredBy": Whether a is covered by b

• "ST_DWithin": x) Whether a is within distance x of b

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
# RECOMMENDED: Efficient lazy workflow using ddbs_open_dataset
library(duckspatial)

# Load data directly as lazy spatial data frames (CRS auto-detected)
countries <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", package = "duckspatial")
)

argentina <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", package = "duckspatial")
)

# Lazy filter - computation stays in DuckDB
neighbors <- ddbs_filter(countries, argentina, predicate = "touches")

# Collect to sf when needed
neighbors_sf <- dplyr::collect(neighbors) |> sf::st_as_sf()


# Alternative: using sf objects directly (legacy compatibility)
library(sf)

countries_sf <- st_read(system.file("spatial/countries.geojson", package = "duckspatial"))
argentina_sf <- st_read(system.file("spatial/argentina.geojson", package = "duckspatial"))

result <- ddbs_filter(countries_sf, argentina_sf, predicate = "touches")


# Alternative: using table names in a duckdb connection
conn <- ddbs_create_conn(dbdir = "memory")

ddbs_write_table(conn, countries_sf, "countries")
ddbs_write_table(conn, argentina_sf, "argentina")

ddbs_filter(conn = conn, "countries", "argentina", predicate = "touches")

## End(Not run)

Description

Reflects geometries across their centroid. By default, flipping is applied relative to the centroid of all geometries; if by_feature = TRUE, each geometry is flipped relative to its own centroid.

Usage

ddbs_flip(
  x,
  direction = c("horizontal", "vertical"),
  by_feature = FALSE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_table(conn, argentina_ddbs, "argentina")

## flip all features together as a whole (default)
ddbs_flip(conn = conn, "argentina", direction = "horizontal", by_feature = FALSE)

## flip each feature independently
ddbs_flip(conn = conn, "argentina", direction = "horizontal", by_feature = TRUE)

## flip without using a connection
ddbs_flip(argentina_ddbs, direction = "horizontal")

## End(Not run)

Description

Returns a geometry with the X and Y coordinates swapped. This is useful for correcting geometries where longitude and latitude are in the wrong order, or for converting between coordinate systems with different axis orders.

Usage

ddbs_flip_coordinates(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_vector(conn, argentina_ddbs, "argentina")

## flip coordinates
ddbs_flip_coordinates("argentina", conn)

## flip coordinates without using a connection
ddbs_flip_coordinates(argentina_ddbs)

## End(Not run)

Description

Functions to force geometries to have specific coordinate dimensions (X, Y, Z, M)

Usage

ddbs_force_2d(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_force_3d(
  x,
  var,
  dim = "z",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_force_4d(
  x,
  var_z,
  var_m,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

These functions modify the dimensionality of geometries:

• ddbs_force_2d() removes Z and M coordinates from geometries, returning only X and Y coordinates. This is useful for simplifying 3D or measured geometries to 2D.

• ddbs_force_3d() forces geometries to have three dimensions. When dim = "z" (default), adds or retains Z coordinates (X, Y, Z). When dim = "m", adds or retains M coordinates (X, Y, M). Missing values are typically set to 0. If the input geometry has a third dimension already, it will be replaced by the new one. If the input geometry has 4 dimensions, it will drop the dimension that wasn't specified.

• ddbs_force_4d() forces geometries to have all four dimensions (X, Y, Z, M). Missing Z or M values are typically set to 0.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(dplyr)
library(duckspatial)

## load data and add 2 numeric vars
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
) |> 
  dplyr::filter(ISO3_CODE != "ATA") |> 
  ddbs_area(new_column = "area") |> 
  ddbs_perimeter(new_column = "perim") 

## add a Z dimension
countries_z_ddbs <- ddbs_force_3d(countries_ddbs, "area")
ddbs_has_z(countries_z_ddbs)

## add a M dimension as 3D (removes current Z)
countries_m_ddbs <- ddbs_force_3d(countries_z_ddbs, "area", "m")
ddbs_has_z(countries_m_ddbs)
ddbs_has_m(countries_m_ddbs)

## add both Z and M
countries_zm_ddbs <- ddbs_force_4d(countries_ddbs, "area", "perim")
ddbs_has_z(countries_zm_ddbs)
ddbs_has_m(countries_zm_ddbs)

## drop both ZM
countries_drop_ddbs <- ddbs_force_2d(countries_zm_ddbs)
ddbs_has_z(countries_drop_ddbs)
ddbs_has_m(countries_drop_ddbs)

## End(Not run)

Description

Creates random points within the bounding box of each geometry, which may fall outside the geometry itself.

Usage

ddbs_generate_points(
  x,
  n,
  seed = NULL,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## store in duckdb
ddbs_write_table(conn, argentina_ddbs, "argentina")

## generate 100 random points within each geometry
ddbs_generate_points("argentina", n = 100, conn)

## generate points without using a connection
ddbs_generate_points(argentina_ddbs, n = 100)

## End(Not run)

Description

Get the geometry column name

Usage

ddbs_geom_col(x)

Arguments

Value

Character string with geometry column name

Description

Functions to check various geometric properties and validity conditions of spatial geometries using DuckDB's spatial extension.

Usage

ddbs_is_simple(
  x,
  new_column = "is_simple",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_is_valid(
  x,
  new_column = "is_valid",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_is_closed(
  x,
  new_column = "is_closed",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_is_empty(
  x,
  new_column = "is_empty",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_is_ring(
  x,
  new_column = "is_ring",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

These functions provide different types of geometric validation. Note that by default, the functions add a new column as a logical vector. This behaviour allows to filter the data within DuckDB without the need or materializating a vector in R (see details).

• ddbs_is_valid() checks if a geometry is valid according to the OGC Simple Features specification. Invalid geometries may have issues like self-intersections in polygons, duplicate points, or incorrect ring orientations.

• ddbs_is_simple() determines whether geometries are simple, meaning they are free of self-intersections. For example, a linestring that crosses itself is not simple.

• ddbs_is_ring() checks if a linestring geometry is closed (first and last points are identical) and simple (no self-intersections), forming a valid ring.

• ddbs_is_empty() tests whether a geometry is empty, containing no points. Empty geometries are valid but represent the absence of spatial information.

• ddbs_is_closed() determines if a linestring geometry is closed, meaning the first and last coordinates are identical. Unlike ddbs_is_ring(), this does not check for simplicity.

Value

• mode = "duckspatial" (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• mode = "sf": An eagerly collected vector in R memory.

• When name is provided: writes the table in the DuckDB connection and returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)
library(dplyr)

## create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
)

rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson", 
  package = "duckspatial")
)

## geometry validation
ddbs_is_valid(countries_ddbs)
ddbs_is_simple(countries_ddbs)
ddbs_is_ring(rivers_ddbs)
ddbs_is_empty(countries_ddbs)
ddbs_is_closed(countries_ddbs)

## filter invalid countries
ddbs_is_valid(countries_ddbs) |> filter(!is_valid)

## End(Not run)

Description

Returns the type of each geometry (e.g., POINT, LINESTRING, POLYGON) in the input features.

Usage

ddbs_geometry_type(x, by_feature = TRUE, conn = NULL)

Arguments

Value

A factor with geometry type(s)

Examples

## Not run: 
## load package
library(duckspatial)

## read data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
)

# option 1: passing sf objects
# Get geometry type for each feature
ddbs_geometry_type(countries_ddbs)

# Get overall geometry type
ddbs_geometry_type(countries_ddbs, by_feature = FALSE)

## End(Not run)

Description

Prints a transposed table of the first rows of a DuckDB table, similarly as the S3 dplyr::glimpse method.

Usage

ddbs_glimpse(conn, name, quiet = FALSE)

Arguments

Value

Invisibly duckspatial_df object

Examples

## Not run: 
library(duckspatial)

# create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
argentina_sf <- ddbs_open_dataset(system.file("spatial/argentina.geojson", package = "duckspatial"))

## store in duckdb
ddbs_write_table(conn, argentina_sf, "argentina")

## glimpse the inserted table
ddbs_glimpse(conn, "argentina")

## End(Not run)

Description

Functions to check whether geometries have Z (elevation) or M (measure) dimensions

Usage

ddbs_has_z(
  x,
  by_feature = TRUE,
  new_column = "has_z",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_has_m(
  x,
  by_feature = TRUE,
  new_column = "has_m",
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

These functions check for additional coordinate dimensions beyond X and Y:

• ddbs_has_z() checks if a geometry has Z coordinates (elevation/altitude values). Geometries with Z dimension are often referred to as 3D geometries and have coordinates in the form (X, Y, Z).

• ddbs_has_m() checks if a geometry has M coordinates (measure values). The M dimension typically represents a measurement along the geometry, such as distance or time, and results in coordinates of the form (X, Y, M) or (X, Y, Z, M).

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load packages
library(dplyr)
library(duckspatial)

## create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
) |> 
  filter(ISO3_CODE != "ATA")

## check if it has Z or M
ddbs_has_m(countries_ddbs)
ddbs_has_z(countries_ddbs)

## End(Not run)

Description

Checks if a spatial extension is available, and installs it in a DuckDB database

Usage

ddbs_install(conn, upgrade = FALSE, quiet = FALSE, extension = "spatial")

Arguments

Value

TRUE (invisibly) for successful installation

Examples

## load packages
library(duckspatial)
library(duckdb)

# connect to in memory database
conn <- duckdb::dbConnect(duckdb::duckdb())

# install the spatial extension
ddbs_install(conn)

# install the h3 community extension
ddbs_install(conn, extension = "h3")

# disconnect from db
duckdb::dbDisconnect(conn)

Description

Transfers attribute data from a source spatial layer to a target spatial layer based on the area of overlap between their geometries. This function executes all spatial calculations within DuckDB, enabling efficient processing of large datasets without loading all geometries into R memory.

Usage

ddbs_interpolate_aw(
  target,
  source,
  tid,
  sid,
  extensive = NULL,
  intensive = NULL,
  weight = "sum",
  mode = NULL,
  keep_NA = TRUE,
  na.rm = FALSE,
  join_crs = NULL,
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

Areal-weighted interpolation is used when the source and target geometries are incongruent (they do not align). It relies on the assumption of uniform distribution: values in the source polygons are assumed to be spread evenly across the polygon's area.

Coordinate Systems: Area calculations are highly sensitive to the Coordinate Reference System (CRS). While the function can run on geographic coordinates (lon/lat), it is strongly recommended to use a projected CRS (e.g., EPSG:3857, UTM, or Albers) to ensure accurate area measurements. Use the join_crs argument to project data on-the-fly during the interpolation.

Extensive vs. Intensive Variables:

• Extensive variables are counts or absolute amounts (e.g., total population, number of voters). When a source polygon is split, the value is divided proportionally to the area.

• Intensive variables are ratios, rates, or densities (e.g., population density, cancer rates). When a source polygon is split, the value remains constant for each piece.

Mass Preservation (The weight argument): For extensive variables, the choice of weight determines the denominator used in calculations:

• "sum" (default): The denominator is the sum of all overlapping areas for that source feature. This preserves the "mass" of the variable relative to the target's coverage. If the target polygons do not completely cover a source polygon, some data is technically "lost" because it falls outside the target area. This matches areal::aw_interpolate(weight="sum").

• "total": The denominator is the full geometric area of the source feature. This assumes the source value is distributed over the entire source polygon. If the target covers only 50% of the source, only 50% of the value is transferred. This is strictly mass-preserving relative to the source. This matches sf::st_interpolate_aw(extensive=TRUE).

Note: Intensive variables are always calculated using the "sum" logic (averaging based on intersection areas) regardless of this parameter.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

References

Prener, C. and Revord, C. (2019). areal: An R package for areal weighted interpolation. Journal of Open Source Software, 4(37), 1221. Available at: doi:10.21105/joss.01221

See Also

areal::aw_interpolate() — reference implementation.

Examples

library(sf)

# 1. Prepare Data
# Load NC counties (Source) and project to Albers (EPSG:5070)
nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
nc <- st_transform(nc, 5070)
nc$sid <- seq_len(nrow(nc)) # Create Source ID

# Create a target grid
g <- st_make_grid(nc, n = c(10, 5))
g_sf <- st_as_sf(g)
g_sf$tid <- seq_len(nrow(g_sf)) # Create Target ID

# 2. Extensive Interpolation (Counts)
# Use weight = "total" for strict mass preservation (e.g., total births)
res_ext <- ddbs_interpolate_aw(
  target = g_sf, source = nc,
  tid = "tid", sid = "sid",
  extensive = "BIR74",
  weight = "total",
  mode = "sf"
)

# Check mass preservation
sum(res_ext$BIR74, na.rm = TRUE) / sum(nc$BIR74) # Should be ~1

# 3. Intensive Interpolation (Density/Rates)
# Calculates area-weighted average (e.g., assumption of uniform density)
res_int <- ddbs_interpolate_aw(
  target = g_sf, source = nc,
  tid = "tid", sid = "sid",
  intensive = "BIR74",
  mode = "sf"
)

# 4. Quick Visualization
par(mfrow = c(1, 2))
plot(res_ext["BIR74"], main = "Extensive (Total Count)", border = NA)
plot(res_int["BIR74"], main = "Intensive (Weighted Avg)", border = NA)

Description

Combines two sets of geometries based on spatial relationships, such as intersection or containment, attaching attributes from one set to the other.

Usage

ddbs_join(
  x,
  y,
  join = "intersects",
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  distance = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

Spatial Join Predicates:

A spatial predicate is really just a function that evaluates some spatial relation between two geometries and returns true or false, e.g., “does a contain b” or “is a within distance x of b”. Here is a quick overview of the most commonly used ones, taking two geometries a and b:

• "ST_Intersects": Whether a intersects b

• "ST_Contains": Whether a contains b

• "ST_ContainsProperly": Whether a contains b without b touching a's boundary

• "ST_Within": Whether a is within b

• "ST_Overlaps": Whether a overlaps b

• "ST_Touches": Whether a touches b

• "ST_Equals": Whether a is equal to b

• "ST_Crosses": Whether a crosses b

• "ST_Covers": Whether a covers b

• "ST_CoveredBy": Whether a is covered by b

• "ST_DWithin": x) Whether a is within distance x of b

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
# RECOMMENDED: Efficient lazy workflow using ddbs_open_dataset
library(duckspatial)

# Load data directly as lazy spatial data frames (CRS auto-detected)
countries <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", package = "duckspatial")
)

# Create random points
n <- 100
points <- data.frame(
    id = 1:n,
    x = runif(n, min = -180, max = 180),
    y = runif(n, min = -90, max = 90)
) |> 
  sf::st_as_sf(coords = c("x", "y"), crs = 4326) |>
  as_duckspatial_df()

# Lazy join - computation stays in DuckDB
result <- ddbs_join(points, countries, join = "within")

# Collect to sf when needed
result_sf <- dplyr::collect(result) |> sf::st_as_sf()
plot(result_sf["CNTR_NAME"])


# Alternative: using sf objects directly (legacy compatibility)
library(sf)

countries_sf <- sf::st_read(system.file("spatial/countries.geojson", package = "duckspatial"))

output <- duckspatial::ddbs_join(
    x = points,
    y = countries_sf,
    join = "within"
)


# Alternative: using table names in a duckdb connection
conn <- duckspatial::ddbs_create_conn()

ddbs_write_table(conn, points, "points", overwrite = TRUE)
ddbs_write_table(conn, countries_sf, "countries", overwrite = TRUE)

output2 <- ddbs_join(
    conn = conn,
    x = "points",
    y = "countries",
    join = "within"
)


## End(Not run)

Description

Returns either a single point at a specified position along a line, or multiple equally-spaced points along a line, depending on the value of intervals. When intervals = FALSE, this wraps ST_LineInterpolatePoint; when intervals = TRUE, it wraps ST_LineInterpolatePoints.

Usage

ddbs_line_interpolate(
  x,
  fraction = 0.5,
  intervals = FALSE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## return the midpoint of a line (default)
ddbs_line_interpolate(rivers_ddbs)

## return the point 25% along the line
ddbs_line_interpolate(rivers_ddbs, fraction = 0.25)

## return equally-spaced points every 10% of the line length
ddbs_line_interpolate(rivers_ddbs, fraction = 0.1, intervals = TRUE)

## return equally-spaced points every 50% of the line length (i.e. midpoint and end)
ddbs_line_interpolate(rivers_ddbs, fraction = 0.5, intervals = TRUE)

## End(Not run)

Description

Merges a collection of line geometries that share endpoints into a single LINESTRING, or MULTILINESTRING if endpoints are not shared

Usage

ddbs_line_merge(
  x,
  preserve = TRUE,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)
library(dplyr)

## read data
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## first, union by river name
rivers_union <- ddbs_union_agg(rivers_ddbs, by = "RIVER_NAME")

## merge lines, preserving direction
rivers_merged <- ddbs_line_merge(rivers_union)

## check Rio Eume (union doesn't guarantee the merging)
rivers_union |> filter(RIVER_NAME == "Rio Eume")
rivers_merged |> filter(RIVER_NAME == "Rio Eume")


## End(Not run)

Description

Returns the portion of a line between two fractional positions along its length

Usage

ddbs_line_substring(
  x,
  start = 0,
  end = 0.5,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## return the first half of each line (default)
ddbs_line_substring(rivers_ddbs)

## return the middle third of each line
ddbs_line_substring(rivers_ddbs, start = 0.33, end = 0.67)

## return the last quarter of each line
ddbs_line_substring(rivers_ddbs, start = 0.75, end = 1)

## End(Not run)

Description

Check tables and schemas inside a database

Usage

ddbs_list_tables(conn)

Arguments

Value

data.frame

Examples

## Not run: 
## load packages
library(duckspatial)

## create a duckdb database in memory (with spatial extension)
conn <- ddbs_create_conn(dbdir = "memory")

## read some data
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
)

argentina_ddbs <- ddbs_open_dataset(
  system.file("spatial/argentina.geojson", 
  package = "duckspatial")
)

## insert into the database
ddbs_write_table(conn, argentina_ddbs, "argentina")
ddbs_write_table(conn, countries_ddbs, "countries")

## list tables in the database
ddbs_list_tables(conn)

## End(Not run)

Description

Checks if a spatial extension is installed, and loads it in a DuckDB database

Usage

ddbs_load(conn, quiet = FALSE, extension = "spatial", create_macros = TRUE)

Arguments

Value

TRUE (invisibly) for successful installation

Examples

## Not run: 
## load packages
library(duckspatial)
library(duckdb)

## connect to in memory database
conn <- duckdb::dbConnect(duckdb::duckdb())

## install the spatial exntesion
ddbs_install(conn)
ddbs_load(conn)

## disconnect from db
duckdb::dbDisconnect(conn)

## End(Not run)

Description

Return the geometries at a specific M values or range of M values.

Usage

ddbs_locate_along(
  x,
  measure,
  offset = 0,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_locate_between(
  x,
  start_measure,
  end_measure,
  offset = 0,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

• ddbs_locate_along(): returns a point or multi-point, containing the point(s) at the geometry with the given measure

• ddbs_locate_between(): returns a geometry or geometry collection created by filtering and interpolating vertices within a range of "M" values

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data (must contain M-enabled linestring geometries)
rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson",
  package = "duckspatial")
)

## Calculate the length of the rivers
rivers_agg_ddbs <- rivers_ddbs |> 
  ddbs_union_agg("RIVER_NAME") |> 
  ddbs_length()

## Add M dimension to the rivers
rivers_m_ddbs <- rivers_agg_ddbs |> 
  ddbs_force_3d("length", dim = "M")

## Locate rivers with M between 10000 and 20000
ddbs_locate_between(rivers_m_ddbs, 10000, 20000)


## End(Not run)

Description

Creates a rectangular POLYGON geometry from four bounding coordinates.

Usage

ddbs_make_envelope(
  xmin,
  ymin,
  xmax,
  ymax,
  crs = "EPSG:4326",
  name = NULL,
  conn = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## without storing in duckdb
finland_bbox_ddbs <- ddbs_make_envelope(
  xmin = 19.1, ymin = 59.7,
  xmax = 31.6, ymax = 70.1
)

## End(Not run)

Description

Aggregates point geometries into a single LINESTRING by connecting them in their original order. Optionally, lines can be created per group using the by argument.

Usage

ddbs_make_line(
  x,
  by = NULL,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Details

Connects input POINT geometries into a LINESTRING in row order (row 1 → row 2 → …). To control the connection order, sort the data beforehand with dplyr::arrange().

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## load package
library(duckspatial)

## read data
points_ddbs <- ddbs_open_dataset(
  system.file("spatial/points.gpkg", package = "duckspatial")
)

## create a single line from all points
ddbs_make_line(points_ddbs)

## create lines grouped by a column
ddbs_make_line(points_ddbs, by = "type")

## return as sf object
ddbs_make_line(points_ddbs, by = "type", mode = "sf")

## screate lines groupping by 2 columns
ddbs_make_line(points_ddbs, by = c("type", "class"))

## End(Not run)

Description

Converts a single closed linestring geometry into a polygon. The linestring must be closed (first and last points identical). Does not work with MULTILINESTRING inputs - use ddbs_polygonize() or ddbs_build_area() instead.

Usage

ddbs_make_polygon(
  x,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A duckspatial_df (lazy spatial data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected object in R memory, that will return the same data type as the sf equivalent (e.g. sf or units vector).

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).