Evaluate solution importance using replacement cost scores
Source:R/eval_replacement_importance.R
eval_replacement_importance.RdCalculate importance scores for planning units selected in a solution based on the replacement cost method (Cabeza and Moilanen 2006).
eval_replacement_importance(x, solution, ...) # S4 method for ConservationProblem,numeric eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...) # S4 method for ConservationProblem,matrix eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...) # S4 method for ConservationProblem,data.frame eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...) # S4 method for ConservationProblem,Spatial eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...) # S4 method for ConservationProblem,sf eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...) # S4 method for ConservationProblem,Raster eval_replacement_importance(x, solution, rescale, run_checks, force, threads, ...)
Arguments
| x |
|
|---|---|
| solution |
|
| ... | not used. |
| rescale |
|
| run_checks |
|
| force |
|
| threads |
|
Value
A numeric, matrix, data.frame
RasterLayer, Spatial,
or sf::sf() object containing the importance scores for each planning
unit in the solution. Specifically, the returned object is in the
same format as the planning unit data in the argument to x.
Details
This function implements a modified version of the
replacement cost method (Cabeza and Moilanen 2006).
Specifically, the score for each planning unit is calculated
as the difference in the objective value of a solution when each planning
unit is locked out and the optimization processes rerun with all other
selected planning units locked in. In other words, the replacement cost
metric corresponds to change in solution quality incurred if a given
planning unit cannot be acquired when implementing the solution and the
next best planning unit (or set of planning units) will need to be
considered instead. Thus planning units with a higher score are more
important (and irreplaceable).
For example, when using the minimum set objective function
(add_min_set_objective()), the replacement cost scores
correspond to the additional costs needed to meet targets when each
planning unit is locked out. When using the maximum utility
objective function (add_max_utility_objective(), the
replacement cost scores correspond to the reduction in the utility when
each planning unit is locked out. Infinite values mean that no feasible
solution exists when planning units are locked out---they are
absolutely essential for obtaining a solution (e.g. they contain rare
species that are not found in any other planning units or were locked in).
Zeros values mean that planning units can swapped with other planning units
and this will have no effect on the performance of the solution at all
(e.g. because they were only selected due to spatial fragmentation
penalties).
These calculations can take a long time to complete for large
or complex conservation planning problems. As such, we using this
method for small or moderate-sized conservation planning problems
(e.g. < 30,000 planning units). To reduce run time, we
recommend calculating these scores without additional penalties (e.g.
add_boundary_penalties()]) or spatial constraints (e.g.
link{add_contiguity_constraints}). To further reduce run time,
we recommend using proportion-type decisions when calculating the scores
(see below for an example).
Solution format
The argument to solution must be in the same format as
the planning unit data in the argument to x
(e.g. in terms of data representation, dimensionality, and spatial
attributes).
For example, if the planning unit data in x is a numeric
vector, then the argument to solution must be a numeric vector
with the same number of elements.
Similarly, if the planning units in x are a data.frame, then the
argument to solution must also be a data.frame with each
column corresponding to a different zone, each row corresponding to a
different planning unit, and cell values corresponding to the solution value.
Additionally, if the planning unit data in x is
a Raster object, then the argument to
solution must also be a Raster object with
the same dimensionality (rows and columns), resolution, extent, and
coordinate reference system.
Furthermore, if the planning unit data in x is a
Spatial or sf::sf() object then the
argument to solution must also be a Spatial
or sf::sf() object (respectively) with the same spatial information
(e.g. polygons and coordinate reference system), and contain columns
corresponding to different zones, and cell values corresponding to the
solution values.
The argument to solution must also have missing (NA) values for planning
units that have missing (NA) cost values.
In other words, the solution must have missing (NA) values in the
same elements, cells, or pixels (depending on the cost data format) as the
planning unit cost data.
For example, if the planning unit data are a Raster object,
then the argument to solution must have missing (NA) values in
the same pixels as the planning unit cost data.
Similarly, if the planning unit data are a
Spatial, sf::sf(), or data.frame object, then
the solution must have missing (NA) values in the same cells
as the planning unit cost data columns.
If an argument is supplied to solution where
the missing (NA) values in the argument to solution do not match
those in the planning unit cost data, then an error will be thrown.
References
Cabeza M and Moilanen A (2006) Replacement cost: A practical measure of site value for cost-effective reserve planning. Biological Conservation, 132: 336--342.
See also
Examples
# seed seed for reproducibility set.seed(600) # load data data(sim_pu_raster, sim_features, sim_pu_zones_stack, sim_features_zones) # create minimal problem with binary decisions p1 <- problem(sim_pu_raster, sim_features) %>% add_min_set_objective() %>% add_relative_targets(0.1) %>% add_binary_decisions() %>% add_default_solver(gap = 0, verbose = FALSE) # \dontrun{ # solve problem s1 <- solve(p1) # print solution print(s1)#> class : RasterLayer #> dimensions : 10, 10, 100 (nrow, ncol, ncell) #> resolution : 0.1, 0.1 (x, y) #> extent : 0, 1, 0, 1 (xmin, xmax, ymin, ymax) #> crs : NA #> source : memory #> names : layer #> values : 0, 1 (min, max) #># calculate importance scores rc1 <- eval_replacement_importance(p1, s1) # print importance scores print(rc1)#> class : RasterLayer #> dimensions : 10, 10, 100 (nrow, ncol, ncell) #> resolution : 0.1, 0.1 (x, y) #> extent : 0, 1, 0, 1 (xmin, xmax, ymin, ymax) #> crs : NA #> source : memory #> names : layer #> values : 0, 1 (min, max) #># } # since replacement cost scores can take a long time to calculate with # binary decisions, we can calculate them using proportion-type # decision variables. Note we are still calculating the scores for our # previous solution (s1), we are just using a different optimization # problem when calculating the scores. p2 <- problem(sim_pu_raster, sim_features) %>% add_min_set_objective() %>% add_relative_targets(0.1) %>% add_proportion_decisions() %>% add_default_solver(gap = 0, verbose = FALSE) # calculate importance scores using proportion type decisions # \dontrun{ rc2 <- eval_replacement_importance(p2, s1) # print importance scores based on proportion type decisions print(rc2)#> class : RasterLayer #> dimensions : 10, 10, 100 (nrow, ncol, ncell) #> resolution : 0.1, 0.1 (x, y) #> extent : 0, 1, 0, 1 (xmin, xmax, ymin, ymax) #> crs : NA #> source : memory #> names : layer #> values : 0, 1 (min, max) #># plot importance scores based on proportion type decisions # we can see that the importance values in rc1 and rc2 are similar, # and this confirms that the proportion type decisions are a good # approximation plot(rc2, main = "replacement cost", axes = FALSE, box = FALSE)# } # build multi-zone conservation problem with binary decisions p3 <- problem(sim_pu_zones_stack, sim_features_zones) %>% add_min_set_objective() %>% add_relative_targets(matrix(runif(15, 0.1, 0.2), nrow = 5, ncol = 3)) %>% add_binary_decisions() %>% add_default_solver(gap = 0, verbose = FALSE) # \dontrun{ # solve the problem s3 <- solve(p3) # print solution print(s3)#> class : RasterStack #> dimensions : 10, 10, 100, 3 (nrow, ncol, ncell, nlayers) #> resolution : 0.1, 0.1 (x, y) #> extent : 0, 1, 0, 1 (xmin, xmax, ymin, ymax) #> crs : NA #> names : layer.1.1, layer.1.2, layer.1.3 #> min values : 0, 0, 0 #> max values : 1, 1, 1 #># plot solution # each panel corresponds to a different zone, and data show the # status of each planning unit in a given zone plot(s3, main = paste0("zone ", seq_len(nlayers(s3))), axes = FALSE, box = FALSE)# calculate importance scores rc3 <- eval_replacement_importance(p3, s3) # plot importance # each panel corresponds to a different zone, and data show the # importance of each planning unit in a given zone plot(rc3, main = paste0("zone ", seq_len(nlayers(s3))), axes = FALSE, box = FALSE)# }
