Package 'multiscape'

Description

Define named combinations of existing actions. An action can belong to more than one set. Sets are stored separately from the individual action catalog.

Usage

add_action_sets(x, sets)

Arguments

Details

Run add_actions() first. Supply either a named list of action-id vectors or a long table with one row per membership and columns set and action. Additional table columns are ignored. Each set must contain at least two distinct registered actions; duplicate memberships and nested sets are rejected. Members are matched by action id, not by their display name.

Set identifiers cannot coincide with action ids, action display names, or existing labels in actions$action_set. The latter column remains an independent, backward-compatible action classification.

Repeated calls add new sets. Reusing a registered set identifier is an error, including attempts to extend or redefine its membership. Definitions are returned in a consistent order by get_action_sets().

Registering a set does not create a selectable action, change feasible planning-unit/action pairs, require its members to be selected together, or add an interaction effect. It also does not enable simultaneous actions: the default maximum of one selected action per planning unit still applies unless changed with add_constraint_action_cardinality(). Sets may be registered even if their members have no common feasible unit. The modern add_effects() interface accepts these identifiers for supplied total joint effects. Objectives and constraints still receive individual members. Joint effects do not make a set a separate selectable action.

Value

A new Problem object containing the definitions. The input object is not modified. Any previously compiled model is invalidated, following the usual problem-construction workflow.

See Also

add_actions(), get_action_sets(), add_constraint_action_cardinality()

Examples

problem <- create_problem(
  pu = data.frame(id = 1:2, cost = c(1, 2)),
  features = data.frame(id = 1L, name = "woodland"),
  dist_features = data.frame(
    pu = 1:2, feature = 1L, amount = c(10, 20)
  )
) |>
  add_actions(
    actions = data.frame(id = c("restore", "control", "fence")),
    cost = 1
  )

# An action may belong to several sets.
list_problem <- problem |>
  add_action_sets(list(
    restore_control = c("restore", "control"),
    restore_fence = c("restore", "fence")
  ))
get_action_sets(list_problem)

# Equivalent definitions in long-table format.
memberships <- data.frame(
  set = c("restore_control", "restore_control", "restore_fence", "restore_fence"),
  action = c("restore", "control", "restore", "fence")
)
table_problem <- add_action_sets(problem, memberships)
identical(get_action_sets(list_problem), get_action_sets(table_problem))

# Add another set without changing existing definitions.
table_problem <- table_problem |>
  add_action_sets(list(control_fence = c("control", "fence")))
get_action_sets(table_problem)

Description

Define the action catalogue, the set of feasible planning unit–action pairs, their implementation costs, and the effective area represented by each feasible planning unit–action decision.

This function adds two core components to a Problem object. First, it stores the action catalogue. Second, it creates the feasible planning unit–action table, including implementation costs, effective action areas, status codes, and internal indices used by the optimization backend.

Conceptually, if $\mathcal{I}$ is the set of planning units and $\mathcal{A}$ is the set of actions, this function determines which pairs $(i,a) \in \mathcal{I} \times \mathcal{A}$ are feasible decisions and assigns a non-negative implementation cost to each feasible pair.

Usage

add_actions(
  x,
  actions,
  include_pairs = NULL,
  exclude_pairs = NULL,
  cost = NULL,
  action_area = NULL
)

Arguments

Details

When to use add_actions().

Use this function when you want to move from a planning problem defined only by planning units and features to a problem in which decisions are explicitly represented as actions applied in planning units.

Action catalogue.

The actions argument must be a data.frame with a unique id column identifying each action. If a column named action is supplied instead, it is renamed internally to id. Additional columns are preserved. If no name column is provided, action labels are taken from id. If an action_set column is present, it is also preserved and can later be used to refer to groups of actions. To register combinations with many-to-many membership, use add_action_sets after defining the individual actions. Existing definitions are validated whenever the action catalog is updated.

Actions are stored sorted by id to ensure reproducible internal indexing.

Feasible planning unit–action pairs.

Feasibility is controlled through include_pairs and exclude_pairs.

If include_pairs = NULL, all possible (pu, action) pairs are initially considered feasible, that is, all pairs $(i,a) \in \mathcal{I} \times \mathcal{A}$.

If include_pairs is supplied, only those pairs are retained. If exclude_pairs is also supplied, matching pairs are removed afterwards.

More precisely, let $\mathcal{D}^{\mathrm{inc}}$ denote the set of included planning unit–action pairs and let $\mathcal{D}^{\mathrm{exc}}$ denote the set of excluded pairs.

If include_pairs = NULL, the feasible decision set is:

$\{(i,a) : i \in \mathcal{I},\ a \in \mathcal{A}\} \setminus \mathcal{D}^{\mathrm{exc}}.$

If include_pairs is supplied, the feasible decision set is:

$\mathcal{D}^{\mathrm{inc}} \setminus \mathcal{D}^{\mathrm{exc}}.$

Both include_pairs and exclude_pairs can be specified as:

• NULL,

• a data.frame with columns pu and action,

• or a named list whose names are action ids.

When supplied as a data.frame, the object must contain columns pu and action. An optional logical-like column feasible may also be provided; only rows with feasible = TRUE are retained. Missing values in feasible are treated as FALSE.

When supplied as a named list, names must match action ids. Each element may contain either:

• a vector of planning-unit ids, or

• an sf object defining the spatial zone where the action is feasible.

Lists may mix vectors of planning-unit ids and sf objects across actions. In the spatial case, feasible planning units are identified using sf::st_intersects() against the stored planning-unit geometry. If include_pairs or exclude_pairs contains sf objects, the problem must contain planning-unit geometry in x$data$pu_sf; otherwise an error is raised.

Spatial exclusions are applied after inclusions. If a planning unit–action pair is included and excluded, the exclusion takes precedence and the pair is removed. Spatial exclusions remove complete (pu, action) pairs; they do not partially subtract area from included geometries.

Action areas.

The action_area column in dist_actions stores the effective area represented by each feasible (pu, action) decision. This is an area, not an action intensity.

If action_area = NULL, action areas are derived automatically:

• when include_pairs is supplied using sf objects, action areas are computed as the area of the spatial intersection between planning-unit geometries and the corresponding action geometries;

• when feasible pairs are supplied without spatial geometries, action areas default to the full planning-unit area when this can be derived from the problem object.

If action_area is supplied as a data.frame, it must contain columns pu, action, and action_area. A column named area is also accepted and renamed internally to action_area. Supplied areas must be finite and non-negative. User-supplied values override automatically derived values for matching feasible pairs. Rows referring to non-feasible pairs are ignored with a warning.

If full planning-unit areas cannot be derived for some feasible pairs, action_area is left as NA for those pairs. Area-based action constraints should check for missing action_area values before model construction.

Feasibility versus decision fixing.

This function only determines whether a pair $(i,a)$ exists in the model. It does not force a feasible action to be selected or forbidden beyond structural infeasibility. Fixed decisions should instead be imposed later with add_constraint_locked_actions.

Costs.

Costs can be supplied in several ways:

• If cost = NULL, all feasible pairs receive a default cost of 1.

• If cost is a scalar, that value is assigned to all feasible pairs.

• If cost is a named numeric vector, names must match action ids and costs are assigned by action.

• If cost is a data.frame, it must define either:

  • action-level costs through columns action and cost, or

  • pair-specific costs through columns pu, action, and cost.

In all cases, costs must be finite and non-negative.

In practice, a scalar cost is useful when all actions cost the same everywhere, a named vector is useful when cost depends only on action type, and a (pu, action, cost) table is useful when cost varies by both planning unit and action.

Status values.

Internally, all feasible pairs are initialized with status = 0, meaning that the decision is free. If planning units have already been marked as locked out, then all feasible actions in those planning units are assigned status = 3. This preserves consistency with planning-unit exclusions already stored in the problem.

Repeated calls.

The action catalogue and feasible pairs can be defined only once per problem. A second call raises an error, even if the input is identical. To compare action catalogues, build separate problems from the object before this call.

After defining actions, typical next steps include adding effects, optional decision-fixing constraints, objectives, and solver settings before calling solve().

Value

An updated Problem object with:

actions

The action catalogue, including a unique integer internal_id for each action.

dist_actions

The feasible planning unit–action table with columns pu, action, cost, action_area, status, internal_pu, and internal_action.

pu index

A mapping from user-supplied planning-unit ids to internal integer ids.

action index

A mapping from action ids to internal integer ids.

See Also

create_problem, add_action_sets, add_constraint_locked_actions

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

actions <- data.frame(
  id = c("conservation", "restoration"),
  name = c("Conservation", "Restoration")
)

# Example 1: all actions feasible in all planning units
p1 <- add_actions(
  x = p,
  actions = actions,
  cost = c(conservation = 5, restoration = 12)
)

print(p1)
utils::head(p1$data$dist_actions)

# Example 2: specify feasible pairs explicitly
include_df <- data.frame(
  pu = c(1, 2, 3, 4),
  action = c("conservation", "conservation", "restoration", "restoration")
)

