Package 'multiscape'

Add management actions to a planning problem

Description

Define the action catalogue, the set of feasible planning unit–action pairs, and their implementation costs.

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

Arguments

x	A Problem object created with create_problem.
actions	A data.frame defining the action catalogue. It must contain a unique id column. A column named action is also accepted and automatically renamed to id.
include_pairs	Optional specification of feasible (pu, action) pairs. It can be NULL, a data.frame with columns pu and action (optionally also feasible), or a named list whose names are action ids and whose elements are vectors of planning unit ids or sf objects.
exclude_pairs	Optional specification of infeasible (pu, action) pairs. It uses the same formats as include_pairs and removes matching pairs from the feasible set.
cost	Optional cost specification for feasible pairs. It may be NULL, a scalar numeric value, a named numeric vector indexed by action id, or a data.frame with columns action, cost or pu, action, cost.

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.

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.

In the spatial case, feasible planning units are identified using sf::st_intersects() against the stored planning-unit geometry.

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.

Replacement behaviour.

Calling add_actions() replaces any previous action catalogue and feasible action table stored in the problem object.

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, 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_constraint_locked_actions

Examples

# ------------------------------------------------------
# Minimal planning problem
# ------------------------------------------------------
pu <- data.frame(
  id = 1:4,
  cost = c(2, 3, 1, 4)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

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

p3$data$dist_actions

---

Add benefits

Description

Convenience wrapper around add_effects that keeps only positive effects, that is, rows with benefit > 0.

Usage

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

Arguments

x	A Problem object created with create_problem. It must already contain feasible actions; run add_actions first.
benefits	Alias of effects, kept for backwards compatibility.
effect_type	Character string indicating how supplied effect values are interpreted. Must be one of: "delta": values represent signed net changes, "after": values represent after-action amounts and are converted to net changes relative to baseline feature amounts.
effect_aggregation	Character string giving the aggregation used when converting raster values to planning-unit level. Must be one of "sum" or "mean".

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

---

Add area constraint

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

x	A Problem object.
area	Numeric scalar greater than or equal to zero. Target value for the constrained area.
sense	Character string indicating the type of area constraint. Must be one of "min", "max", or "equal".
tolerance	Numeric scalar greater than or equal to zero. Only used when sense = "equal". In that case, equality is interpreted as a band around area with half-width tolerance. Ignored otherwise.
area_col	Optional character string giving the name of the area column in x$data$pu. If NULL, the area source is resolved later by the model builder.
area_unit	Character string indicating the unit of area and tolerance. Must be one of "m2", "ha", or "km2".
actions	Optional subset of actions to which the constraint applies. If NULL, the constraint applies to the total selected area in the problem through the planning-unit selection variables. Otherwise, it applies to the selected decision variables associated with the specified subset of actions. This argument is resolved using the package's standard action subset parser.
name	Optional character string used as the label of the stored linear constraint when it is later added to the optimization model. If NULL, a default name is generated.

Details

Use this function when area requirements must be imposed either on the total selected landscape or on the subset of selected decisions associated with specific actions.

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.

When actions is not NULL, the constraint is applied only to the selected decisions associated with the specified subset of actions. Let $\mathcal{A}^\star \subseteq \mathcal{A}$ denote that 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}$. In that case, the constrained quantity is

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

Under formulations where at most one action can be selected per planning unit, this coincides with the area allocated to that subset of actions.

Areas are obtained from the planning-unit table. If area_col is provided, that column is used. Otherwise, the model builder later determines the default area source according to the internal rules of the package. The value of area_unit indicates the unit in which area and tolerance are expressed and therefore how the stored threshold should be interpreted.

This function only stores the constraint specification; it does not validate the feasibility of the threshold against the available planning units 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

Examples

