add_linear_penalties  R Documentation 
Add penalties to a conservation planning problem to penalize
solutions that select planning units with higher values from a specific
data source (e.g., anthropogenic impact). These penalties assume
a linear tradeoff between the penalty values and the primary
objective of the conservation planning problem (e.g.,
solution cost for minimum set problems; add_min_set_objective()
.
## S4 method for signature 'ConservationProblem,ANY,character'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,numeric'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,matrix'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,Matrix'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,Raster'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,SpatRaster'
add_linear_penalties(x, penalty, data)
## S4 method for signature 'ConservationProblem,ANY,dgCMatrix'
add_linear_penalties(x, penalty, data)
x 

penalty 

data 

This function penalizes solutions that have higher values according to the sum of the penalty values associated with each planning unit, weighted by status of each planning unit in the solution.
An updated problem()
object with the penalties added to it.
The argument to data
can be specified using the following formats.
data
as character
vectorcontaining column name(s) that
contain penalty values for planning units. This format is only
compatible if the planning units in the argument to x
are a
sf::sf()
or data.frame
object. The column(s) must have numeric
values, and must not contain any missing (NA
) values.
For problems that contain a single zone, the argument to data
must
contain a single column name. Otherwise, for problems that
contain multiple zones, the argument to data
must
contain a column name for each zone.
data
as a numeric
vectorcontaining values for
planning units. These values must not contain any missing
(NA
) values. Note that this format is only available
for planning units that contain a single zone.
data
as a matrix
/Matrix
objectcontaining numeric
values
that specify data for each planning unit.
Each row corresponds to a planning unit, each column corresponds to a
zone, and each cell indicates the data for penalizing a planning unit
when it is allocated to a given zone.
data
as a terra::rast()
objectcontaining values for planning
units. This format is only
compatible if the planning units in the argument to x
are
sf::sf()
, or terra::rast()
objects.
If the planning unit data are a sf::sf()
object,
then the values are calculated by overlaying the
planning units with the argument to data
and calculating the sum of the
values associated with each planning unit.
If the planning unit data are a terra::rast()
object, then the values
are calculated by extracting the cell
values (note that the planning unit data and the argument to data
must
have exactly the same dimensionality, extent, and missingness).
For problems involving multiple zones, the argument to data
must
contain a layer for each zone.
The linear penalties are implemented using the following
equations.
Let I
denote the set of planning units
(indexed by i
), Z
the set of management zones (indexed by
z
), and X_{iz}
the decision variable for allocating
planning unit i
to zone z
(e.g., with binary
values indicating if each planning unit is allocated or not). Also, let
P_z
represent the penalty scaling value for zones
z \in Z
(argument to penalty
), and
D_{iz}
the penalty data for allocating planning unit
i \in I
to zones z \in Z
(argument to
data
, if supplied as a matrix
object).
\sum_{i}^{I} \sum_{z}^{Z} P_z \times D_{iz} \times X_{iz}
Note that when the problem objective is to maximize some measure of
benefit and not minimize some measure of cost, the term P_z
is
replaced with P_z
.
See penalties for an overview of all functions for adding penalties.
Other penalties:
add_asym_connectivity_penalties()
,
add_boundary_penalties()
,
add_connectivity_penalties()
,
add_feature_weights()
## Not run:
# set seed for reproducibility
set.seed(600)
# load data
sim_pu_polygons < get_sim_pu_polygons()
sim_features < get_sim_features()
sim_zones_pu_raster < get_sim_zones_pu_raster()
sim_zones_features < get_sim_zones_features()
# add a column to contain the penalty data for each planning unit
# e.g., these values could indicate the level of habitat
sim_pu_polygons$penalty_data < runif(nrow(sim_pu_polygons))
# plot the penalty data to visualise its spatial distribution
plot(sim_pu_polygons[, "penalty_data"], axes = FALSE)
# create minimal problem with minimum set objective,
# this does not use the penalty data
p1 <
problem(sim_pu_polygons, sim_features, cost_column = "cost") %>%
add_min_set_objective() %>%
add_relative_targets(0.1) %>%
add_binary_decisions() %>%
add_default_solver(verbose = FALSE)
# print problem
print(p1)
# create an updated version of the previous problem,
# with the penalties added to it
p2 < p1 %>% add_linear_penalties(100, data = "penalty_data")
# print problem
print(p2)
# solve the two problems
s1 < solve(p1)
s2 < solve(p2)
# create a new object with both solutions
s3 < sf::st_sf(
tibble::tibble(
s1 = s1$solution_1,
s2 = s2$solution_1
),
geometry = sf::st_geometry(s1)
)
# plot the solutions and compare them,
# since we supplied a very high penalty value (i.e., 100), relative
# to the range of values in the penalty data and the objective function,
# the solution in s2 is very sensitive to values in the penalty data
plot(s3, axes = FALSE)
# for real conservation planning exercises,
# it would be worth exploring a range of penalty values (e.g., ranging
# from 1 to 100 increments of 5) to explore the tradeoffs
# now, let's examine a conservation planning exercise involving multiple
# management zones
# create targets for each feature within each zone,
# these targets indicate that each zone needs to represent 10% of the
# spatial distribution of each feature
targ < matrix(
0.1, ncol = number_of_zones(sim_zones_features),
nrow = number_of_features(sim_zones_features)
)
# create penalty data for allocating each planning unit to each zone,
# these data will be generated by simulating values
penalty_raster < simulate_cost(
sim_zones_pu_raster[[1]],
n = number_of_zones(sim_zones_features)
)
# plot the penalty data, each layer corresponds to a different zone
plot(penalty_raster, main = "penalty data", axes = FALSE)
# create a multizone problem with the minimum set objective
# and penalties for allocating planning units to each zone,
# with a penalty scaling factor of 1 for each zone
p4 <
problem(sim_zones_pu_raster, sim_zones_features) %>%
add_min_set_objective() %>%
add_relative_targets(targ) %>%
add_linear_penalties(c(1, 1, 1), penalty_raster) %>%
add_binary_decisions() %>%
add_default_solver(verbose = FALSE)
# print problem
print(p4)
# solve problem
s4 < solve(p4)
# plot solution
plot(category_layer(s4), main = "multizone solution", axes = FALSE)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.