p2 <- add_actions(
  x = p,
  actions = actions,
  include_pairs = include_df,
  cost = 10
)

p2$data$dist_actions

# Example 3: remove selected pairs after full expansion
exclude_df <- data.frame(
  pu = c(2, 4),
  action = c("restoration", "conservation")
)

p3 <- add_actions(
  x = p,
  actions = actions,
  exclude_pairs = exclude_df,
  cost = c(conservation = 3, restoration = 8)
)

utils::head(p3$data$dist_actions)

# Example 4: provide action-specific areas manually
action_area <- data.frame(
  pu = c(1, 2, 3, 4),
  action = c("conservation", "conservation", "restoration", "restoration"),
  action_area = c(100, 50, 80, 100)
)

p4 <- add_actions(
  x = p,
  actions = actions,
  include_pairs = include_df,
  action_area = action_area,
  cost = 10
)

p4$data$dist_actions

Description

Legacy convenience wrapper around add_effects that retains only positive signed changes (effect > 0). Positive change does not necessarily imply an ecological benefit. For new code, prefer add_effects() to retain signed effects of both directions. Effects can be defined only once per problem.

Usage

add_benefits(
  x,
  benefits = NULL,
  effect_type = c("delta", "after"),
  effect_aggregation = c("sum", "mean")
)

Arguments

Value

An updated Problem object containing:

dist_effects

The canonical filtered effects table, containing only rows with benefit > 0.

dist_benefit

A backwards-compatible mirror table containing only the benefit component.

See Also

add_effects, add_losses, add_objective_max_benefit

Description

Set a minimum, maximum, or exact number of management actions that can be selected in each planning unit. Rules can apply to all units, selected units, all actions, or a specified subset of actions.

Usage

add_constraint_action_cardinality(
  x,
  count,
  sense,
  actions = NULL,
  pu = NULL,
  name = NULL
)

Arguments

Details

How action cardinality works

A cardinality constraint limits the number of individual actions selected within each planning unit. For example, count = 2 and sense = "max" allow zero, one, or two actions per unit, whereas sense = "equal" requires exactly two. The available senses are:

• "max": select at most count actions.

• "min": select at least count actions.

• "equal": select exactly count actions.

The limit is evaluated separately for every unit covered by pu; it is not a total number of actions across the study area.

Default and overlapping rules

By default, at most one action can be selected per planning unit. To allow concurrent actions, specify a total maximum or exact-count rule with actions = NULL. That rule replaces the default one-action limit only in the planning units it covers. A minimum rule or a rule restricted to an action subset does not remove the default limit.

For example, to require at least two actions in a unit, first allow at least two with a total maximum, then add the minimum. Rules from different calls are enforced together; later rules do not overwrite earlier ones. Conflicting rules can make the problem infeasible.

Restricting the scope

Supply pu to restrict a rule to particular planning units and actions to count only specified actions. For example, a minimum of one action from c("restore", "control") requires at least one of those actions in every covered unit. Actions excluded by the subset are not counted towards that particular rule.

Cardinality counts individual selected actions, not the action sets registered with add_action_sets(). Registered sets describe joint effects when their member actions are selected; they are not additional selectable actions.

Feasibility and stored rules

Only available planning-unit/action pairs can be selected. A positive minimum or exact count larger than the number of available actions in a covered unit is rejected. Conflicts with other constraints may still be detected only when the problem is solved. Explicit rules are stored in x$data$constraints$action_cardinality and do not themselves select actions or run an optimisation solver.

Value

An updated Problem with an additional rule in x$data$constraints$action_cardinality. The input problem is preserved; no optimisation is performed.

See Also

add_actions, add_action_sets, add_constraint_budget

Examples

# EXAMPLE 1: Define the available decisions

# Consider three planning units, each with four possible actions.
# By default, the model allows at most one action in each unit.
# Registering actions does not select any of them.

problem <- create_problem(
  pu = data.frame(id = c(10L, 20L, 30L), cost = 1),
  features = data.frame(id = 1L, name = "woodland"),
  dist_features = data.frame(
    pu = c(10L, 20L, 30L), feature = 1L, amount = 10
  )
) |>
  add_actions(
    data.frame(id = c("restore", "control", "fence", "monitor")),
    cost = 1
  )

# EXAMPLE 2: Different capacities in different planning units

# Allow up to three actions in unit 10 and up to two in unit 20.
# Unit 30 retains the default maximum of one action.
# A maximum permits fewer actions, including no intervention.

capacities <- problem |>
  add_constraint_action_cardinality(
    count = 3, sense = "max", pu = 10L, name = "capacity_10"
  ) |>
  add_constraint_action_cardinality(
    count = 2, sense = "max", pu = 20L, name = "capacity_20"
  )

# Inspect the registered constraints, not solved decisions.
capacities$data$constraints$action_cardinality[
  , c("name", "count", "sense")
]

# EXAMPLE 3: Require at least one action from a subset

# In units 10 and 20, require restoration or control (or both).
# The minimum applies separately to each unit, and only these
# two actions count towards the requirement. The previously
# defined total capacities remain in force.

required <- capacities |>
  add_constraint_action_cardinality(
    count = 1, sense = "min",
    actions = c("restore", "control"),
    pu = c(10L, 20L), name = "management_required"
  )

# EXAMPLE 4: Require an exact count or prohibit interventions

# An exact count of two overrides the default one-action maximum
# in unit 10 and requires two distinct actions to be selected.

exact <- add_constraint_action_cardinality(
  problem, count = 2, sense = "equal", pu = 10L
)

# A zero maximum prohibits all actions in unit 30.
# It does not exclude that unit from the planning region.

no_action <- add_constraint_action_cardinality(
  problem, count = 0, sense = "max", pu = 30L
)

# EXAMPLE 5: Map where a more flexible capacity is allowed

# Use the bundled 64-unit landscape to impose a hypothetical
# policy allowing two concurrent actions in the eastern half.
# All other planning units retain the default maximum of one.
# No solver is needed to visualise the scope of the rule.

if (requireNamespace("sf", quietly = TRUE)) {
  sim <- load_sim_multiaction()
  spatial_problem <- create_problem(
    pu = sim$planning_units,
    features = sim$features,
    dist_features = sim$dist_features,
    cost = "cost"
  ) |>
    add_actions(sim$actions, cost = sim$action_costs)

  # Identify the eastern units using the x-coordinate of their
  # polygon centroids. The two-action limit is an upper bound,
  # not a requirement to select two actions.
  centres <- sf::st_coordinates(
    sf::st_centroid(sf::st_geometry(sim$planning_units))
  )
  east <- centres[, 1] > stats::median(centres[, 1])
  eastern_ids <- sim$planning_units$id[east]

  spatial_problem <- add_constraint_action_cardinality(
    spatial_problem, count = 2, sense = "max", pu = eastern_ids
  )

  # Display the geographical limits, not selected actions.
  capacity_map <- sim$planning_units
  capacity_map$max_actions <- ifelse(east, 2L, 1L)
  plot(capacity_map["max_actions"], main = "Maximum actions per unit")
}

Description

Prevent two or more incompatible actions from being selected together in the same planning unit. At most one action in the specified group may be selected; selecting none is also allowed.

Usage

add_constraint_action_excludes(x, actions, pu = NULL, name = NULL)

Arguments

Details

How the relation works

Suppose restoration and harvesting are incompatible uses of a site. This relation prevents their simultaneous selection without prohibiting either action individually. With three or more actions, every pair in the group is mutually exclusive, not just the complete combination.

For every scoped unit, the constraint is $\sum_{a \in A} x_{ia} \le 1$. Actions outside the group are not restricted by this relation. The rule is most informative when the cardinality settings otherwise permit more than one action per unit.

Value

A new Problem with the relation appended. The input problem is unchanged.

Scope and feasibility

Each relation applies separately within each unit specified by pu; pu = NULL applies it to all registered planning units. Relations do not select actions by themselves or make unavailable actions feasible. By default, at most one action can be selected per planning unit. Use add_constraint_action_cardinality() when a requires or together rule needs simultaneous selections. Unavailable or locked-out actions are treated as unselected: missing companions may prohibit a trigger, and a missing together member may prohibit the other members. Combined rules, budgets, and locks can also make a model infeasible.

Relations do not imply a temporal sequence or dependencies between different planning units. They can be combined with joint effects registered through add_action_sets(), but defining a joint effect does not itself require actions to be selected together.

Repeated calls

Distinct rules accumulate and are enforced simultaneously. Duplicate rules with the same type, action groups, sense, and PU scope are rejected; names must be unique across requires, excludes, and together relations. To revise a rule, start from the problem before that rule was added.

See Also

add_constraint_action_requires(), add_constraint_action_together(), add_constraint_action_cardinality()

Examples

# EXAMPLE 1: Allow multiple actions, but exclude an incompatible pair

# Up to three actions may be selected per unit. Restoration and harvesting
# are incompatible, while threat control can accompany either one.