pu <- data.frame(
  id = 1:4,
  cost = c(2, 3, 1, 4),
  area_ha = c(10, 15, 8, 20)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

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

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

p <- add_actions(
  p,
  actions = actions,
  cost = c(conservation = 1, restoration = 2)
)

p <- add_constraint_area(
  x = p,
  area = 25,
  sense = "min",
  area_col = "area_ha",
  area_unit = "ha"
)

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

p <- add_constraint_area(
  x = p,
  area = 5,
  sense = "min",
  area_col = "area_ha",
  area_unit = "ha",
  actions = "restoration"
)

p$data$constraints$area

---

Add budget constraint

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

x	A Problem object.
budget	Numeric scalar greater than or equal to zero. Target value for the constrained budget.
sense	Character string indicating the type of budget constraint. Must be one of "min", "max", or "equal".
tolerance	Numeric scalar greater than or equal to zero. Only used when sense = "equal". In that case, equality is interpreted as a band around budget with half-width tolerance. Ignored otherwise.
actions	Optional subset of actions to which the constraint applies. If NULL, the constraint applies to the whole problem. Otherwise, it applies only to the selected decision variables associated with the specified subset of actions. This argument is resolved using the package's standard action subset parser.
include_pu_cost	Logical scalar indicating whether planning-unit costs should be included in the constrained budget. This is only supported when actions = NULL.
include_action_cost	Logical scalar indicating whether action costs should be included in the constrained budget.
name	Optional character string used as the label of the stored linear constraint when it is later added to the optimization model. If NULL, a default name is generated.

Details

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

pu <- data.frame(
  id = 1:4,
  cost = c(2, 3, 1, 4)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

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

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

p <- add_actions(
  p,
  actions = actions,
  cost = c(conservation = 1, restoration = 2)
)

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 = "restoration",
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)

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

p$data$constraints$budget

---

Add locked action decisions to a planning problem

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

x	A Problem object with action feasibility already defined via add_actions.
locked_in	Optional specification of feasible (pu, action) pairs that must be selected. It may be NULL, a data.frame, or a named list.
locked_out	Optional specification of feasible (pu, action) pairs that must not be selected. It may be NULL, a data.frame, or a named list.

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

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

pu <- data.frame(
  id = 1:4,
  cost = c(2, 3, 1, 4)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

p <- add_actions(
  x = p,
  actions = data.frame(id = c("conservation", "restoration")),
  cost = c(conservation = 3, restoration = 8)
)

# Lock a few feasible decisions
p <- add_constraint_locked_actions(
  x = p,
  locked_in = data.frame(
    pu = c(1, 2),
    action = c("conservation", "restoration")
  ),
  locked_out = data.frame(
    pu = c(4),
    action = c("conservation")
  )
)

p$data$dist_actions

# Named-list interface
p2 <- add_constraint_locked_actions(
  x = p,
  locked_in = list(
    conservation = c(1, 3)
  ),
  locked_out = list(
    restoration = c(2)
  )
)

p2$data$dist_actions

---

Add locked planning units to a problem

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_pu(x, locked_in = NULL, locked_out = NULL)

Arguments

x	A Problem object created with create_problem.
locked_in	Optional locked-in specification. It may be NULL, a column name in the raw planning-unit data, a logical vector, or a vector of planning-unit ids.
locked_out	Optional locked-out specification. It may be NULL, a column name in the raw planning-unit data, a logical vector, or a vector of planning-unit ids.

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.

Replacement behaviour

Each call to add_constraint_locked_pu() replaces any existing locked_in and locked_out columns in the planning-unit table. In other words, the function defines the complete current set of locked planning units; it does not merge new values with previous ones.

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

Examples

pu <- data.frame(
  id = 1:5,
  cost = c(2, 3, 1, 4, 2),
  lock_col = c(TRUE, FALSE, FALSE, TRUE, FALSE),
  out_col = c(FALSE, FALSE, FALSE, FALSE, TRUE)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

# 1) Lock by planning-unit ids
p1 <- add_constraint_locked_pu(
  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 PU data columns
p2 <- add_constraint_locked_pu(
  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_pu(
  x = p,
  locked_in = c(TRUE, FALSE, TRUE, FALSE, FALSE),
  locked_out = c(FALSE, FALSE, FALSE, TRUE, FALSE)
)

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

---

Add absolute targets

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

x	A Problem object.
targets	Target specification. This is interpreted as an absolute target value in the same units as the modelled feature contributions. It may be a scalar, vector, named vector, or data.frame. See Details.
features	Optional feature specification indicating which features the supplied target values refer to when targets does not identify features explicitly. If NULL, all features are targeted.
actions	Optional character vector indicating which actions count toward target achievement. Entries may match action ids, action_set labels, or both. If NULL, all actions count.
label	Optional character string stored with the targets for reporting and bookkeeping.

Details

Use this function when target requirements are naturally expressed in the original units of the modelled feature contributions, rather than as proportions of current baseline 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$.

When the optimization model is built, each such target is interpreted as a lower-bound constraint 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$.

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

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)

feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)

dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(data.frame(id = "conservation", name = "conservation"), cost = 0)

# 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 = "conservation"
)
p3$data$targets

---

Add relative 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

x	A Problem object.
targets	Target specification as proportions in $[0,1]$. It may be a scalar, vector, named vector, or data.frame. See Details.
features	Optional feature specification indicating which features the supplied target values refer to when targets does not identify features explicitly. If NULL, all features are targeted.
actions	Optional character vector indicating which actions count toward target achievement. Entries may match action ids, action_set labels, or both. If NULL, all actions count.
label	Optional character string stored with the targets for reporting and bookkeeping.

Details

Use this function when target requirements are naturally expressed as proportions of current baseline 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 current baseline 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$.

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 current full landscape baseline.

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

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

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)

feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)

dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(data.frame(id = "conservation", name = "conservation"), cost = 0)

# 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 = "conservation"
)
p3$data$targets

---

Add action effects to a planning problem

Description

Define the effects of management actions on features across planning units.

Effects are stored in a canonical representation in an effects table, with one row per (pu, action, feature) triple and three main effect columns:

• amount_after: the feature amount expected after applying the action,

• benefit: the positive component of the net change,

• loss: the magnitude of the negative component of the net change.

Let $i$ index planning units, $a$ index actions, and $f$ index features. Let $b_{if}$ denote the baseline amount of feature $f$ in planning unit $i$, and let $\Delta_{iaf}$ denote the net effect of applying action $a$. The after-action amount is:

$\mathrm{amount\_after}_{iaf} = b_{if} + \Delta_{iaf}.$

Under the semantics adopted by this package, each (pu, action, feature) triple represents a single net effect. Consequently, after validation and aggregation, a stored row cannot have both benefit > 0 and loss > 0 at the same time.

Usage

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

Arguments

x	A Problem object created with create_problem. It must already contain feasible actions; run add_actions first.
effects	Effect specification. One of: NULL, to store an empty effects table, a data.frame(action, feature, multiplier), a data.frame(pu, action, feature, ...) with explicit effects, a named list of terra::SpatRaster objects, one per action.
effect_type	Character string indicating how supplied effect values are interpreted. Must be one of: "delta": values represent signed net changes, "after": values represent after-action amounts and are converted to net changes relative to baseline feature amounts.
effect_aggregation	Character string giving the aggregation used when converting raster values to planning-unit level. Must be one of "sum" or "mean".
component	Character string controlling which component of the canonical effects table is retained. Must be one of: "any": keep all stored effect rows, "benefit": keep only rows with benefit > 0, "loss": keep only rows with loss > 0.

Details

When to use add_effects().

Use this function when you want to specify what feasible actions do to features. It is the stage at which an action-based decision space is linked to feature-level ecological or functional consequences.

This function provides a unified interface for specifying action effects from several input formats while enforcing a single internal representation. Regardless of how the user supplies the effects, the stored output always follows the same canonical structure based on amount_after and non-negative benefit/loss components.

Let $i \in \mathcal{I}$ index planning units, $a \in \mathcal{A}$ index actions, and $f \in \mathcal{F}$ index features. Let $b_{if}$ denote the baseline amount of feature $f$ in planning unit $i$, as given by the feature-distribution table. Let $\Delta_{iaf}$ denote the net change caused by applying action $a$ in planning unit $i$ to feature $f$. The canonical stored representation is:

$\mathrm{amount\_after}_{iaf} = b_{if} + \Delta_{iaf},$

$\mathrm{benefit}_{iaf} = \max(\Delta_{iaf}, 0),$

$\mathrm{loss}_{iaf} = \max(-\Delta_{iaf}, 0).$

Hence:

• if $\Delta_{iaf} > 0$, then benefit > 0 and loss = 0,

• if $\Delta_{iaf} < 0$, then benefit = 0 and loss > 0,

• if $\Delta_{iaf} = 0$, then both are zero and amount_after equals the baseline amount.

Thus, benefit and loss describe the net change relative to the baseline, whereas amount_after describes the final feature amount under the action. This distinction is important for actions that maintain baseline values. For example, if an action preserves a feature unchanged, then benefit = 0, loss = 0, and amount_after equals the baseline amount.

Why split effects into benefit and loss?

This representation avoids ambiguity in downstream optimization models. It allows the package to support, for example, objectives that maximize beneficial effects, minimize damages, impose no-net-loss conditions, or combine both components differently in multi-objective formulations.

Supported effect specifications

The effects argument may be provided in one of the following forms:

1. NULL. An empty effects table is stored.

2. A data.frame(action, feature, multiplier). In this case, effects are constructed by multiplying baseline feature amounts by the supplied multiplier. The interpretation depends on effect_type.

   If effect_type = "delta", the multiplier represents a relative net change:

   $\Delta_{iaf} = b_{if} \times m_{af}.$

   If effect_type = "after", the multiplier represents the after-action amount relative to the baseline:

   $\mathrm{amount\_after}_{iaf} = b_{if} \times m_{af},$

   and the net effect is:

   $\Delta_{iaf} = \mathrm{amount\_after}_{iaf} - b_{if} = b_{if}(m_{af} - 1).$

   Thus, under effect_type = "after", a multiplier of 1 means no change, a multiplier below 1 means a loss, and a multiplier above 1 means a gain. This specification is expanded over all feasible (pu, action) pairs.

3. A data.frame(pu, action, feature, ...) giving explicit effects for individual triples. The table may contain:

   • delta or effect: interpreted as signed net changes,

   • after: interpreted as after-action amounts and requiring effect_type = "after",

   • benefit and/or loss: explicit non-negative split components,

   • legacy signed benefit without loss: interpreted as a signed net effect for backwards compatibility.

4. A named list of terra::SpatRaster objects, one per action. In this case, names must match action ids, and each raster must contain one layer per feature. Raster values are aggregated to planning-unit level using effect_aggregation.

Interpretation of effect_type

If effect_type = "delta", supplied values are interpreted as net changes directly. For explicit delta or effect columns, values are used as signed changes. For multiplier inputs, values are interpreted as relative net changes:

$\Delta_{iaf} = b_{if} \times m_{af}.$

If effect_type = "after", supplied values are interpreted as after-action amounts and converted internally to net effects using:

$\Delta_{iaf} = \mathrm{after}_{iaf} - b_{if}.$

For multiplier inputs under effect_type = "after", the after-action amount is computed as $b_{if} \times m_{af}$, so that:

$\Delta_{iaf} = b_{if}(m_{af} - 1).$

Missing baseline values are treated as zero.

Feasibility and locked-out decisions

Effects are only retained for feasible (pu, action) pairs. Thus, add_actions() must be called first. Pairs marked as locked out (status == 3) are removed before storing the final effects table.

This function does not define the action-decision layer itself; it builds on the feasible (pu, action) pairs already stored in the problem.

Duplicate rows and semantic validation

If multiple rows are supplied for the same (pu, action, feature) triple, they are aggregated by summing benefit and loss separately. The resulting triple must still respect the package semantics, namely that both components cannot be strictly positive simultaneously. Inputs violating this rule are rejected.

Component filtering

After canonicalization and validation, rows can be restricted to:

• component = "any": keep all stored effect rows, including neutral effects,

• component = "benefit": keep only rows with benefit > 0,

• component = "loss": keep only rows with loss > 0.

Zero-effect rows are retained by default because they may encode valid neutral effects. They are removed only when using component = "benefit" or component = "loss".

Raster handling

When effects are supplied as rasters, they are automatically aligned to the planning-unit raster or geometry when needed before extraction or zonal aggregation.

Stored output

The resulting effects table contains user-facing ids, internal integer ids, and optional labels for actions and features. Metadata describing the stored representation and input interpretation are written to an effects metadata field.

After defining effects, typical next steps include adding objectives that use beneficial or harmful effects, and then solving the configured problem.

Value

An updated Problem object containing:

dist_effects

A canonical effects table with columns pu, action, feature, amount_after, benefit, loss, internal_pu, internal_action, internal_feature, and optional labels such as feature_name and action_name.

effects_meta

Metadata describing how effects were interpreted and stored.

See Also

add_actions, add_benefits, add_losses

---

Add losses

Description

Convenience wrapper around add_effects that keeps only negative effects, represented by rows with loss > 0.

Usage

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

Arguments

x	A Problem object created with create_problem. It must already contain feasible actions; run add_actions first.
losses	Alias of effects, used for symmetry with add_benefits().
effect_type	Character string indicating how supplied effect values are interpreted. Must be one of: "delta": values represent signed net changes, "after": values represent after-action amounts and are converted to net changes relative to baseline feature amounts.
effect_aggregation	Character string giving the aggregation used when converting raster values to planning-unit level. Must be one of "sum" or "mean".

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

---

Add objective: maximize benefit

Description

Define an objective that maximizes the total positive effects generated by selected actions on selected features.

This objective is based on the canonical effects table and uses only the non-negative benefit component.

Usage

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

Arguments

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

Details

Use this function when positive ecological gains should be maximized explicitly, without offsetting them against harmful effects.

Let $b_{iaf} \ge 0$ denote the stored benefit associated with planning unit $i$, action $a$, and feature $f$. Since the effects table is already expressed in canonical form, $b_{iaf}$ represents the positive part of the net effect associated with the corresponding selected action decision.

If no subsets are supplied, the objective can be written as:

$\max \sum_{(i,a,f) \in \mathcal{R}} b_{iaf} \, x_{ia},$

where $\mathcal{R}$ denotes the set of stored benefit rows and $x_{ia} \in \{0,1\}$ indicates whether action $a$ is selected in planning unit $i$.

If actions is provided, only rows whose action belongs to the selected subset contribute to the objective.

If features is provided, only rows whose feature belongs to the selected subset contribute to the objective.

More generally, letting $\mathcal{R}^{\star}$ be the subset induced by the selected actions and features, the objective is:

$\max \sum_{(i,a,f) \in \mathcal{R}^{\star}} b_{iaf} \, x_{ia}.$

This objective maximizes gains only. It does not subtract losses. If harmful effects should also be accounted for, they must be handled separately through additional objectives or constraints.

Value

An updated Problem object.

See Also

add_objective_min_loss, add_effects

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)
effects_df <- data.frame(
  pu = c(1, 2, 3, 4, 1, 2, 3, 4),
  action = c("conservation", "conservation", "conservation", "conservation",
             "restoration", "restoration", "restoration", "restoration"),
  feature = c(1, 1, 1, 1, 2, 2, 2, 2),
  benefit = c(2, 1, 0, 1, 3, 0, 1, 2),
  loss = c(0, 0, 1, 0, 0, 1, 0, 0)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2)) |>
  add_effects(effects_df)

p1 <- add_objective_max_benefit(p)
p1$data$model_args

p2 <- add_objective_max_benefit(
  p,
  actions = "restoration"
)
p2$data$model_args

p3 <- add_objective_max_benefit(
  p,
  features = 1
)
p3$data$model_args

---

Add objective: maximize net profit

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

