Add absolute targets

Set targets expressed as the actual value of features in the study area that need to be represented in the prioritization. For instance, setting a target of 10 requires that the solution secure a set of planning units for which their summed feature values are equal to or greater than 10.

Usage

add_absolute_targets(x, targets)

# S4 method for ConservationProblem,numeric
add_absolute_targets(x, targets)

# S4 method for ConservationProblem,matrix
add_absolute_targets(x, targets)

# S4 method for ConservationProblem,character
add_absolute_targets(x, targets)

Arguments

x: problem() object.
targets: object that specifies the targets for each feature. See the Targets format section for more information.

Value

An updated problem() object with the targets added to it.

Details

Targets are used to specify the minimum amount or proportion of a feature's distribution that needs to be protected. Most conservation planning problems require targets with the exception of the maximum cover (see add_max_cover_objective()) and maximum utility (see add_max_utility_objective()) problems. Attempting to solve problems with objectives that require targets without specifying targets will throw an error.

For problems associated with multiple management zones, add_absolute_targets() can be used to set targets that each pertain to a single feature and a single zone. To set targets that can be met through allocating different planning units to multiple zones, see the add_manual_targets() function. An example of a target that could be met through allocations to multiple zones might be where each management zone is expected to result in a different amount of a feature and the target requires that the total amount of the feature in all zones must exceed a certain threshold. In other words, the target does not require that any single zone secure a specific amount of the feature, but the total amount held in all zones must secure a specific amount. Thus the target could, potentially, be met through allocating all planning units to any specific management zone, or through allocating the planning units to different combinations of management zones.

Targets format

The targets for a problem can be specified using the following formats.

targets as a numeric vector: containing target values for each feature. Additionally, for convenience, this format can be a single value to assign the same target to each feature. Note that this format cannot be used to specify targets for problems with multiple zones.
targets as a matrix object: containing a target for each feature in each zone. Here, each row corresponds to a different feature in argument to x, each column corresponds to a different zone in argument to x, and each cell contains the target value for a given feature that the solution needs to secure in a given zone.
targets as a character vector: containing the column name(s) in the feature data associated with the argument to x that contain targets. This format can only be used when the feature data associated with x is a sf::st_sf() or data.frame. For problems that contain a single zone, the argument to targets must contain a single column name. Otherwise, for problems that contain multiple zones, the argument to targets must contain a column name for each zone.

Examples

# \dontrun{
# set seed for reproducibility
set.seed(500)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with no targets
p0 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# create problem with targets to secure 3 amounts for each feature
p1 <- p0 %>% add_absolute_targets(3)

# create problem with varying targets for each feature
targets <- c(1, 2, 3, 2, 1)
p2 <- p0 %>% add_absolute_targets(targets)

# solve problem
s1 <- c(solve(p1), solve(p2))
names(s1) <- c("equal targets", "varying targets")

# plot solution
plot(s1, axes = FALSE)


# create a problem with multiple management zones
p3 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# create a problem with targets that specify an equal amount of each feature
# to be represented in each zone
p4_targets <- matrix(
  2,
  nrow = number_of_features(sim_zones_features),
  ncol = number_of_zones(sim_zones_features),
  dimnames = list(
    feature_names(sim_zones_features), zone_names(sim_zones_features)
  )
)
print(p4_targets)
#>           zone_1 zone_2 zone_3
#> feature_1      2      2      2
#> feature_2      2      2      2
#> feature_3      2      2      2
#> feature_4      2      2      2
#> feature_5      2      2      2

p4 <- p3 %>% add_absolute_targets(p4_targets)

# solve problem
s4 <- solve(p4)

# plot solution (pixel values correspond to zone identifiers)
plot(category_layer(s4), main = "equal targets", axes = FALSE)


# create a problem with targets that require a varying amount of each
# feature to be represented in each zone
p5_targets <- matrix(
  rpois(15, 1),
  nrow = number_of_features(sim_zones_features),
  ncol = number_of_zones(sim_zones_features),
  dimnames = list(
    feature_names(sim_zones_features),
    zone_names(sim_zones_features)
  )
)
print(p5_targets)
#>           zone_1 zone_2 zone_3
#> feature_1      2      0      0
#> feature_2      1      1      2
#> feature_3      3      3      2
#> feature_4      1      2      0
#> feature_5      2      1      1

p5 <- p3 %>% add_absolute_targets(p5_targets)

# solve problem
s5 <- solve(p5)

# plot solution (pixel values correspond to zone identifiers)
plot(category_layer(s5), main = "varying targets", axes = FALSE)

# }