base <- create_problem(
  pu = data.frame(id = 1:2, cost = 0),
  features = data.frame(id = 1L, name = "habitat"),
  dist_features = data.frame(pu = 1:2, feature = 1L, amount = 100)
) |>
  add_actions(
    data.frame(id = c("restore", "harvest", "control", "monitor")),
    cost = 1
  ) |>
  add_constraint_action_cardinality(3, "max")

exclusive <- add_constraint_action_excludes(
  base,
  actions = c("restore", "harvest"),
  name = "incompatible_uses"
)

# EXAMPLE 2: Restrict the rule to selected planning units

# In unit 1, choosing any one of restoration, harvesting, or control
# precludes the other two. The same rule is not imposed in unit 2.

local <- add_constraint_action_excludes(
  base,
  actions = c("restore", "harvest", "control"),
  pu = 1L,
  name = "local_exclusion"
)

# Inspect the stored relation, not a selected management plan.
local$data$constraints$action_relations[, c("type", "name")]

Description

Make the selection of one or more actions conditional on selecting companion actions in the same planning unit. With sense = "all", every companion is required; with sense = "any", at least one is required.

Usage

add_constraint_action_requires(
  x,
  actions,
  requires,
  sense = c("all", "any"),
  pu = NULL,
  name = NULL
)

Arguments

Details

How the relation works

Suppose restoration is effective only when threat control is also carried out. If restoration is selected, control must also be selected; if restoration is not selected, the relation imposes no requirement. With several triggering actions, each independently activates the requirement.

For binary action decisions $x_{ia}$, requiring all companions gives $x_{ia} \le x_{ib}$ for each required action $b$. Requiring any companion gives $x_{ia} \le \sum_b x_{ib}$. When there is only one companion, "all" and "any" are equivalent.

Value

A new Problem with the relation appended to x$data$constraints$action_relations. The input problem is unchanged.

Scope and feasibility

Each relation applies separately within each unit specified by pu; pu = NULL applies it to all registered planning units. Relations do not select actions by themselves or make unavailable actions feasible. By default, at most one action can be selected per planning unit. Use add_constraint_action_cardinality() when a requires or together rule needs simultaneous selections. Unavailable or locked-out actions are treated as unselected: missing companions may prohibit a trigger, and a missing together member may prohibit the other members. Combined rules, budgets, and locks can also make a model infeasible.

Relations do not imply a temporal sequence or dependencies between different planning units. They can be combined with joint effects registered through add_action_sets(), but defining a joint effect does not itself require actions to be selected together.

Repeated calls

Distinct rules accumulate and are enforced simultaneously. Duplicate rules with the same type, action groups, sense, and PU scope are rejected; names must be unique across requires, excludes, and together relations. To revise a rule, start from the problem before that rule was added.

See Also

add_constraint_action_excludes(), add_constraint_action_together(), add_constraint_action_cardinality(), add_action_sets()

Examples

# EXAMPLE 1: Create a problem where concurrent actions are possible

# Three planning units offer restoration, control, fencing, and monitoring.
# Allow up to three actions per unit: the default one-action maximum
# would otherwise prevent restoration and its companions being selected.

base <- create_problem(
  pu = data.frame(id = c(10L, 20L, 30L), cost = 0),
  features = data.frame(id = 1L, name = "habitat"),
  dist_features = data.frame(
    pu = c(10L, 20L, 30L), feature = 1L, amount = 100
  )
) |>
  add_actions(
    data.frame(id = c("restore", "control", "fence", "monitor")),
    cost = 1
  ) |>
  add_constraint_action_cardinality(3, "max")

# EXAMPLE 2: Require all companions in a specific unit

# In unit 10, restoration must be accompanied by both control and fencing.
# This is a conditional requirement: it does not force restoration.

required <- add_constraint_action_requires(
  base,
  actions = "restore",
  requires = c("control", "fence"),
  sense = "all",
  pu = 10L,
  name = "restore_with_both"
)

# EXAMPLE 3: Require at least one alternative companion

# In unit 20, either control OR fencing is sufficient for restoration.
# These rules have different PU scopes and can coexist.

required <- add_constraint_action_requires(
  required,
  actions = "restore",
  requires = c("control", "fence"),
  sense = "any",
  pu = 20L,
  name = "restore_with_either"
)

# EXAMPLE 4: Multiple independent triggers

# In unit 30, choosing either restoration or monitoring requires control.
# The triggers need not both be selected.

required <- add_constraint_action_requires(
  required,
  actions = c("restore", "monitor"),
  requires = "control",
  pu = 30L
)

# Inspect the three registered rules (not an optimised solution).
required$data$constraints$action_relations[, c("type", "sense", "name")]

# EXAMPLE 5: Map where a requirement applies (no solver needed)

if (requireNamespace("sf", quietly = TRUE)) {
  sim <- load_sim_multiaction()

  # Apply the restoration-protection requirement to the first 16 cells.
  # Both actions may be selected in these cells, so permit cardinality 2.
  scoped_pu <- head(sim$planning_units$id, 16)
  spatial <- create_problem(
    pu = sim$planning_units,
    features = sim$features,
    dist_features = sim$dist_features,
    cost = "cost"
  ) |>
    add_actions(sim$actions, cost = sim$action_costs) |>
    add_constraint_action_cardinality(2, "max", pu = scoped_pu) |>
    add_constraint_action_requires(
      "restore", "protect", pu = scoped_pu
    )

  # The map shows the SCOPE of the requirement, not selected actions.
  mapped <- sim$planning_units
  mapped$requirement <- ifelse(
    mapped$id %in% scoped_pu, "Applies", "Does not apply"
  )
  plot(mapped["requirement"], main = "Restoration requires protection")
}

Description

Link a group of actions so that, in each specified planning unit, either all are selected or none are selected.

Usage

add_constraint_action_together(x, actions, pu = NULL, name = NULL)

Arguments

Details

How the relation works

Suppose restoration and threat control must be implemented as one package. This relation requires both actions whenever either is selected. It does not require either action to be selected in the first place.

The binary decisions satisfy $x_{ia} = x_{ib}$ for all members of the group. Unlike add_constraint_action_requires(), dependency is bidirectional. Unlike add_constraint_action_excludes(), simultaneous selection is permitted and, when the group is used, required.

Cardinality must allow all members to be selected. Registering a set with add_action_sets() specifies a possible combination for joint effects; it does not itself impose the together relation.

Value

A new Problem with the relation appended. The input problem is unchanged.

Scope and feasibility

Each relation applies separately within each unit specified by pu; pu = NULL applies it to all registered planning units. Relations do not select actions by themselves or make unavailable actions feasible. By default, at most one action can be selected per planning unit. Use add_constraint_action_cardinality() when a requires or together rule needs simultaneous selections. Unavailable or locked-out actions are treated as unselected: missing companions may prohibit a trigger, and a missing together member may prohibit the other members. Combined rules, budgets, and locks can also make a model infeasible.

Relations do not imply a temporal sequence or dependencies between different planning units. They can be combined with joint effects registered through add_action_sets(), but defining a joint effect does not itself require actions to be selected together.

Repeated calls

Distinct rules accumulate and are enforced simultaneously. Duplicate rules with the same type, action groups, sense, and PU scope are rejected; names must be unique across requires, excludes, and together relations. To revise a rule, start from the problem before that rule was added.

See Also

add_constraint_action_requires(), add_constraint_action_excludes(), add_constraint_action_cardinality(), add_action_sets()

Examples

# EXAMPLE 1: Require restoration and control to occur together

# In planning unit 1, restoration and control must be selected together
# or both omitted. Monitoring remains independently selectable.
# Allow two simultaneous actions in unit 1; elsewhere the default
# maximum of one action still applies.

base <- create_problem(
  pu = data.frame(id = 1:2, cost = 0),
  features = data.frame(id = 1L, name = "habitat"),
  dist_features = data.frame(pu = 1:2, feature = 1L, amount = 100)
) |>
  add_actions(
    data.frame(id = c("restore", "control", "monitor")), cost = 1
  ) |>
  add_constraint_action_cardinality(2, "max", pu = 1L)

together <- add_constraint_action_together(
  base,
  actions = c("restore", "control"),
  pu = 1L,
  name = "restoration_package"
)

# Inspect the registered requirement; no solver has been run.
together$data$constraints$action_relations[, c("type", "name")]

# EXAMPLE 2: Extend the package to three actions

# All three must be selected or omitted as a group. The cardinality
# upper bound must now allow three actions in the scoped unit.

extended <- create_problem(
  pu = data.frame(id = 1L, cost = 0),
  features = data.frame(id = 1L, name = "habitat"),
  dist_features = data.frame(pu = 1L, feature = 1L, amount = 100)
) |>
  add_actions(
    data.frame(id = c("restore", "control", "monitor")), cost = 1
  ) |>
  add_constraint_action_cardinality(3, "max") |>
  add_constraint_action_together(c("restore", "control", "monitor"))

Description

Add an area constraint to a planning problem.

