add_spatial_distance: Add distance-threshold spatial relations

In multiscape: Multi-Action, Multi-Objective Spatial Planning

Add distance-threshold spatial relations

Description

Build and register a spatial relation connecting planning units whose Euclidean distance is less than or equal to a user-defined threshold.

This constructor does not require polygon geometry and instead uses planning-unit coordinates.

Usage

add_spatial_distance(
  x,
  coords = NULL,
  max_distance,
  name = "distance",
  weight_mode = c("constant", "inverse", "inverse_sq"),
  distance_eps = 1e-09
)

Arguments

x	A Problem object created with create_problem.
coords	Optional coordinates specification, following the same rules as in add_spatial_knn.
max_distance	Positive numeric scalar giving the maximum distance for an edge.
name	Character string giving the key under which the relation is stored.
weight_mode	Character string indicating how distance is converted to weight. Must be one of "constant", "inverse", or "inverse_sq".
distance_eps	Small positive numeric constant used to avoid division by zero in inverse-distance weighting.

Details

Use this function when neighbourhood should be defined by a fixed distance radius rather than by polygon topology or a fixed number of neighbours.

Let s_i = (x_i, y_i) denote the coordinates of planning unit i. Let d_{ij} be the Euclidean distance between planning units i and j.

For a user-supplied threshold d_{\max}, this constructor creates an edge between i and j whenever:

d_{ij} \le d_{\max}.

Edge weights are assigned according to weight_mode:

• "constant":

  \omega_{ij} = 1,

• "inverse":

  \omega_{ij} = \frac{1}{\max(d_{ij}, \varepsilon)},

• "inverse_sq":

  \omega_{ij} = \frac{1}{\max(d_{ij}, \varepsilon)^2},

where \varepsilon = distance_eps is a small constant.

The implementation computes an O(n^2) distance matrix and is therefore best suited to small or moderate numbers of planning units. For large problems, add_spatial_knn is often more scalable.

The resulting relation is registered as undirected.

Value

An updated Problem object.

See Also

add_spatial_knn, add_spatial_relations

Examples

# Load a complete simulated planning problem.
example_data <- load_sim_multiaction()

p <- create_problem(
  pu = example_data$planning_units,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
)

p <- add_spatial_distance(
  x = p,
  max_distance = 1.01,
  name = "within_1",
  weight_mode = "constant"
)

p$data$spatial_relations$within_1

multiscape documentation built on Oct. 12, 2026, 5:08 p.m.