x	A Problem object.
profit_col	Character string giving the profit column in the stored profit table.
include_pu_cost	Logical. If TRUE, subtract planning-unit costs.
include_action_cost	Logical. If TRUE, subtract action costs.
actions	Optional subset of actions to include in the profit and action-cost terms. Values may match x$data$actions$id and, if present, x$data$actions$action_set.
alias	Optional identifier used to register this objective for multi-objective workflows.

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.

See Also

add_objective_max_profit, add_objective_min_cost

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)
profit_df <- data.frame(
  pu = c(1, 2, 3, 4, 1, 2, 3, 4),
  action = c("conservation", "conservation", "conservation", "conservation",
             "restoration", "restoration", "restoration", "restoration"),
  profit = c(5, 4, 3, 2, 8, 7, 6, 5)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2)) |>
  add_profit(profit_df)

p1 <- add_objective_max_net_profit(p)
p1$data$model_args

p2 <- add_objective_max_net_profit(
  p,
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)
p2$data$model_args

p3 <- add_objective_max_net_profit(
  p,
  actions = "restoration"
)
p3$data$model_args

---

Add objective: maximize profit

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

x	A Problem object.
profit_col	Character string giving the profit column in the stored profit table.
actions	Optional subset of actions to include. Values may match x$data$actions$id and, if present, x$data$actions$action_set. If NULL, all actions are included.
alias	Optional identifier used to register this objective for multi-objective workflows.

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.

See Also

add_objective_min_cost, add_objective_max_net_profit

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)
profit_df <- data.frame(
  pu = c(1, 2, 3, 4, 1, 2, 3, 4),
  action = c("conservation", "conservation", "conservation", "conservation",
             "restoration", "restoration", "restoration", "restoration"),
  profit = c(5, 4, 3, 2, 8, 7, 6, 5)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2)) |>
  add_profit(profit_df)

p1 <- add_objective_max_profit(p)
p1$data$model_args

p2 <- add_objective_max_profit(
  p,
  actions = "restoration"
)
p2$data$model_args

---

Add objective: minimize cost

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

x	A Problem object.
include_pu_cost	Logical. If TRUE, include planning-unit costs in the objective.
include_action_cost	Logical. If TRUE, include action costs in the objective.
actions	Optional subset of actions to include in the action-cost component. Values may match x$data$actions$id and, if present, x$data$actions$action_set. If NULL, all feasible actions are included in the action-cost term.
alias	Optional identifier used to register this objective for multi-objective workflows.

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.

See Also

add_objective_max_profit, add_objective_max_net_profit

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2))

p1 <- add_objective_min_cost(p)
p1$data$model_args

p2 <- add_objective_min_cost(
  p,
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)
p2$data$model_args

p3 <- add_objective_min_cost(
  p,
  actions = "restoration"
)
p3$data$model_args

---

Add objective: minimize action fragmentation

Description

Define an objective that minimizes fragmentation at the action level over a stored spatial relation.

Unlike add_objective_min_fragmentation_pu, which acts on the selected planning-unit set through $w_i$, this objective acts on the spatial arrangement of individual action decisions through the action variables $x_{ia}$.

Usage

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

Arguments

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

Details

Use this function when spatial cohesion should be encouraged separately for each selected action pattern.

Let $\mathcal{I}$ denote the set of planning units and let $\mathcal{A}$ denote the set of actions.

Let $x_{ia} \in \{0,1\}$ indicate whether action $a \in \mathcal{A}$ is selected in planning unit $i \in \mathcal{I}$.

Let the chosen spatial relation define weighted pairs with weights $\omega_{ij} \ge 0$, and let $\lambda =$ weight_multiplier be the global scaling factor applied to these weights.

If actions is supplied, only the selected subset $\mathcal{A}^{\star} \subseteq \mathcal{A}$ contributes to the final objective. If actions = NULL, all actions are included.

The internal preparation step constructs one auxiliary variable $b_{ija} \in [0,1]$ for each unique non-diagonal undirected edge $(i,j)$ with $i < j$ and for each action $a$. The intended semantics is:

$b_{ija} = x_{ia} \land x_{ja}.$

