/
portfolios.R
108 lines (106 loc) · 4.07 KB
/
portfolios.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
#' @include internal.R Collection-proto.R
NULL
#' Solution portfolios
#'
#' Conservation planning exercises rarely have access to all the
#' data needed to identify the *truly* perfect solution. This is because
#' available data may lack important details
#' (e.g. land acquisition costs may be unavailable), contain errors
#' (e.g. species presence/absence data may have false positives),
#' or key objectives may not be formally incorporated into the
#' prioritization process (e.g. future land use requirements).
#' As such, conservation planners can help decision makers by providing
#' them with a portfolio of solutions to inform their decision.
#'
#' @details
#' The following portfolios can be added to a conservation planning
#' [problem()].
#' Note that all methods for generating portfolios return solutions that
#' are within the specified optimality gap.
#'
#' \describe{
#'
#' \item{[add_extra_portfolio()]}{Generate a portfolio of solutions
#' by storing feasible solutions found during the optimization
#' process. This method is useful for quickly obtaining multiple solutions,
#' but does not provide any guarantees on the number of solutions, or
#' the quality of solutions.
#' Note that it requires the *Gurobi* solver.}
#'
#' \item{[add_top_portfolio()]}{Generate a portfolio of
#' solutions by finding a pre-specified number of solutions that
#' are closest to optimality (i.e the top solutions). This is useful
#' for examining differences among near-optimal solutions.
#' It can also be used to generate multiple solutions and, in turn,
#' to calculate selection frequencies for small problems.
#' Note that it requires the *Gurobi* solver.}
#'
#' \item{[add_gap_portfolio()]}{Generate a portfolio of solutions
#' by finding a certain number of solutions that are all within a pre-
#' specified optimality gap. This method is useful for generating
#' multiple solutions that can be used to calculate selection frequencies
#' for moderate and large-sized problems (similar to *Marxan*).
#' Note that it requires the *Gurobi* solver.}
#'
#' \item{[add_cuts_portfolio()]}{Generate a portfolio of distinct
#' solutions within a pre-specified optimality gap using Bender's cuts.
#' This is recommended as a replacement for [add_top_portfolio()]
#' when the *Gurobi* software is not available.}
#
#' \item{[add_shuffle_portfolio()]}{Generate a portfolio of
#' solutions by randomly reordering the data prior to attempting to solve
#' the problem.
#' This is recommended as a replacement for [add_gap_portfolio()]
#' when the *Gurobi* software is not available.}
#'
#' }
#'
#' @family overviews
#'
#' @examples
#' # load data
#' data(sim_pu_raster, sim_features)
#'
#' # create problem
#' p <- problem(sim_pu_raster, sim_features) %>%
#' add_min_set_objective() %>%
#' add_relative_targets(0.1) %>%
#' add_binary_decisions() %>%
#' add_default_solver(gap = 0.02, verbose = FALSE)
#'
#' # create problem with cuts portfolio with 4 solutions
#' p1 <- p %>% add_cuts_portfolio(4)
#'
#' # create problem with shuffle portfolio with 4 solutions
#' p2 <- p %>% add_shuffle_portfolio(4)
#' \dontrun{
#' # create problem with extra portfolio
#' p3 <- p %>% add_extra_portfolio()
#'
#' # create problem with top portfolio with 4 solutions
#' p4 <- p %>% add_top_portfolio(4)
#'
#' # create problem with gap portfolio with 4 solutions within 50% of optimality
#' p5 <- p %>% add_gap_portfolio(4, 0.5)
#'
#' # solve problems and create solution portfolios
#' s <- list(solve(p1), solve(p2), solve(p3), solve(p4), solve(p5))
#'
#' # plot solutions from extra portfolio
#' plot(stack(s[[1]]), axes = FALSE, box = FALSE)
#'
#' # plot solutions from top portfolio
#' plot(stack(s[[2]]), axes = FALSE, box = FALSE)
#'
#' # plot solutions from gap portfolio
#' plot(stack(s[[3]]), axes = FALSE, box = FALSE)
#'
#' # plot solutions from cuts portfolio
#' plot(stack(s[[4]]), axes = FALSE, box = FALSE)
#'
#' # plot solutions from shuffle portfolio
#' plot(stack(s[[5]]), axes = FALSE, box = FALSE)
#'
#' }
#' @name portfolios
NULL