add_spatial_relations: Add spatial relations

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

Add spatial relations

Description

Register an externally computed spatial relation inside a Problem object using the unified internal representation adopted by multiscape.

Most users will typically prefer one of the convenience constructors such as add_spatial_boundary, add_spatial_rook, add_spatial_queen, add_spatial_knn, or add_spatial_distance. This function is the advanced low-level entry point for adding an already computed relation.

Usage

add_spatial_relations(x, relations, name, directed = FALSE, allow_self = FALSE)

Arguments

x	A Problem object created with create_problem.
relations	A data.frame describing relation edges. It must contain either: pu1, pu2, and weight, using external planning-unit ids, or internal_pu1, internal_pu2, and weight, using internal planning-unit indices. Extra columns such as distance or source are allowed and are preserved when possible.
name	Character string giving the key under which the relation is stored.
directed	Logical. If FALSE, treat rows as undirected edges; each unordered pair must occur exactly once. If TRUE, keep rows as directed ordered pairs; reciprocal arcs are distinct, but duplicate arcs are rejected.
allow_self	Logical. If TRUE, allow diagonal entries (i,i). In fragmentation objectives, diagonal entries contribute as unary terms associated with the corresponding planning unit. Default is FALSE.

Details

Use this function when the spatial relation has already been computed externally and should be registered directly in the Problem object.

The input relation may be provided either in terms of external planning-unit identifiers or in terms of internal planning-unit indices.

Specifically, the input relations table must contain either:

• pu1, pu2, and weight, or

• internal_pu1, internal_pu2, and weight.

If external ids are supplied, they are mapped to internal indices using the planning-unit identifiers stored in the problem.

Let G = (\mathcal{I}, E, \omega) denote the supplied relation, where E corresponds to the rows of relations. If directed = FALSE, each edge is treated as undirected, so pairs (i,j) and (j,i) are interpreted as the same edge. In that case, each unordered pair must be supplied exactly once. Duplicate undirected edges are rejected, including reciprocal rows.

If directed = TRUE, edges are preserved as ordered pairs, so (i,j) and (j,i) are distinct unless the user provides both.

#' Self-edges (i,i) are permitted only if allow_self = TRUE. In fragmentation objectives, diagonal entries are interpreted as unary planning-unit terms \omega_{ii} x_i, including for directed relations; they are not interpreted as directed self-dependencies.

The final relation is stored in x$data$spatial_relations[[name]].

Calls accumulate relations with distinct names. If a relation with the same name already exists, an error is raised, including through spatial constructors. To change it, rebuild from the problem before it was added.

Value

An updated Problem object with the relation stored in x$data$spatial_relations[[name]].

See Also

add_spatial_boundary, add_spatial_rook, add_spatial_queen, add_spatial_knn, add_spatial_distance

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"
)

rel <- data.frame(
  pu1 = c(1, 1, 2),
  pu2 = c(2, 3, 3),
  weight = c(1, 1, 2)
)

p <- add_spatial_relations(
  x = p,
  relations = rel,
  name = "my_relation"
)

p$data$spatial_relations$my_relation

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