This function stores one area-constraint specification in the Problem object so that it can later be incorporated when the optimization model is assembled. Area constraints can be imposed either on the total selected planning-unit area or on the effective area of selected actions.

Multiple area constraints can be added by calling this function repeatedly, provided that no duplicated combination of action subset and constraint sense is introduced.

Usage

add_constraint_area(
  x,
  area,
  sense,
  tolerance = 0,
  area_col = NULL,
  area_unit = c("m2", "ha", "km2"),
  actions = NULL,
  name = NULL
)

Arguments

Details

Calls accumulate constraints for distinct action scopes, area measures (area_col), or senses. Repeating the same combination raises an error, even with a different threshold, display unit, or name. To change it, rebuild from the problem before the constraint was added. Explicit names must be unique within the area-constraint family; omitted names are generated automatically.

Use this function when area requirements must be imposed either on the total selected landscape or on the effective area allocated to specific actions.

Total selected area.

Let $\mathcal{I}$ denote the set of planning units and let $a_i \ge 0$ be the area associated with planning unit $i \in \mathcal{I}$.

When actions = NULL, the constraint refers to the total selected area in the problem. In that case, let $w_i \in \{0,1\}$ denote the binary variable indicating whether planning unit $i$ is selected by at least one decision in the model.

Depending on sense, this function stores one of the following constraints.

If sense = "min":

$\sum_{i \in \mathcal{I}} a_i w_i \ge A$

If sense = "max":

$\sum_{i \in \mathcal{I}} a_i w_i \le A$

If sense = "equal" and tolerance = 0:

$\sum_{i \in \mathcal{I}} a_i w_i = A$

If sense = "equal" and tolerance > 0, the equality is stored as a two-sided band:

$A - \tau \le \sum_{i \in \mathcal{I}} a_i w_i \le A + \tau$

where $\tau$ is the value supplied through tolerance.

Action-specific effective area.

When actions is not NULL, the constraint refers to the effective area of the selected decisions associated with the specified subset of actions.

Let $\mathcal{A}^\star \subseteq \mathcal{A}$ denote the specified action subset and let $x_{ia} \in \{0,1\}$ denote the binary variable indicating whether action $a \in \mathcal{A}^\star$ is selected in planning unit $i \in \mathcal{I}$. Let $b_{ia} \ge 0$ denote the effective action area associated with feasible pair $(i,a)$, as stored in x$data$dist_actions$action_area. In that case, the constrained quantity is:

$\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}^\star} b_{ia} x_{ia}.$

Effective action areas are defined in add_actions. They can be supplied manually through the action_area argument, derived from spatial include_pairs, or default to full planning-unit areas when these can be derived from the problem.

Consequently, if no partial action areas are supplied and each feasible action is assumed to apply to the full planning unit, then an action-specific area constraint is numerically equivalent to using planning-unit areas for those action decisions. If partial action areas are supplied, the constraint uses those effective areas instead.

Area units and area sources.

The value of area_unit indicates the unit in which area and tolerance are expressed.

When actions = NULL, areas are obtained from the planning-unit table or planning-unit geometry. If area_col is provided, that column is used. Otherwise, the model builder determines the default area source according to the internal rules of the package.

When actions is not NULL, the model builder uses x$data$dist_actions$action_area. These values are stored internally in square metres and are converted to area_unit when the model is built. If action areas are missing for relevant feasible (pu, action) pairs, the model builder may use area_col as a fallback to derive full planning-unit areas. If valid action areas still cannot be obtained, model construction fails with an error.

This function only stores the constraint specification; it does not validate the feasibility of the threshold against the available planning units or actions at this stage.

Multiple area constraints can be stored in a Problem object. However, at most one can be stored for the same combination of action subset and constraint sense. Attempting to add a duplicated actions–sense combination results in an error.

Value

An updated Problem object with the new area-constraint specification appended to x$data$constraints$area.

See Also

create_problem, add_actions

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"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  )

# Constrain the total selected planning-unit area.
p <- add_constraint_area(
  x = p,
  area = 25,
  sense = "min",
  area_unit = "ha"
)

# Constrain the effective area allocated to the restore action.
# Action areas are derived from the planning-unit geometries.

p <- add_constraint_area(
  x = p,
  area = 15,
  sense = "max",
  area_unit = "ha",
  actions = "restore"
)

p$data$constraints$area

Description

Add a budget constraint to a planning problem.

This function stores one budget-constraint specification in the Problem object so that it can later be incorporated when the optimization model is assembled. Multiple budget constraints can be added by calling this function repeatedly, provided that no duplicated combination of action subset and constraint sense is introduced.

Usage

add_constraint_budget(
  x,
  budget,
  sense,
  tolerance = 0,
  actions = NULL,
  include_pu_cost = TRUE,
  include_action_cost = TRUE,
  name = NULL
)

Arguments

Details

Calls accumulate constraints for distinct action scopes, cost components, or senses. Repeating the same combination raises an error, even with a different threshold or name. To change it, rebuild from the problem before the constraint was added. Explicit names must be unique within the budget-constraint family; omitted names are generated automatically.

Use this function when spending limits or minimum spending requirements must be imposed either on the full problem or on the subset of selected decisions associated with specific actions.

Let $\mathcal{I}$ denote the set of planning units and let $\mathcal{A}$ denote the set of actions. Let $w_i \in \{0,1\}$ denote the binary variable indicating whether planning unit $i \in \mathcal{I}$ is selected by at least one decision in the model, and let $x_{ia} \in \{0,1\}$ denote the binary variable indicating whether action $a \in \mathcal{A}$ is selected in planning unit $i \in \mathcal{I}$.

The total constrained budget can include two cost components:

• planning-unit costs, associated with $w_i$;

• action costs, associated with $x_{ia}$.

The arguments include_pu_cost and include_action_cost determine which of these components are included in the stored budget constraint.

When actions = NULL, the constraint refers to the total budget across the whole problem. In that case, depending on the values of include_pu_cost and include_action_cost, the constrained quantity is one of the following:

If only planning-unit costs are included:

$\sum_{i \in \mathcal{I}} c_i^{pu} w_i$

If only action costs are included:

$\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}} c_{ia}^{act} x_{ia}$

If both components are included:

$\sum_{i \in \mathcal{I}} c_i^{pu} w_i + \sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}} c_{ia}^{act} x_{ia}$

Depending on sense, this function stores one of the following constraints:

If sense = "min":

$C \ge B$

If sense = "max":

$C \le B$

If sense = "equal" and tolerance = 0:

$C = B$

If sense = "equal" and tolerance > 0, the equality is stored as a two-sided band:

$B - \tau \le C \le B + \tau$

where $C$ denotes the selected cost expression and $\tau$ is the value supplied through tolerance.

When actions is not NULL, only action costs can be included. In that case, let $\mathcal{A}^\star \subseteq \mathcal{A}$ denote the selected subset of actions, and the constrained quantity is

$\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}^\star} c_{ia}^{act} x_{ia}.$

Action-specific budget constraints only support action costs. Therefore, include_pu_cost = TRUE is only allowed when actions = NULL, because planning-unit costs are not action-specific.

This function only stores the constraint specification; it does not validate the feasibility of the threshold against the available cost data at this stage.

Multiple budget constraints can be stored in a Problem object. However, at most one can be stored for the same combination of action subset and constraint sense. Attempting to add a duplicated actions–sense combination results in an error.

Value

An updated Problem object with the new budget-constraint specification appended to the stored budget-constraint table.

See Also

create_problem

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"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  )

p <- add_constraint_budget(
  x = p,
  budget = 10,
  sense = "max",
  include_pu_cost = TRUE,
  include_action_cost = TRUE
)

p <- add_constraint_budget(
  x = p,
  budget = 4,
  sense = "max",
  actions = "restore",
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)

p <- add_constraint_budget(
  x = p,
  budget = 1,
  sense = "min",
  actions = "restore",
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)

p$data$constraints$budget

Description

Fix feasible planning unit–action decisions to be selected or excluded.

This function modifies the status of existing feasible (pu, action) pairs stored in the feasible action table. It does not create new feasible action pairs and therefore must be used only after add_actions has been called.

Usage

add_constraint_locked_actions(x, locked_in = NULL, locked_out = NULL)

Arguments

Details

Use this function when only specific feasible (pu, action) decisions must be forced in or out of the solution, rather than whole planning units.

Let $\mathcal{I}$ denote the set of planning units and $\mathcal{A}$ the set of actions. Let $\mathcal{D} \subseteq \mathcal{I} \times \mathcal{A}$ denote the set of feasible planning unit–action pairs already defined in the problem.

This function allows the user to define two subsets:

• $\mathcal{D}^{in} \subseteq \mathcal{D}$, the set of feasible pairs that must be selected,

• $\mathcal{D}^{out} \subseteq \mathcal{D}$, the set of feasible pairs that must not be selected.

These sets are encoded by updating the status column of the feasible action table. The function validates that all requested locked-in and locked-out pairs are already feasible. Therefore, it cannot be used to introduce new planning unit–action combinations into the problem.

