Skip to contents

Create Neighbors Table

Source: R/neighbors_t.R
neighbors_t.Rd

Creates a neighbors_t table and validates that it matches the schema.

Usage

as_neighbors_t(x)

create_neighbors_t(
  coords_t,
  max_distance,
  distance_breaks = NULL,
  quiet = FALSE
)

# S3 method for class 'neighbors_t'
validate(x, ...)

# S3 method for class 'neighbors_t'
print(x, nrow = 10, ...)

set_neighbors(
  self,
  max_distance = 1000,
  distance_breaks = c(0, 100, 500, 1000),
  overwrite = FALSE,
  quiet = FALSE,
  chunksize = 1e+08
)

generate_neighbor_predictors(self)

upsert_new_neighbors(self, id_period)

Arguments

x

An object that can be passed to data.table::setDT()

coords_t

A coords_t object containing coordinate points with id_coord, lon, and lat columns, and appropriate metadata attributes (epsg, extent, resolution).

max_distance

Maximum distance to search for neighbors (in same units as coordinates)

distance_breaks

Optional numeric vector defining distance class boundaries. If NULL, no distance classification is performed. If provided, must have at least 2 elements defining interval breaks.

quiet

If TRUE, suppress progress messages during neighbor computation

...

Passed to data.table::print.data.table() resp. validate()

nrow

Maximum number of rows to print

self

An evoland_db object

overwrite

If FALSE and neighbors_t already exists, skip computation (default: FALSE)

chunksize

Number of rows to write per chunk when inserting into the database to avoid memory issues (default: 1e8)

id_period

Integer period ID for which to generate predictors; if missing, only use non-extrapolated periods

Value

A data.table of class "neighbors_t" with columns:

  • id_coord_origin: Foreign key to coords_t (origin coordinate)

  • id_coord_neighbor: Foreign key to coords_t (neighbor coordinate)

  • distance: Numeric distance between coordinates

  • distance_class: Optional factor representing distance intervals

A data.table with columns:

  • id_coord_origin: ID of the origin coordinate

  • id_coord_neighbor: ID of the neighboring coordinate

  • distance: Distance between origin and neighbor

  • distance_class: Factor indicating distance class (if distance_breaks provided)

Methods (by generic)

  • validate(neighbors_t): Validate a neighbors_t object

  • print(neighbors_t): Print a neighbors_t object

Functions

  • create_neighbors_t(): Compute neighboring coordinates within specified distances. This uses a spatial hash map for efficiency.

  • set_neighbors(): Compute neighbor relationships between coordinates and store in self$neighbors_t. This uses a spatial hash map for efficiency and can produce a very large table depending on max_distance.

  • generate_neighbor_predictors(): Generates neighbor predictors based on neighbor land use counts by distance class, e.g. "10 coordinate points within 200-500m are of class forest". This requires that neighbors_t, lulc_data_t, lulc_meta_t, and pred_meta_t are all present in the database. The generated predictors are stored in pred_data_t and metadata in pred_meta_t.

  • upsert_new_neighbors(): Append neighbor predictors for a specific period. This is used after extrapolating transition rates to new periods, so we can generate predictors for those periods. This requires that neighbors_t, lulc_data_t, lulc_meta_t, and pred_meta_t are all present in the database. pred_meta_t must have neighbor predictors already generated by generate_neighbor_predictors()