Skip to contents

Add spatial relations

Source: R/add_spatial_relations.R
add_spatial_relations.Rd

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.

Value

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

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]].

If a relation with the same name already exists, it is replaced.

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
#>   internal_pu1 internal_pu2 weight pu1 pu2 relation_name directed
#> 1            1            2      1   1   2   my_relation    FALSE
#> 2            1            3      1   1   3   my_relation    FALSE
#> 3            2            3      2   2   3   my_relation    FALSE