In optimization terms, if $x_{ia}$ denotes the decision variable associated with planning unit $i$ and action $a$, then:

• locked-in pairs conceptually impose $x_{ia} = 1$,

• locked-out pairs conceptually impose $x_{ia} = 0$.

The exact translation into solver-side constraints occurs later when the model is built.

In contrast, add_constraint_locked_pu fixes whole planning units through the unit-selection variables, whereas this function fixes only specific feasible (pu, action) decisions.

Accepted formats

Both locked_in and locked_out accept the same formats:

• NULL,

• a data.frame with columns pu and action, optionally including a feasible column used as a filter,

• a named list whose names are action ids and whose elements are either vectors of planning unit ids or sf objects.

If a feasible column is supplied in a data.frame, only rows with feasible = TRUE are used. Missing values in feasible are treated as FALSE.

If an sf specification is supplied, the problem object must contain planning-unit geometry, and planning units are matched spatially using sf::st_intersects().

Conflict checking

Calls accumulate compatible locks and preserve omitted arguments. Repeating the same lock is idempotent. Changing an existing locked-in pair to locked-out, or vice versa, raises an error. To change a lock, rebuild from the problem before it was added.

A given (pu, action) pair cannot be simultaneously requested in both locked_in and locked_out. Such overlaps are rejected.

In addition, if a planning unit is already marked as locked out at the planning-unit level, then all feasible actions in that planning unit are forced to status = 3. Any attempt to lock in an action within such a planning unit raises an error.

Order of precedence

User-supplied locked-in and locked-out action requests are first applied to the feasible action table. Afterwards, any planning-unit-level locked_out flag is enforced, overriding action-level status and ensuring consistency with planning-unit exclusions.

Value

An updated Problem object in which the status column of the feasible action table has been modified to reflect locked-in and locked-out decisions.

See Also

add_actions, add_constraint_locked_pu

Examples

# Build a small spatial planning problem with two available actions.
sim <- load_sim_multiaction()
p <- create_problem(
  pu = sim$planning_units,
  features = sim$features,
  dist_features = sim$dist_features,
  cost = "cost"
) |>
  add_actions(sim$actions, cost = sim$action_costs)

# EXAMPLE 1: Fix individual planning-unit/action decisions.
# Protection must be selected in unit 1, restoration in unit 2,
# and protection cannot be selected in unit 4.
locked <- add_constraint_locked_actions(
  p,
  locked_in = data.frame(
    pu = c(1, 2), action = c("protect", "restore")
  ),
  locked_out = data.frame(pu = 4, action = "protect")
)

# Only show modified decisions: 2 = locked in, 3 = locked out.
# All remaining feasible decisions retain status 0 (free).
subset(locked$data$dist_actions, status %in% c(2L, 3L),
       select = c(pu, action, status))

# EXAMPLE 2: Specify the same locks using a named list.
# List names are action IDs; values are planning-unit IDs.
locked_list <- add_constraint_locked_actions(
  p,
  locked_in = list(protect = 1, restore = 2),
  locked_out = list(protect = 4)
)

# Both input formats lead to the same decision statuses.
identical(locked$data$dist_actions$status,
          locked_list$data$dist_actions$status)

Description

Define planning units that must be included in, or excluded from, the optimization problem.

This function updates the planning-unit table stored in the Problem object by creating or replacing the logical columns locked_in and locked_out. These columns are later used by the model builder when translating the problem into optimization constraints.

Lock information may be supplied either directly as logical vectors, as vectors of planning-unit ids, or by referencing columns in the raw planning-unit data originally passed to create_problem.

Usage

add_constraint_locked_planning_units(x, locked_in = NULL, locked_out = NULL)

Arguments

Details

Use this function when whole planning units must be forced into or out of the solution, regardless of which action may later be selected in them.

Let $\mathcal{I}$ denote the set of planning units and let $w_i \in \{0,1\}$ denote the binary variable indicating whether planning unit $i \in \mathcal{I}$ is selected by the model.

This function defines two subsets:

• $\mathcal{I}^{in} \subseteq \mathcal{I}$, the planning units that must be included,

• $\mathcal{I}^{out} \subseteq \mathcal{I}$, the planning units that must be excluded.

Conceptually, these sets correspond to the following conditions:

• if $i \in \mathcal{I}^{in}$, then $w_i = 1$,

• if $i \in \mathcal{I}^{out}$, then $w_i = 0$.

These constraints are not imposed immediately by this function; instead, they are stored in the planning-unit table and enforced later when building the optimization model.

Philosophy

The role of create_problem is to construct and normalize the basic inputs of the planning problem. Locking planning units is treated as a separate modelling step so that users can define or revise selection restrictions after the Problem object has already been created.

In contrast, add_constraint_locked_actions is used to fix specific feasible (pu, action) decisions rather than whole planning units.

Supported input formats

For both locked_in and locked_out, the function accepts:

• NULL, meaning that no planning units are locked on that side,

• a single character string, interpreted as a column name in the raw planning-unit data,

• a logical vector of length nrow(pu),

• a vector of planning-unit ids.

When a column name is supplied, the referenced column is coerced to logical. Numeric values are interpreted as non-zero = TRUE; character and factor values are interpreted using common logical strings such as "true", "t", "1", "yes", and "y". Missing values are treated as FALSE.

Repeated calls

Calls accumulate compatible locks and preserve omitted arguments. Repeating the same lock is idempotent. A planning unit cannot be locked in after it was locked out, or vice versa. Conflicts with existing action locks are also rejected. To change a lock, rebuild from the problem before it was added.

Consistency checks

The function checks that no planning unit is simultaneously assigned to both locked_in and locked_out. If such conflicts are found, an error is raised.

Value

An updated Problem object in which the planning-unit table contains logical columns locked_in and locked_out.

See Also

create_problem, add_actions, add_constraint_locked_actions, add_constraint_locked_pu

Examples

# Load a complete simulated planning problem.
example_data <- load_sim_multiaction()

pu <- example_data$planning_units
pu$lock_col <- pu$id %in% c(1, 4)
pu$out_col <- pu$id == 5

p <- create_problem(
  pu = pu,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
)

# 1) Lock by planning-unit ids
p1 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = c(1, 3),
  locked_out = c(5)
)

p1$data$pu[, c("id", "locked_in", "locked_out")]

# 2) Read lock information from raw planning-unit data columns
p2 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = "lock_col",
  locked_out = "out_col"
)

p2$data$pu[, c("id", "locked_in", "locked_out")]

# 3) Use logical vectors
p3 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = pu$id %in% c(1, 3),
  locked_out = pu$id == 4
)

p3$data$pu[, c("id", "locked_in", "locked_out")]

Description

add_constraint_locked_pu() has been replaced by add_constraint_locked_planning_units.

Usage

add_constraint_locked_pu(x, locked_in = NULL, locked_out = NULL)

Arguments

Value

An updated Problem object in which the planning-unit table contains logical columns locked_in and locked_out.

See Also

add_constraint_locked_planning_units

Description

Add feature-level absolute targets to a planning problem.

These targets are stored in the problem object and later translated into linear constraints when the optimization model is built. Absolute targets are interpreted directly in the same units as the feature contributions used by the model. Each call appends one or more target definitions to the problem. This makes it possible to combine multiple target rules, including targets associated with different action subsets.

Usage

add_constraint_targets_absolute(
  x,
  targets,
  features = NULL,
  actions = NULL,
  label = NULL
)

Arguments

Details

Calls accumulate targets for distinct feature/action scopes. A second target for the same feature and action scope raises an error immediately, even if it uses relative units or a different label. To change a target, rebuild from the problem before it was added.

Use this function when target requirements are naturally expressed in the original units of the modelled feature contributions, rather than as proportions of reference-scenario totals.

Let $\mathcal{F}$ denote the set of features. For each targeted feature $f \in \mathcal{F}$, this function stores an absolute target threshold $T_f \ge 0$.

With at most one action per unit, each target is interpreted as a lower-bound constraint on post-action amounts of the form:

$\sum_{(i,a) \in \mathcal{D}_f^{\star}} c_{iaf} x_{ia} \ge T_f,$

where:

• $i \in \mathcal{I}$ indexes planning units,

• $a \in \mathcal{A}$ indexes actions,

• $x_{ia}$ indicates whether action $a$ is selected in planning unit $i$,

• $c_{iaf}$ is the contribution of that action to feature $f$,

• $\mathcal{D}_f^{\star}$ is the subset of planning unit–action pairs allowed to count toward the target for feature $f$.

In the absolute case, the stored target threshold is simply:

$T_f = t_f,$

where $t_f$ is the user-supplied target value for feature $f$.

With concurrent actions, the model instead combines signed changes within each unit and feature and counts the reference once:

$\sum_i \left(r_{if} s_i^{\star} + \Delta_{if}^{\star}(x)\right) \ge T_f.$

Here $s_i^{\star}$ indicates that at least one action in the target scope is selected. Joint corrections contribute only when every member belongs to that scope. Individual effects are additive when no interaction is supplied. The same aggregation is used to report target achievement.