Whenever both decision variables $x_{ia}$ and $x_{ja}$ exist in the model, this conjunction is enforced by the linearization:

$b_{ija} \le x_{ia},$

$b_{ija} \le x_{ja},$

$b_{ija} \ge x_{ia} + x_{ja} - 1.$

If one of the two action variables does not exist because the corresponding (pu, action) pair is not feasible, the auxiliary variable is forced to zero.

Therefore, $b_{ija}=1$ if and only if action $a$ is selected in both adjacent planning units $i$ and $j$; otherwise $b_{ija}=0$.

The exact objective coefficients are assembled later by the model builder from:

• the action decision variables $x_{ia}$,

• the edge-conjunction variables $b_{ija}$,

• the relation weights $\omega_{ij}$,

• the multiplier $\lambda$,

• and, if supplied, the action-specific weights.

If action-specific weights are provided, let $\alpha_a \ge 0$ denote the weight associated with action $a$. Then the resulting objective can be interpreted as an action-wise compactness or fragmentation functional of the form:

$\min \sum_{a \in \mathcal{A}^{\star}} \alpha_a \, F_a(x_{\cdot a}, b_{\cdot\cdot a}; \lambda \omega),$

where $F_a$ is the fragmentation expression induced by the selected relation and the internal coefficient construction for action $a$.

In practical terms, this objective penalizes solutions in which the same action is spatially scattered or broken into separate patches, while allowing different actions to form different spatial patterns.

This differs from planning-unit fragmentation:

• add_objective_min_fragmentation_pu() encourages cohesion of the union of selected planning units,

• add_objective_min_fragmentation_action() encourages cohesion of each selected action pattern separately.

Setting weight_multiplier = 0 removes the contribution of the spatial relation from the objective after scaling.

Value

An updated Problem object.

See Also

add_objective_min_fragmentation_pu, add_spatial_boundary, add_spatial_relations

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)

feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)

dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)

actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)

bound_df <- data.frame(
  id1 = c(1, 1, 2, 1, 2, 3, 4),
  id2 = c(1, 2, 2, 3, 4, 4, 4),
  boundary = c(4, 1, 4, 1, 1, 1, 4)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2))

p <- add_spatial_boundary(
  x = p,
  boundary = bound_df,
  name = "boundary",
  include_self = TRUE,
  edge_factor = 1
)

p <- add_objective_min_fragmentation_action(
  p,
  relation_name = "boundary",
  actions = "restoration",
  weight_multiplier = 1
)

p$data$model_args

---

Add objective: minimize fragmentation

Description

Define an objective that minimizes planning-unit fragmentation over a stored spatial relation.

This objective acts on the planning-unit selection pattern through the binary planning-unit variables $w_i$. It is therefore appropriate when spatial cohesion is to be encouraged at the level of the selected planning-unit set as a whole.

Usage

add_objective_min_fragmentation_pu(
  x,
  relation_name = "boundary",
  weight_multiplier = 1,
  alias = NULL
)

Arguments

x	A Problem object.
relation_name	Character string giving the name of the spatial relation to use. The relation must already exist in x$data$spatial_relations.
weight_multiplier	Numeric scalar greater than or equal to zero. Global multiplier applied to the relation weights when the objective is built.
alias	Optional identifier used to register this objective for multi-objective workflows.

Details

Use this function when spatial cohesion should be encouraged at the level of the selected planning-unit set as a whole.

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

Let the chosen spatial relation define a set of weighted pairs with weights $\omega_{ij} \ge 0$. These relation weights are interpreted by the model builder after scaling by $\lambda =$ weight_multiplier.

The internal preparation step constructs one auxiliary variable $y_{ij} \in [0,1]$ for each unique non-diagonal undirected edge $(i,j)$ with $i < j$. The intended semantics is:

$y_{ij} = w_i \land w_j.$

This is enforced by the standard linearization:

$y_{ij} \le w_i,$

$y_{ij} \le w_j,$

$y_{ij} \ge w_i + w_j - 1.$

