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)

# 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+07
)

generate_neighbor_predictors(self)

upsert_new_neighbors(self, id_period)

Arguments

x

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

...

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

nrow

Maximum number of rows to print

self

An evoland_db object

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.

overwrite

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

quiet

If TRUE, suppress progress messages during neighbor computation

chunksize

Number of neighbour pairs per chunk; bounds the memory used while computing and committing (default: 1e7, a few hundred MB)

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

Methods (by generic)

  • validate(neighbors_t): Validate a neighbors_t object

  • print(neighbors_t): Print a neighbors_t object

Functions

  • 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. The table is never held in memory as a whole: the neighbourhoods are computed and committed in chunks of complete neighbourhoods (all neighbours of a set of origins), inside one transaction.

  • 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()