Add objective: maximize signed effect

Maximize the total signed change generated by selected management actions relative to the reference scenario. Positive changes increase the objective; negative changes reduce it.

Usage

add_objective_max_effect(x, actions = NULL, features = NULL, alias = NULL)

Arguments

x: A Problem object.
actions: Optional subset of actions to include in the objective. Values may match x$data$actions$id and, if present, x$data$actions$action_set. If NULL, all actions are included.
features: Optional subset of features to include in the objective. Values may match x$data$features$id and, if present, x$data$features$name. If NULL, all features are included.
alias: Optional identifier used to register this objective for multi-objective workflows.

Value

An updated Problem object.

Details

Let $\Delta_{if}(x)$ be the signed change for planning unit $i$ and feature $f$, after combining selected individual actions and their interaction corrections. The objective is $$\max \sum_{i,f} \Delta_{if}(x).$$ For one action per unit this reduces to the sum of selected signed effects. With concurrent actions, supplied joint totals and inferred combinations are evaluated together; a negative interaction correction is not discarded.

The reference is the scenario supplied through dist_features, at the same horizon and in the same units as action outcomes. An unselected unit contributes zero change. Costs are not subtracted by this objective. A positive effect means an increase in the feature; select features for which an increase is desirable. Standardize incompatible units before aggregation, or register separate feature objectives using distinct aliases.

With actions, include only individual terms in that subset and joint corrections whose every member belongs to it. This is an accounting scope, not attribution of a cross-subset interaction to its individual members. With features, include only the selected features.

Changed behavior

This development version maximizes signed net change. Earlier versions maximized positive effects only. Models with negative effects or negative interaction corrections may therefore produce different solutions. The historical add_objective_max_benefit() name is deprecated in favor of add_objective_max_effect(). get_features() still reports positive gains separately in selected_benefit; the signed objective corresponds to selected_net when their scopes match.

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

Tallis, H., et al. (2021). Prioritizing actions: spatial action maps for conservation. Annals of the New York Academy of Sciences, 1505, 118–141. doi:10.1111/nyas.14651

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

Examples

# EXAMPLE: Maximise woodland gain in a fixed number of units
#
# The bundled landscape has spatially varying woodland reference
# amounts. Assume restoration increases these amounts by 50%.
# The absolute signed effect is therefore larger where the
# reference amount is greater.
sim <- load_sim_multiaction()

p <- create_problem(
  pu = sim$planning_units,
  features = sim$features,
  dist_features = sim$dist_features,
  cost = "cost"
) |>
  add_actions(data.frame(id = "restore"), cost = 1) |>
  add_effects(data.frame(
    action = "restore", feature = "woodland", relative_change = 0.50
  )) |>
  add_constraint_budget(12, "equal", include_pu_cost = FALSE) |>
  add_objective_max_effect(features = "woodland", alias = "woodland_gain")

# Every restoration costs one monetary unit, so exactly 12 units
# must be managed. The objective favours the largest woodland gains.
if (requireNamespace("rcbc", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  solutions <- solve(set_solver_cbc(p, time_limit = 30, verbose = FALSE))
  get_objectives(solutions, format = "wide")
  plot_spatial_actions(solutions, layout = "single")
}