add_spatial_boundary: Add spatial boundary-length relations

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

Add spatial boundary-length relations

Description

Build and register a boundary-length spatial relation between planning units.

Boundary relations represent shared edge length between adjacent polygons. In contrast to queen adjacency, they only account for boundary segments of positive length and ignore point-only contacts.

Usage

add_spatial_boundary(
  x,
  boundary = NULL,
  geometry = NULL,
  name = "boundary",
  weight_col = NULL,
  weight_multiplier = 1,
  include_self = TRUE,
  edge_factor = 1
)

Arguments

x	A Problem object.
boundary	Optional data.frame describing boundary lengths. Accepted formats are: (id1, id2, boundary), or (pu1, pu2, weight).
geometry	Optional sf object with planning-unit polygons and an id column. If NULL, x$data$pu_sf is used.
name	Character string giving the key under which the relation is stored.
weight_col	Optional character string giving the name of the weight column in boundary. If NULL, the function tries to infer it from "boundary" or "weight".
weight_multiplier	Positive numeric scalar applied to all boundary weights.
include_self	Logical. If TRUE, include diagonal entries representing exposed boundary.
edge_factor	Numeric scalar greater than or equal to zero. Multiplier applied to exposed boundary when constructing diagonal entries.

Details

Use this function when spatial structure should be represented through shared boundary length rather than binary contiguity or coordinate-based proximity.

Two input modes are supported:

1. Boundary-table mode. If boundary is supplied, it is interpreted as a boundary table, for example a Marxan-style bound.dat.

2. Geometry mode. If boundary = NULL, boundary lengths are derived from polygon geometry using geometry or x$data$pu_sf.

Let \omega_{ij} \ge 0 denote the shared boundary length between planning units i and j, multiplied by weight_multiplier.

For off-diagonal entries i \neq j, the stored weight is:

\omega_{ij} = \mathrm{\gamma} \times b_{ij},

where b_{ij} is the shared boundary length and \gamma is the user-supplied weight_multiplier.

If include_self = TRUE, diagonal entries are also created. These are not geometric self-neighbours in the graph sense; instead, they represent the effective boundary exposed to the outside of the solution.

Let p_i be the total perimeter of planning unit i, and let \sum_{j \neq i} \omega_{ij} be the total incident shared boundary recorded for that planning unit. Then the exposed boundary is represented by a diagonal term derived from the difference between total perimeter and shared boundary, scaled by edge_factor.

These diagonal terms are useful in boundary-based compactness or fragmentation objectives, because they encode the portion of each planning unit's perimeter that would remain exposed if the unit were selected.

Boundary-table mode

If boundary is provided, accepted formats are:

• (id1, id2, boundary), or

• (pu1, pu2, weight).

If the table contains diagonal rows (i,i), these are interpreted as total perimeter values in boundary-table mode.

Geometry mode

If boundary = NULL, shared boundary lengths are derived directly from polygon geometry. Only positive-length intersections are retained. Point touches are ignored.

Storage

The final relation is stored through add_spatial_relations, typically as an undirected relation with optional diagonal entries.

Value

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

See Also

add_spatial_relations, add_objective_min_fragmentation_pu, add_objective_min_fragmentation_action

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_boundary(
  x = p,
  name = "boundary",
  include_self = TRUE,
  edge_factor = 1
)

p$data$spatial_relations$boundary

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