The actions argument restricts which actions may contribute toward achievement of the target, but it does not modify the value of $T_f$ itself.

The targets argument is parsed by .pa_parse_targets() and may be supplied in several equivalent forms, including:

• a single numeric value recycled to all selected features,

• a numeric vector aligned to features,

• a named numeric vector where names identify features,

• a data.frame with feature and target columns.

If targets does not explicitly identify features:

• if features = NULL, the target is applied to all features,

• if features is supplied, the target values are interpreted with respect to that feature set.

Repeated calls append new target rules rather than replacing previous ones. This allows cumulative target modelling, including multiple rules on the same feature with different contributing action subsets.

Value

An updated Problem object with absolute targets appended to the stored target table.

See Also

add_constraint_targets_relative

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"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  )

# Same absolute target for all features
p1 <- add_constraint_targets_absolute(p, 3)
p1$data$targets

# Different targets by feature
p2 <- add_constraint_targets_absolute(
  p,
  c("1" = 4, "2" = 2)
)
p2$data$targets

# Restrict which actions count toward target achievement
p3 <- add_constraint_targets_absolute(
  p,
  2,
  actions = "protect"
)
p3$data$targets

Description

Add feature-level relative targets to a planning problem.

These targets are stored in the problem object and later translated into linear constraints when the optimization model is built. Relative targets are supplied as proportions in $[0,1]$ and are converted internally into absolute thresholds using the current total amount of each feature in the landscape.

Each call appends one or more target definitions to the problem. This makes it possible to combine multiple target rules, including targets associated with different action subsets.

Usage

add_constraint_targets_relative(
  x,
  targets,
  features = NULL,
  actions = NULL,
  label = NULL
)

Arguments

Details

Use this function when target requirements are naturally expressed as proportions of reference-scenario feature totals rather than in original feature units.

Let $\mathcal{F}$ denote the set of features. For each targeted feature $f \in \mathcal{F}$, let $B_f$ denote the reference-scenario total amount of that feature in the landscape, as computed by .pa_feature_totals().

If the user supplies a relative target $r_f \in [0,1]$, then this function converts it to an absolute threshold:

$T_f = r_f \times B_f.$

The absolute threshold $T_f$ is stored in target_value, while:

• the original user-supplied proportion $r_f$ is stored in target_raw,

• the baseline total $B_f$ is stored in basis_total.

When the optimization model is built, the resulting target is interpreted as:

$\sum_{(i,a) \in \mathcal{D}_f^{\star}} c_{iaf} x_{ia} \ge T_f,$

where:

• $i \in \mathcal{I}$ indexes planning units,

• $a \in \mathcal{A}$ indexes actions,

• $x_{ia}$ indicates whether action $a$ is selected in planning unit $i$,

• $c_{iaf}$ is the contribution of that action to feature $f$,

• $\mathcal{D}_f^{\star}$ is the subset of planning unit–action pairs allowed to count toward the target for feature $f$.

With concurrent actions, the model instead combines signed changes within each unit and feature and counts the reference once:

$\sum_i \left(r_{if} s_i^{\star} + \Delta_{if}^{\star}(x)\right) \ge T_f.$

Here $s_i^{\star}$ indicates that at least one action in the target scope is selected. Joint corrections contribute only when every member belongs to that scope. Individual effects are additive when no interaction is supplied. The same aggregation is used to report target achievement.

The actions argument restricts which actions may contribute toward target achievement, but it does not affect the baseline amount $B_f$ used to compute the threshold. In other words, relative targets are always scaled against the full landscape reference scenario.

Therefore, actions changes who may satisfy the target, but not how the threshold itself is scaled.

The targets argument is parsed by .pa_parse_targets() and may be supplied in several equivalent forms, including:

• a single numeric value recycled to all selected features,

• a numeric vector aligned to features,

• a named numeric vector where names identify features,

• a data.frame with feature and target columns.

If targets does not explicitly identify features:

• if features = NULL, the target is applied to all features,

• if features is supplied, the target values are interpreted with respect to that feature set.

Relative targets must lie in $[0,1]$. A second target for the same feature and action scope raises an error, including when an absolute target already exists. Labels and threshold values do not change target identity.

Repeated calls append new target rules rather than replacing previous ones. This allows cumulative target modelling, including multiple rules on the same feature with different contributing action subsets.

Value

An updated Problem object with relative targets appended to the stored target table.

See Also

add_constraint_targets_absolute

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"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  )

# Require 30% of the baseline total for all features
p1 <- add_constraint_targets_relative(p, 0.3)
p1$data$targets

# Require 20% for one selected feature
p2 <- add_constraint_targets_relative(
  p,
  0.2,
  features = 1
)
p2$data$targets

# Restrict which actions count toward target achievement
p3 <- add_constraint_targets_relative(
  p,
  0.2,
  actions = "protect"
)
p3$data$targets

Description

Specify the expected consequences of feasible management actions for feature amounts in planning units, relative to a reference scenario.

Usage

add_effects(
  x,
  effects = NULL,
  effect_type = c("delta", "after"),
  effect_aggregation = c("sum", "mean"),
  component = c("any", "benefit", "loss"),
  raster_aggregation = c("sum", "mean"),
  raster_type = c("effect", "outcome")
)

Arguments

Details

Reference amounts, outcomes, and effects

The feature distribution supplied to create_problem() defines the reference amount $r_{if}$ of feature $f$ in planning unit $i$. This reference may describe current conditions, existing management, or a future without intervention. Let $y_{iaf}$ be the expected amount under action $a$. Its signed effect is $e_{iaf} = y_{iaf} - r_{if}$. These quantities describe what an action changes, not whether that change is desirable. For example, increasing habitat may be desirable, whereas decreasing fuel load may also be desirable. Objectives and constraints determine how consequences are valued in a planning problem.

Three alternative tabular inputs

Provide action, feature, optionally pu, and exactly one of the following numeric columns:

• effect: signed absolute change $e_{iaf}$.

• outcome: expected amount $y_{iaf}$ under the action.

• relative_change: proportional change $c_{iaf}$, with $y_{iaf} = r_{if}(1+c_{iaf})$ and $e_{iaf} = r_{if}c_{iaf}$.

For a reference amount of 100, effect = 30, outcome = 130, and relative_change = 0.30 are equivalent. Likewise, relative_change = -0.20 represents a 20 percent decrease. These input columns are alternatives, not values to supply together.

Actions must first be registered with add_actions(). With pu, effects can vary by location; without it, each action/feature specification is expanded over feasible planning-unit/action pairs. Locked-out pairs are excluded. A feature can be identified by name or numeric identifier. Values must be finite and non-missing; resulting outcomes must be non-negative. Reference amounts and outcomes must have compatible units and, when applicable, a common time horizon. Missing reference amounts are treated as zero: a relative change cannot create a positive outcome from a zero reference, so use effect or outcome in that case.

Stored representation

Regardless of the input format, dist_effects exposes reference_amount, action_outcome, and signed effect. For compatibility, it also retains amount_after (an alias of action_outcome) and columns named benefit and loss: these are strictly the positive and negative magnitudes of the signed change, $max(e,0)$ and $max(-e,0)$, not ecological judgements. A zero effect leaves the outcome equal to the reference amount.

Joint action effects

An action identifier may also refer to a set registered with add_action_sets(). Supply its total joint effect or outcome, not merely the interaction increment; individual and joint effects must be supplied in the same call. In the absence of a specified interaction, concurrent individual effects are treated as additive. Unspecified terms are assumed to be zero, which is a modelling assumption. Joint effects and signed interaction corrections are retained in separate internal tables; dist_effects represents individual actions. Cardinality constraints determine whether combinations may be selected.

Raster inputs

Supply a named list of terra::SpatRaster objects, one per action, each containing one layer per feature in feature-catalogue order. The problem must contain planning-unit polygons or a planning-unit raster. Use raster_type = "effect" for signed changes or raster_type = "outcome" for expected amounts, and choose raster_aggregation = "sum" or "mean" to aggregate values within planning units. Ensure the aggregated raster amounts are comparable with the reference; relative-change rasters are not accepted directly.

Single definition and compatibility

Effects can be specified only once per problem. To compare effect scenarios, create separate problems from a common object before calling add_effects(). Historical delta, after, multiplier, benefit, and loss inputs and explicit effect_type, effect_aggregation, and component arguments remain available with deprecation warnings. Use the three modern tabular columns for new code.

Value

An updated Problem containing dist_effects and effects_meta; the stored effect table includes reference amounts, action outcomes, signed effects, and compatibility columns.

See Also

add_actions, add_action_sets

Examples

# EXAMPLE 1: Equivalent ways to describe action effects
#
# Consider two planning units and two features: habitat and fuel load.
# The reference amounts represent their values before implementing
# any management action.
#
# In planning unit 1, habitat = 100 and fuel load = 60.
# In planning unit 2, habitat = 40 and fuel load = 20.

