add_constraint_targets_absolute: Add absolute targets

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

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

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

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