spatial_relations: Spatial relations infrastructure

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

Spatial relations infrastructure

Description

Define a unified internal representation for spatial relations between planning units and provide constructors for building such relations from common spatial inputs.

Spatial relations in multiscape are graph-like structures defined over the set of planning units. They are used to represent adjacency, shared boundary length, proximity, neighbourhood graphs, or other pairwise spatial relationships that may later be used by objectives, constraints, or diagnostics.

Relations are stored inside the Problem object as x$data$spatial_relations[[name]].

Details

Internal representation

Each spatial relation is stored as a data.frame containing, at a minimum, the columns:

internal_pu1

Integer index of the first planning unit.

internal_pu2

Integer index of the second planning unit.

weight

Non-negative edge weight. Its interpretation depends on the relation type.

Additional columns may also be present, such as pu1, pu2, distance, source, or other diagnostic fields. These extra columns are preserved when possible.

Thus, a spatial relation can be interpreted as a weighted graph G = (\mathcal{I}, E, \omega), where:

• \mathcal{I} is the set of planning units,

• E is the set of stored edges,

• \omega_{ij} \ge 0 is the weight associated with edge (i,j).

Directed and undirected relations

Some relation constructors create undirected relations by default. In that case, each unordered pair is typically stored once, usually with i < j, unless self-edges are explicitly allowed.

Boundary relations and diagonal terms

The function add_spatial_boundary supports boundary-length relations derived either from a boundary table or from polygon geometry.

If include_self = TRUE, diagonal entries (i,i) may be added to represent exposed boundary. These diagonal weights are intended for boundary-based compactness or fragmentation formulations, where perimeter exposed to the outside of the selected solution should contribute to the objective.

Geometry safety

All sf-based constructors operate only through spatial predicates, topological relations, or boundary-length calculations. They never subdivide, cut, or alter planning-unit geometries. Planning units are aligned to the internal planning-unit order before spatial relations are computed.

Available constructors

The following functions build and register spatial relations:

• add_spatial_relations: register a precomputed relation,

• add_spatial_boundary: shared boundary length relation,

• add_spatial_rook: rook adjacency from polygons,

• add_spatial_queen: queen adjacency from polygons,

• add_spatial_knn: k-nearest-neighbours graph from coordinates,

• add_spatial_distance: distance-threshold graph from coordinates.

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