add_objective_max_effect: Add objective: maximize signed effect

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

Add objective: maximize signed effect

Description

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.

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.

Value

An updated Problem object.

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. \Sexpr[results=rd]{tools:::Rd_expr_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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.ecolmodel.2019.108901")}

See Also

add_objective_min_effect, add_effects

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")
}

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