p <- create_problem(
  pu = data.frame(id = 1:2, cost = 0),
  features = data.frame(id = 1:2, name = c("habitat", "fuel")),
  dist_features = data.frame(
    pu = c(1, 1, 2, 2), feature = c(1, 2, 1, 2),
    amount = c(100, 60, 40, 20)
  )
) |>
  add_actions(actions = data.frame(id = "restore"))

# Suppose restoration increases habitat in planning unit 1
# from 100 to 130. This response can be described in three
# equivalent ways:
#
#   effect          = +30   (absolute increase)
#   outcome         = 130   (amount after restoration)
#   relative_change = 0.30  (30% increase)
#
# Each call starts from the same base problem because effects
# can only be defined once per problem.

p_effect <- add_effects(p, data.frame(
  pu = 1, action = "restore", feature = "habitat", effect = 30
))

p_outcome <- add_effects(p, data.frame(
  pu = 1, action = "restore", feature = "habitat", outcome = 130
))

p_relative <- add_effects(p, data.frame(
  pu = 1, action = "restore", feature = "habitat",
  relative_change = 0.30
))

# Regardless of the input specification, multiscape stores
# the reference amount, signed effect, and action outcome.

p_effect$data$dist_effects[, c(
  "reference_amount", "effect", "action_outcome"
)]


# EXAMPLE 2: Effects that apply across planning units
#
# The 'pu' column is optional. When omitted, the specified
# change is applied to every feasible planning unit for
# the corresponding action.
#
# Here, restoration increases habitat by 25% in both units.
# Because their reference amounts differ (100 and 40),
# the resulting absolute effects also differ (+25 and +10).

p_global <- add_effects(p, data.frame(
  action = "restore", feature = "habitat",
  relative_change = 0.25
))

# Inspect how the same proportional change produces
# different absolute effects across planning units.

p_global$data$dist_effects[, c(
  "pu", "reference_amount", "effect"
)]


# EXAMPLE 3: Positive and negative effects
#
# A management action may simultaneously increase some
# features and decrease others.
#
# Suppose restoration increases habitat from 100 to 130
# but reduces fuel load from 60 to 45 in planning unit 1.
#
# Both responses are represented as signed effects:
#
#   habitat: +30
#   fuel:    -15
#
# Importantly, the sign describes the direction of change,
# not whether that change is desirable. Increasing habitat
# and reducing fuel load may both support management goals.

p_mixed <- add_effects(p, data.frame(
  pu = 1, action = "restore",
  feature = c("habitat", "fuel"),
  effect = c(30, -15)
))

# Inspect the direction and magnitude of each response.

p_mixed$data$dist_effects[, c(
  "feature_name", "effect", "action_outcome"
)]


# EXAMPLE 4: Spatial variation in action outcomes
#
# Use the bundled 64-unit landscape to illustrate how
# reference amounts and action outcomes vary spatially.
# No optimisation or solver is required.
#
# The example applies a hypothetical 25% increase in the
# first feature under the first available action.

if (requireNamespace("sf", quietly = TRUE)) {

  # Load the spatial planning units, features, reference
  # distributions, and available management actions.

  sim <- load_sim_multiaction()

  spatial_problem <- create_problem(
    pu = sim$planning_units,
    features = sim$features,
    dist_features = sim$dist_features,
    cost = "cost"
  ) |>
    add_actions(sim$actions, cost = sim$action_costs)

  # Select one feature and one management action.

  f <- sim$features$name[1]
  a <- sim$actions$id[1]

  # Define a hypothetical 25% increase relative to the
  # reference amount in every feasible planning unit.
  # Because reference amounts vary spatially, so do the
  # resulting absolute effects and action outcomes.

  spatial_problem <- add_effects(
    spatial_problem,
    data.frame(
      action = a,
      feature = f,
      relative_change = 0.25
    )
  )

  # Extract the reference and expected outcome for the
  # selected feature-action combination.

  vals <- subset(
    spatial_problem$data$dist_effects,
    action == a & feature_name == f,
    select = c("pu", "reference_amount", "action_outcome")
  )

  # Attach these values to the planning-unit geometries
  # so they can be displayed as spatial maps.

  mapped <- merge(
    sim$planning_units, vals,
    by.x = "id", by.y = "pu", all.x = TRUE
  )

  # Compare reference amounts with potential outcomes.
  # These maps represent the consequences of implementing
  # the action, not an optimised selection of actions.

  plot(mapped[c("reference_amount", "action_outcome")])
}


# EXAMPLE 5: Joint effects of multiple actions
#
# When multiple actions can be implemented together,
# their combined effect need not equal the sum of their
# individual effects.
#
# Consider two actions, 'restore' and 'control'.
# Their individual effects on habitat are +30 and +20.
# However, implementing both together produces a total
# effect of +70 rather than +50.
#
# This implies an additional interaction of +20:
#
#   restore effect          = +30
#   control effect          = +20
#   additional interaction  = +20
#   joint total effect      = +70
#
# The joint effect is supplied as the TOTAL change,
# not merely the additional interaction.

joint_base <- create_problem(
  data.frame(id = 10L, cost = 0),
  data.frame(id = 1L, name = "habitat"),
  data.frame(pu = 10L, feature = 1L, amount = 100)
) |>
  add_actions(
    data.frame(id = c("restore", "control")),
    cost = 1
  ) |>
  add_action_sets(
    list(restore_control = c("restore", "control"))
  ) |>
  add_constraint_action_cardinality(2, "max")

# Supply individual and joint effects in the same call.
# The combined action changes habitat from 100 to 170.

joint <- add_effects(joint_base, data.frame(
  action = c("restore", "control", "restore_control"),
  feature = "habitat",
  effect = c(30, 20, 70)
))

# Inspect the decomposition into individual effects and
# the additional correction associated with joint selection.
# The joint row stores a correction of +20, ensuring that
# the combined total is +70 rather than +90.

joint$data$effect_terms[, c(
  "action", "total_effect", "effect"
)]

Description

Legacy convenience wrapper around add_effects that retains only negative signed changes (effect < 0). Negative change does not necessarily imply an ecological loss. For new code, prefer add_effects() to retain signed effects of both directions. Effects can be defined only once per problem.

Usage

add_losses(
  x,
  losses = NULL,
  effect_type = c("delta", "after"),
  effect_aggregation = c("sum", "mean")
)

Arguments

Value

An updated Problem object containing:

dist_effects

The canonical filtered effects table, containing only rows with loss > 0.

dist_loss

A convenience table containing only the loss component.

losses_meta

Metadata for the stored loss table.

See Also

add_effects, add_benefits, add_objective_min_loss

Description

Use add_objective_max_effect() for signed net effects.

Usage

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

Arguments

Value

An updated Problem object.

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

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. 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

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

Description

Define an objective that maximizes net profit by combining profits with optional planning-unit and action-cost penalties.

Usage

add_objective_max_net_profit(
  x,
  profit_col = "profit",
  include_pu_cost = TRUE,
  include_action_cost = TRUE,
  actions = NULL,
  alias = NULL
)

Arguments

Details

Use this function when decisions generate returns and the objective should optimize the resulting net balance after subtracting selected cost components.

Let:

• $x_{ia} \in \{0,1\}$ denote whether action $a$ is selected in planning unit $i$,

• $w_i \in \{0,1\}$ denote whether planning unit $i$ is selected,

• $\pi_{ia}$ denote the profit associated with decision $(i,a)$,

• $c_i^{PU} \ge 0$ denote the planning-unit cost,

• $c_{ia}^{A} \ge 0$ denote the action cost.

In its most general form, the objective is:

$\max \left( \sum_{(i,a) \in \mathcal{D}^{\star}} \pi_{ia} x_{ia} - \sum_{i \in \mathcal{I}} c_i^{PU} w_i - \sum_{(i,a) \in \mathcal{D}^{\star}} c_{ia}^{A} x_{ia} \right),$

where $\mathcal{D}^{\star}$ denotes the subset of feasible planning unit–action decisions included in the objective.

If actions = NULL, all feasible actions contribute to both the profit term and the action-cost term.

If actions is provided, the profit term and the action-cost term are restricted to that subset. The planning-unit cost term, if included, remains global.

If include_pu_cost = FALSE, the planning-unit cost term is omitted.

If include_action_cost = FALSE, the action-cost term is omitted.

Value

An updated Problem object.

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

Polasky, S., et al. (2008). Where to put things? Spatial land management to sustain biodiversity and economic returns. Biological Conservation, 141, 1505–1524. doi:10.1016/j.biocon.2008.03.022

Chan, K. M. A., Hoshizaki, L., and Klinkenberg, B. (2011). Ecosystem services in conservation planning: targeted benefits vs. co-benefits or costs? PLOS ONE, 6, e24378. doi:10.1371/journal.pone.0024378

See Also

add_objective_max_profit, add_objective_min_cost

Examples

