Add objective: minimise action fragmentation

Encourage spatial cohesion separately for each selected action, rather than only for the union of managed planning units.

Usage

add_objective_min_fragmentation_action(
  x,
  relation_name = "boundary",
  weight_multiplier = 1,
  action_weights = NULL,
  actions = NULL,
  alias = NULL
)

Arguments

x: A Problem object.
relation_name: Character string giving the name of the spatial relation to use. The relation must already exist in x$data$spatial_relations.
weight_multiplier: Numeric scalar greater than or equal to zero. Global multiplier applied to the relation weights when the objective is built.
action_weights: Optional action weights. Either a named numeric vector with names equal to action ids, or a data.frame with columns action and weight. These weights scale the contribution of each action to the final objective.
actions: Optional subset of actions to include. Values may match x$data$actions$id and, if present, x$data$actions$action_set. If NULL, all actions are included.
alias: Optional identifier used to register this objective for multi-objective workflows.

Value

An updated Problem object.

Details

This objective uses the action-selection decisions $x_{ia}$ and a previously registered spatial relation. For neighbouring units $i$ and $j$, $b_{ija}=x_{ia} \land x_{ja}$ represents whether the same action $a$ occurs in both units. Adjacency of different actions does not form a continuous patch of either action.

For each action, the relation is restricted automatically to its feasible planning-unit/action pairs (as supplied through include_pairs and retained in the compiled model). An off-diagonal link contributes only if that action is feasible at both endpoints. A feasible but unselected action remains in this domain. No extra argument or correction objective is needed. Self-boundary weights contribute only where that action is feasible.

Use actions to select which action patterns contribute, action_weights to adjust their relative importance, and weight_multiplier to scale spatial relation weights.

Unlike add_objective_min_fragmentation_planning_units(), this objective distinguishes action identities. Combine it with coverage or allocation requirements so an empty plan is not optimal.

Repeated calls

With alias = NULL, one explicit single objective can be defined per problem; a second unaliased definition raises an error. With an alias, objectives accumulate under distinct names; a repeated alias raises an error. Aliased definitions preserve an explicitly configured single objective. To compare alternatives, start from the problem before its objective was added.

References

Salgado-Rojas, J., Álvarez-Miranda, E., Hermoso, V., Garcia-Gonzalo, J., and Weintraub, A. (2020). A mixed integer programming approach for multi-action planning for threat management. Ecological Modelling, 418, 108901. doi:10.1016/j.ecolmodel.2019.108901

Álvarez-Miranda, E., Salgado-Rojas, J., Hermoso, V., Garcia-Gonzalo, J., and Weintraub, A. (2020). An integer programming method for the design of multi-criteria multi-action conservation plans. Omega, 92, 102147. doi:10.1016/j.omega.2019.102147

Examples

# EXAMPLE: Form separate cohesive patches for two actions
#
# Each action costs one unit. Two action-specific budget equalities
# require exactly four protection and four restoration units.
# The default one-action-per-unit rule prevents overlapping actions.
sim <- load_sim_multiaction()
# Use a 4 by 4 subset so this example solves quickly.
planning_units <- subset(sim$planning_units, x < 4 & y < 4)
dist_features <- subset(sim$dist_features, pu %in% planning_units$id)

p <- create_problem(
  pu = planning_units,
  features = sim$features,
  dist_features = dist_features,
  cost = "cost"
) |>
  add_actions(sim$actions, cost = 1) |>
  add_spatial_boundary(name = "boundary", include_self = TRUE) |>
  add_constraint_budget(
    4, "equal", actions = "protect", include_pu_cost = FALSE
  ) |>
  add_constraint_budget(
    4, "equal", actions = "restore", include_pu_cost = FALSE
  ) |>
  add_objective_min_fragmentation_action(relation_name = "boundary", alias = "action_fragmentation")

# Unlike planning-unit fragmentation, this objective measures
# the cohesion of each action's selected units separately.
if (requireNamespace("rcbc", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  solutions <- solve(set_solver_cbc(p, gap_limit = 0, time_limit = 5, verbose = FALSE))
  get_objectives(solutions, format = "wide")
  plot_spatial_actions(solutions, layout = "single")
}