add_constraint_targets_relative: Add relative targets

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

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

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