# EXAMPLE: Maximise returns minus implementation costs
#
# Use the same west-to-east profit pattern as above, but now
# charge 9.5 monetary units for every selected action. Some
# locations may no longer generate a positive net return.
sim <- load_sim_multiaction()
returns <- sim$action_costs[, c("pu", "action")]
x_coord <- sim$planning_units$x[
  match(returns$pu, sim$planning_units$id)
]
returns$profit <- ifelse(
  returns$action == "protect", 12 - x_coord, 4 + x_coord
)

p <- create_problem(
  pu = sim$planning_units,
  features = sim$features,
  dist_features = sim$dist_features,
  cost = "cost"
) |>
  add_actions(sim$actions, cost = 9.5) |>
  add_profit(returns) |>
  add_objective_max_net_profit(include_pu_cost = FALSE, alias = "net_profit")

# Unlike gross profit maximisation, leaving a unit unmanaged
# can now be optimal when its best return is below its cost.
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")
}

Description

Define an objective that maximizes total profit from selected planning unit–action decisions.

Usage

add_objective_max_profit(
  x,
  profit_col = "profit",
  actions = NULL,
  alias = NULL
)

Arguments

Details

Use this function when the objective is to maximize gross economic return, without subtracting planning-unit or action costs.

Let $x_{ia} \in \{0,1\}$ denote whether action $a$ is selected in planning unit $i$, and let $\pi_{ia}$ denote the profit associated with that decision, as taken from column profit_col in the stored profit table.

If all actions are included, the objective is:

$\max \sum_{(i,a) \in \mathcal{D}} \pi_{ia} x_{ia},$

where $\mathcal{D}$ denotes the set of feasible planning unit–action decisions.

If actions is provided, only the selected subset contributes to the objective. Letting $\mathcal{D}^{\star}$ denote the feasible decisions whose action belongs to the selected subset, the objective becomes:

$\max \sum_{(i,a) \in \mathcal{D}^{\star}} \pi_{ia} x_{ia}.$

This objective considers profit only. It does not subtract planning-unit costs or action costs. For a net-profit formulation, use add_objective_max_net_profit.

Value

An updated Problem object.

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

Polasky, S., et al. (2008). Where to put things? Spatial land management to sustain biodiversity and economic returns. Biological Conservation, 141, 1505–1524. doi:10.1016/j.biocon.2008.03.022

See Also

add_objective_min_cost, add_objective_max_net_profit

Examples

# EXAMPLE: Maximise gross economic return across the landscape
#
# Assign hypothetical profits that favour protection in the west
# and restoration in the east. All values are positive.
sim <- load_sim_multiaction()
returns <- sim$action_costs[, c("pu", "action")]
x_coord <- sim$planning_units$x[
  match(returns$pu, sim$planning_units$id)
]
returns$profit <- ifelse(
  returns$action == "protect", 12 - x_coord, 4 + x_coord
)

p <- create_problem(
  pu = sim$planning_units,
  features = sim$features,
  dist_features = sim$dist_features,
  cost = "cost"
) |>
  add_actions(sim$actions, cost = 9.5) |>
  add_profit(returns) |>
  add_objective_max_profit(alias = "profit")

# Implementation costs are NOT deducted in this objective.
# With positive returns and at most one action per unit, the
# model chooses the more profitable action in each unit.
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")
}

Description

Define an objective that minimizes the total cost of the solution.

Depending on the function arguments, the objective may include planning-unit costs, action costs, or both. Action costs can optionally be restricted to a subset of actions.

Usage

add_objective_min_cost(
  x,
  include_pu_cost = TRUE,
  include_action_cost = TRUE,
  actions = NULL,
  alias = NULL
)

Arguments

Details

Use this function when the planning problem is framed primarily as a cost-minimization problem, with costs arising from planning-unit selection, action implementation, or both.

Let $\mathcal{I}$ be the set of planning units and let $\mathcal{D} \subseteq \mathcal{I} \times \mathcal{A}$ denote the set of feasible planning unit–action decisions.

Let:

• $w_i \in \{0,1\}$ denote whether planning unit $i$ is selected,

• $x_{ia} \in \{0,1\}$ denote whether action $a$ is selected in planning unit $i$,

• $c_i^{PU} \ge 0$ denote the planning-unit cost of unit $i$,

• $c_{ia}^{A} \ge 0$ denote the cost of selecting action $a$ in planning unit $i$.

The most general form of this objective is:

$\min \left( \sum_{i \in \mathcal{I}} c_i^{PU} w_i + \sum_{(i,a) \in \mathcal{D}^{\star}} c_{ia}^{A} x_{ia} \right),$

where $\mathcal{D}^{\star}$ denotes the subset of feasible decisions whose action contributes to the action-cost term.

If include_pu_cost = FALSE, the planning-unit cost term is omitted.

If include_action_cost = FALSE, the action-cost term is omitted.

If actions = NULL, all feasible actions contribute to the action-cost term. If actions is supplied, only the selected subset contributes to that term. Planning-unit costs are never subset by actions; they are always global whenever include_pu_cost = TRUE.

Value

An updated Problem object.

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

Ball, I. R., Possingham, H. P., and Watts, M. E. (2009). Marxan and relatives: software for spatial conservation prioritisation. In Spatial Conservation Prioritization: Quantitative Methods and Computational Tools, pp. 185–195. doi:10.1093/oso/9780199547760.003.0014

Salgado-Rojas, J., Hermoso, V., and Álvarez-Miranda, E. (2025). prioriactions: multi-action management planning in R. Methods in Ecology and Evolution, 16, 1028–1039. doi:10.1111/2041-210X.14220

See Also

add_objective_max_profit, add_objective_max_net_profit

Examples

# EXAMPLE: Minimum-cost management with a woodland target
#
# Use the 64 planning-unit landscape. The hypothetical outcome of 1
# credits one unit of woodland for either action in each selected unit.
# A target of 12 therefore requires at least 12 interventions.
sim <- load_sim_multiaction()

p <- create_problem(
  pu = sim$planning_units,
  features = sim$features,
  dist_features = sim$dist_features,
  cost = "cost"
) |>
  add_actions(sim$actions, cost = sim$action_costs) |>
  add_effects(data.frame(
    action = c("protect", "restore"),
    feature = "woodland", outcome = 1
  )) |>
  add_constraint_targets_absolute(12, features = "woodland") |>
  add_objective_min_cost(include_pu_cost = FALSE, alias = "cost")

# The solver selects the least costly set of actions that meets the target.
# This is a single-objective model: no set_method_*() call is needed.
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")
}

Description

Minimise total signed changes relative to the reference. Whether a decrease is desirable depends on the feature being optimised.

Usage

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

Arguments

Details

For the selected actions and features, this objective minimises $\sum_{i,f} \Delta_{if}(x)$, where $\Delta_{if}(x)$ is the signed change after accounting for joint effects. Increases and decreases can offset one another across units or features.

For instance, minimising signed fuel-load change favours reductions in fuel load. Specify a feature subset when features are measured in incompatible units. Unselected units contribute zero change, and implementation costs are not subtracted.

This differs from the deprecated add_objective_min_loss(), which penalises only the negative part of aggregated changes.

Value

An updated Problem object.

References

Related spatial fuel-management applications (not necessarily using the identical signed-effect objective) include:

Minas, J. P., Hearne, J. W., and Martell, D. L. (2014). A spatial optimisation model for multi-period landscape level fuel management to mitigate wildfire impacts. European Journal of Operational Research, 232, 412–422. doi:10.1016/j.ejor.2013.07.026

Williams, B. A., Shoo, L. P., Wilson, K. A., and Beyer, H. L. (2017). Optimising the spatial planning of prescribed burns to achieve multiple objectives in a fire-dependent ecosystem. Journal of Applied Ecology. doi:10.1111/1365-2664.12920

See Also

add_objective_max_effect(), add_objective_min_loss()

Examples

# EXAMPLE: Minimise the signed change in fuel load
#
# Use the geometry from the bundled 64-unit landscape, with a simple
# hypothetical fuel-load feature that increases from west to east.
# A 25% reduction has a NEGATIVE signed effect, so minimising the
# effect favours the units with the greatest fuel-load reduction.
sim <- load_sim_multiaction()

p <- create_problem(
  pu = sim$planning_units,
  features = data.frame(id = 1L, name = "fuel_load"),
  dist_features = data.frame(
    pu = sim$planning_units$id, feature = 1L,
    amount = 10 + sim$planning_units$x
  ),
  cost = "cost"
) |>
  add_actions(data.frame(id = "thin"), cost = 1) |>
  add_effects(data.frame(
    action = "thin", feature = "fuel_load", relative_change = -0.25
  )) |>
  add_constraint_budget(12, "equal", include_pu_cost = FALSE) |>
  add_objective_min_effect(features = "fuel_load", alias = "fuel_reduction")

# With one monetary unit per action, the budget equality selects
# exactly 12 units. Without it, this negative-effect objective
# could favour implementing the action everywhere.
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")
}

Description

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

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.

Value

An updated Problem object.

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

See Also

add_objective_min_fragmentation_planning_units, add_spatial_boundary, add_spatial_relations

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