Thus, $y_{ij}=1$ if and only if both planning units $i$ and $j$ are selected, and $y_{ij}=0$ otherwise.

The exact objective coefficients are assembled later by the model builder from:

• the planning-unit variables $w_i$,

• the edge-conjunction variables $y_{ij}$,

• the stored relation weights $\omega_{ij}$,

• and the multiplier $\lambda$.

Conceptually, the resulting objective is a boundary- or relation-based compactness functional that penalizes exposed or weakly connected selected patterns while rewarding adjacency among selected planning units.

In the common case where relation_name = "boundary" and the relation was built with add_spatial_boundary, the objective corresponds to a boundary-length-style fragmentation penalty.

Setting weight_multiplier = 0 removes the contribution of the spatial relation from the objective after scaling.

This objective does not distinguish between different actions within the same planning unit. If action-specific spatial cohesion is required, use add_objective_min_fragmentation_action instead.

Value

An updated Problem object.

See Also

add_spatial_boundary, add_spatial_relations, add_objective_min_fragmentation_action

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)

feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)

dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)

actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)

bound_df <- data.frame(
  id1 = c(1, 1, 2, 1, 2, 3, 4),
  id2 = c(1, 2, 2, 3, 4, 4, 4),
  boundary = c(4, 1, 4, 1, 1, 1, 4)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2))

p <- add_spatial_boundary(
  x = p,
  boundary = bound_df,
  name = "boundary",
  include_self = TRUE,
  edge_factor = 1
)

p <- add_objective_min_fragmentation_pu(
  p,
  relation_name = "boundary"
)

p$data$model_args

---

Add objective: minimize intervention impact

Description

Define an objective that minimizes the impact associated with selecting planning units for intervention.

This objective uses planning-unit selection variables rather than summing the same impact repeatedly over multiple actions. As a result, each planning unit contributes at most once to the objective, regardless of how many feasible actions exist in that unit.

Usage

add_objective_min_intervention_impact(
  x,
  impact_col = "amount",
  features = NULL,
  actions = NULL,
  alias = NULL
)

Arguments

x	A Problem object.
impact_col	Character string giving the column in the feature-distribution table that contains the per-(pu, feature) impact amount. The default is "amount".
features	Optional subset of features to include. Values may match x$data$features$id and, if present, x$data$features$name.
actions	Optional subset of actions used to define the intervention context. Values may match x$data$actions$id and, if present, x$data$actions$action_set.
alias	Optional identifier used to register this objective for multi-objective workflows.

Details

Use this function when intervention itself has a baseline ecological, social, or operational burden that should be minimized independently of the detailed effects of particular actions.

Let $w_i \in \{0,1\}$ denote whether planning unit $i$ is selected for intervention. Let $q_{if}$ denote the impact amount associated with planning unit $i$ and feature $f$, taken from column impact_col in the feature-distribution table.

If all selected features are included, the objective can be interpreted as:

$\min \sum_{i \in \mathcal{I}} \left( \sum_{f \in \mathcal{F}^{\star}} q_{if} \right) w_i,$

where $\mathcal{F}^{\star}$ denotes the selected subset of features.

Thus, the coefficient attached to $w_i$ is the aggregated impact of the selected features in planning unit $i$.

The role of actions in this objective is not to make impact additive over actions, but to restrict the notion of intervention to planning units that are relevant for the selected subset of actions in downstream model construction. Even when multiple feasible actions exist in a planning unit, the planning unit contributes at most once through $w_i$.

This objective is useful when intervention itself has a baseline ecological, social, or operational impact that should be minimized independently of the detailed gain or loss generated by particular actions.

Value

An updated Problem object.

See Also

add_objective_max_benefit, add_objective_min_loss

Examples

pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2))

p1 <- add_objective_min_intervention_impact(p)
p1$data$model_args

p2 <- add_objective_min_intervention_impact(
  p,
  features = 1
)
p2$data$model_args

p3 <- add_objective_min_intervention_impact(
  p,
  actions = "restoration"
)
p3$data$model_args

---