prioritizr / prioritizr
Showing 56 of 331 files from the diff.
Other files ignored by Codecov
man/objectives.Rd has changed.
R/decisions.R has changed.
R/portfolios.R has changed.
pkgdown/extra.css has changed.
R/solvers.R has changed.
NAMESPACE has changed.
man/decisions.Rd has changed.
_pkgdown.yml has changed.
man/zones.Rd has changed.
docs/index.html has changed.
docs/pkgdown.yml has changed.
tests/testthat.R has changed.
docs/sitemap.xml has changed.
R/penalties.R has changed.
R/deprecated.R has changed.
man/summaries.Rd has changed.
docs/404.html has changed.
R/summaries.R has changed.
man/penalties.Rd has changed.
man/problem.Rd has changed.
docs/extra.css has changed.
man/solve.Rd has changed.
docs/authors.html has changed.
README.md has changed.
NEWS.md has changed.
man/solvers.Rd has changed.
man/targets.Rd has changed.
R/constraints.R has changed.
R/RcppExports.R has changed.
inst/WORDLIST has changed.
README.Rmd has changed.
DESCRIPTION has changed.
man/portfolios.Rd has changed.
man/importance.Rd has changed.
R/package.R has changed.
R/importance.R has changed.
R/objectives.R has changed.

@@ -35,16 +35,16 @@
Loading
35 35
#'
36 36
#' \describe{
37 37
#'
38 -
#' \item{`integer`}{`vector` of indices pertaining to which
38 +
#' \item{`data` as an `integer` vector}{containing indices that indicate which
39 39
#'   planning units should be locked for the solution. This argument is only
40 40
#'   compatible with problems that contain a single zone.}
41 41
#'
42 -
#' \item{`logical`}{`vector` containing `TRUE` and/or
42 +
#' \item{`data` as a `logical` vector}{containing `TRUE` and/or
43 43
#'   `FALSE` values that indicate which planning units should be locked
44 44
#'   in the solution. This argument is only compatible with problems that
45 45
#'   contain a single zone.}
46 46
#'
47 -
#' \item{`matrix`}{containing `logical` `TRUE` and/or
47 +
#' \item{`data` as a `matrix` object}{containing `logical` `TRUE` and/or
48 48
#'   `FALSE` values which indicate if certain planning units are
49 49
#'   should be locked to a specific zone in the solution. Each row
50 50
#'   corresponds to a planning unit, each column corresponds to a zone, and
@@ -52,25 +52,31 @@
Loading
52 52
#'   zone. Thus each row should only contain at most a single `TRUE`
53 53
#'   value.}
54 54
#'
55 -
#' \item{`character`}{field (column) name(s) that indicate if planning
56 -
#'   units should be locked for the solution. This type of argument is only
55 +
#' \item{`data` as a `character` vector}{containing field (column) name(s)
56 +
#'   that indicate if planning units should be locked for the solution.
57 +
#'   This format is only
57 58
#'   compatible if the planning units in the argument to `x` are a
58 59
#'   [`Spatial-class`], [sf::sf()], or
59 60
#'   `data.frame` object. The fields
60 -
#'   (columns) must have `logical`  (i.e. `TRUE` or `FALSE`)
61 +
#'   (columns) must have `logical` (i.e. `TRUE` or `FALSE`)
61 62
#'   values indicating if the planning unit is to be locked for the solution.
62 -
#'   For problems containing multiple zones, this argument should contain
63 -
#'   a field (column) name for each management zone.}
64 -
#'
65 -
#' \item{[`Spatial-class`] or [sf::sf()]}{
66 -
#'   planning units in `x` that spatially intersect with the
67 -
#'   argument to `y` (according to [intersecting_units()]
68 -
#'   are locked for to the solution. Note that this option is only available
63 +
#'   For problems that contain a single zone, the argument to `data` must
64 +
#'   contain a single field name. Otherwise, for problems that
65 +
#'   contain multiple zones, the argument to `data` must
66 +
#'   contain a field name for each zone.}
67 +
#'
68 +
#' \item{`data` as a [`Spatial-class`] or [sf::sf()] object}{
69 +
#'   containing geometries that will be used to lock planning units for
70 +
#'   the solution. Specifically, planning units in `x` that spatially
71 +
#'   intersect with `y` will be locked (per [intersecting_units()]).
72 +
#'   Note that this option is only available
69 73
#'   for problems that contain a single management zone.}
70 74
#'
71 -
#' \item{[`Raster-class`]}{planning units in `x`
72 -
#'   that intersect with non-zero and non-`NA` raster cells are locked
73 -
#'   for the solution. For problems that contain multiple zones, the
75 +
#' \item{`data` as a [`Raster-class`] object}{containing cells used to lock
76 +
#'   planning units for the solution. Specifically, planning units in `x`
77 +
#'   that intersect with cells that have non-zero and non-`NA` values are
78 +
#'   locked.
79 +
#'   For problems that contain multiple zones, the
74 80
#'   [`Raster-class`] object must contain a layer
75 81
#'   for each zone. Note that for multi-band arguments, each pixel must
76 82
#'   only contain a non-zero value in a single band. Additionally, if the
@@ -80,7 +86,12 @@
Loading
80 86
#'   should also have `NA` values in the locked data.}
81 87
#' }
82 88
#'
83 -
#' @inherit add_contiguity_constraints return seealso
89 +
#' @inherit add_contiguity_constraints return
90 +
#'
91 +
#' @seealso
92 +
#' See [constraints] for an overview of all functions for adding constraints.
93 +
#'
94 +
#' @family constraints
84 95
#'
85 96
#' @examples
86 97
#' # set seed for reproducibility
@@ -212,7 +223,6 @@
Loading
212 223
#' # plot solution
213 224
#' plot(category_layer(s9), main = "solution", axes = FALSE, box = FALSE)
214 225
#' }
215 -
#' @seealso [constraints].
216 226
#'
217 227
#' @name add_locked_in_constraints
218 228
#'

@@ -56,7 +56,12 @@
Loading
56 56
#'
57 57
#' @name eval_boundary_summary
58 58
#'
59 -
#' @seealso [problem()], [summaries], [add_boundary_penalties()].
59 +
#' @seealso
60 +
#' See [summaries] for an overview of all functions for summarizing solutions.
61 +
#' Also, see [add_boundary_penalties()] to penalize solutions with high
62 +
#' boundary length.
63 +
#'
64 +
#' @family summaries
60 65
#'
61 66
#' @examples
62 67
#' \dontrun{

@@ -66,7 +66,8 @@
Loading
66 66
#'
67 67
#' \describe{
68 68
#'
69 -
#' \item{`NULL`}{connection data should be calculated automatically
69 +
#' \item{`data` as a `NULL` value}{connection
70 +
#'   data should be calculated automatically
70 71
#'   using the [adjacency_matrix()] function. This is the default
71 72
#'   argument and means that all adjacent planning units are treated
72 73
#'   as potentially dispersible for all features.
@@ -75,7 +76,7 @@
Loading
75 76
#'   in the argument to `x` is not spatially referenced (e.g.
76 77
#'   in `data.frame` or `numeric` format).}
77 78
#'
78 -
#' \item{`matrix`, `Matrix`}{where rows and columns represent
79 +
#' \item{`data` as a`matrix`/`Matrix` object}{where rows and columns represent
79 80
#'   different planning units and the value of each cell indicates if the
80 81
#'   two planning units are connected or not. Cell values should be binary
81 82
#'   `numeric` values (i.e. one or zero). Cells that occur along the
@@ -84,7 +85,7 @@
Loading
84 85
#'   of connected planning units are treated as being potentially dispersible
85 86
#'   for all features.}
86 87
#'
87 -
#' \item{`data.frame`}{containing the fields (columns)
88 +
#' \item{`data` as a `data.frame` object}{containing the fields (columns)
88 89
#'   `"id1"`, `"id2"`, and `"boundary"`. Here, each row
89 90
#'   denotes the connectivity between two planning units following the
90 91
#'   *Marxan* format. The field `boundary` should contain
@@ -99,7 +100,7 @@
Loading
99 100
#'   Note that pairs of connected planning units are treated as being
100 101
#'   potentially dispersible for all features.}
101 102
#'
102 -
#' \item{`list`}{containing `matrix`, `Matrix`, or
103 +
#' \item{`data` as a `list` object}{containing `matrix`, `Matrix`, or
103 104
#'   `data.frame` objects showing which planning units
104 105
#'   should be treated as connected for each feature. Each element in the
105 106
#'   `list` should correspond to a different feature (specifically,
@@ -109,7 +110,12 @@
Loading
109 110
#'
110 111
#' }
111 112
#'
112 -
#' @inherit add_contiguity_constraints return seealso
113 +
#' @inherit add_contiguity_constraints return
114 +
#"
115 +
#' @seealso
116 +
#' See [constraints] for an overview of all functions for adding constraints.
117 +
#'
118 +
#' @family constraints
113 119
#'
114 120
#' @section Notes:
115 121
#' In early versions, it was named as the `add_corridor_constraints` function.

@@ -39,9 +39,12 @@
Loading
39 39
#' remotes::install_bioc("lpsymphony")
40 40
#' ```
41 41
#'
42 -
#' @inherit add_rsymphony_solver seealso return references
42 +
#' @inherit add_rsymphony_solver return references
43 43
#'
44 -
#' @seealso [solvers].
44 +
#' @seealso
45 +
#' See [solvers] for an overview of all functions for adding a solver.
46 +
#'
47 +
#' @family solvers
45 48
#'
46 49
#' @examples
47 50
#' \dontrun{

@@ -8,7 +8,12 @@
Loading
8 8
#'
9 9
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
10 10
#'
11 -
#' @seealso [portfolios].
11 +
#' @seealso
12 +
#' See [portfolios] for an overview of all functions for adding a portfolio.
13 +
#'
14 +
#' @family portfolios
15 +
#'
16 +
#' @inherit add_cuts_portfolio return
12 17
#'
13 18
#' @noRd
14 19
add_default_portfolio <- function(x) {

@@ -13,8 +13,13 @@
Loading
13 13
14 14
#' Management zones
15 15
#'
16 -
#' Organize biodiversity data into the expected amount of different features
17 -
#' under different management zones.
16 +
#' Organize data for multiple features for multiple management zones.
17 +
#' Specifically, the data should describe the expected amount of each
18 +
#' feature within each planning unit given each management zone.
19 +
#' For example, the data could describe the occupancy
20 +
#' (e.g. presence/absence), probability of occurrence, or
21 +
#' abundance expected for each feature when each planning unit
22 +
#' is allocated to a different zone.
18 23
#'
19 24
#' @param ... [raster::raster()] or `character` objects that
20 25
#'   pertain to the biodiversity data. See Details for more information.
@@ -25,42 +30,45 @@
Loading
25 30
#' @param feature_names `character` names of the features zones. Defaults
26 31
#'   to `NULL` which results in sequential integers.
27 32
#'
28 -
#' @details This function is used to store and organize data for use in a
29 -
#'   conservation planning [problem()] that has multiple management
30 -
#'   zones. In all cases, the data for each zone is input as a separate
31 -
#'   argument. The correct arguments depends on the type of planning unit data
32 -
#'   used when building the conservation planning [problem()].
33 +
#' @details
34 +
#' This function is used to store and organize data for use in a
35 +
#' conservation planning [problem()] that has multiple management
36 +
#' zones.
37 +
#' In all cases, the data for each zone is input as a separate argument.
38 +
#' The correct arguments depends on the type of planning unit data
39 +
#' used when building the conservation planning [problem()].
33 40
#'
41 +
#' \describe{
42 +
#' \item{planning unit data are a [`Raster-class`] or [`Spatial-class`] object}{
43 +
#'   [`Raster-class`] object can be supplied to specify the expected amount of
44 +
#'   each feature within each planning unit under each management zone.
45 +
#'   Data for each zone should be specified as separate
46 +
#'   arguments, and the data for each feature in a given zone are specified
47 +
#'   in separate layers in a [raster::stack()] object.
48 +
#'   Note that all layers for a given zone must have `NA` values in exactly the
49 +
#'   same cells.}
50 +
#' \item{planning unit data are a [`Spatial-class`] or `data.frame`
51 +
#'   object}{`character` vector containing column names can
52 +
#'   be supplied to specify the expected amount of each feature under each
53 +
#'   zone. Note that these columns must not contain any `NA` values.}
54 +
#' \item{planning unit data are a [`Spatial-class`], `data.frame`, or
55 +
#'   `matrix` object}{`data.frame` object can be supplied to specify the
56 +
#'   expected amount of each feature under each zone.
57 +
#'   Following conventions used in *Marxan*, the
58 +
#'   `data.frame` object should contain the following columns.
34 59
#'   \describe{
35 -
#'   \item{[`Raster-class`],
36 -
#'     [`Spatial-class`]}{[`Raster-class`]
37 -
#'     data denoting the amount of each feature present assuming each
38 -
#'     management zone. Data for each zone are specified in separate
39 -
#'     arguments, and the data for each feature in a given zone are specified
40 -
#'     in separate layers in a [raster::stack()] object. Note that
41 -
#'     all layers for a given zone must have `NA` values in exactly the
42 -
#'     same cells.}
43 -
#'   \item{[Spatial()], `data.frame`}{`character` vector
44 -
#'     with column names that correspond to the abundance or occurrence of
45 -
#'     different features in each planning unit for each zone. Note that
46 -
#'     these columns must not contain any `NA` values.}
47 -
#'   \item{[Spatial()], `data.frame` or
48 -
#'     `matrix`}{`data.frame` denoting the amount of each feature
49 -
#'     in each zone. Following conventions used in *Marxan*,
50 -
#'     `data.frame` objects should be supplied with the columns:
51 -
#'     \describe{
52 60
#'     \item{pu}{`integer` planning unit identifier.}
53 61
#'     \item{species}{`integer` feature identifier.}
54 62
#'     \item{amount}{`numeric` amount of the feature in the
55 -
#'       planning unit for a given zone.}
56 -
#'     }
57 -
#'     Note that data for each zone are specified in a separate argument, and
58 -
#'     the data contained in a single `data.frame` object correspond to
59 -
#'     a single zone. Also, note that data are not required for all
60 -
#'     combinations of planning units, features, and zones. The amounts of
61 -
#'     features in planning units assuming different management zones that are
62 -
#'     missing from the table are treated as zero.}
63 +
#'     planning unit for a given zone.}
63 64
#'   }
65 +
#'   Note that data for each zone are specified in a separate argument, and
66 +
#'   the data contained in a single `data.frame` object should correspond to
67 +
#'   a single zone. Also, note that data are not required for all
68 +
#'   combinations of planning units, features, and zones. The expected amount of
69 +
#'   features in planning units under management zones that are
70 +
#'   missing from the table are assumed to be zero.}
71 +
#' }
64 72
#'
65 73
#' @return [`Zones-class`] object.
66 74
#'

@@ -49,40 +49,6 @@
Loading
49 49
#' It was inspired by Beger *et al.* (2010) and can symmetric and asymmetric
50 50
#' connectivity relationships between planning units.
51 51
#'
52 -
#' The connectivity penalties are calculated using the following equations.
53 -
#' Let \eqn{I} represent the set of planning units
54 -
#' (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent the set
55 -
#' of management zones (indexed by \eqn{z} or \eqn{y}), and \eqn{X_{iz}}{Xiz}
56 -
#' represent the decision variable for planning unit \eqn{i} for in zone
57 -
#' \eqn{z} (e.g. with binary
58 -
#' values one indicating if planning unit is allocated or not). Also, let
59 -
#' \eqn{p} represent the argument to `penalty`, \eqn{D} represent the
60 -
#' argument to `data`, and \eqn{W} represent the argument
61 -
#' to `zones`.
62 -
#'
63 -
#' If the argument to `data` is supplied as a `matrix` or
64 -
#' `Matrix` object, then the penalties are calculated as:
65 -
#'
66 -
#' \deqn{
67 -
#' \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz}
68 -
#' \times X_{jy} \times D_{ij} \times W_{zy})}{
69 -
#' sum_i^I sum_j^I sum_z^Z sum_y^Z (-p * Xiz * Xjy * Dij * Wzy)
70 -
#' }
71 -
#'
72 -
#' Otherwise, if the argument to `data` is supplied as a
73 -
#' `data.frame` or `array` object, then the penalties are
74 -
#' calculated as:
75 -
#'
76 -
#' \deqn{
77 -
#' \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz}
78 -
#' \times X_{jy} \times D_{ijzy})}{
79 -
#' sum_i^I sum_j^I sum_z^Z sum_y^Z (-p * Xiz * Xjy * Dijzy)
80 -
#' }
81 -
#'
82 -
#' Note that when the problem objective is to maximize some measure of
83 -
#' benefit and not minimize some measure of cost, the term \eqn{-p} is
84 -
#' replaced with \eqn{p}.
85 -
#'
86 52
#' @section Data format:
87 53
#' The argument to `data` can be specified using several different formats.
88 54
#' These formats can be used to describe symmetric or
@@ -90,7 +56,7 @@
Loading
90 56
#'
91 57
#' \describe{
92 58
#'
93 -
#' \item{`matrix`, `Matrix`}{where rows and columns represent
59 +
#' \item{`data` as a `matrix`/`Matrix` object}{where rows and columns represent
94 60
#'   different planning units and the value of each cell represents the
95 61
#'   strength of connectivity between two different planning units. Cells
96 62
#'   that occur along the matrix diagonal are treated as weights which
@@ -100,7 +66,7 @@
Loading
100 66
#'   The default argument for `zones` is to treat planning units
101 67
#'   allocated to different zones as having zero connectivity.}
102 68
#'
103 -
#' \item{`data.frame`}{containing the fields (columns)
69 +
#' \item{`data` as a `data.frame` object}{containing the fields (columns)
104 70
#'   `"id1"`, `"id2"`, and `"boundary"`. Here, each row
105 71
#'   denotes the connectivity between two planning units following the
106 72
#'   *Marxan* format. The data can be used to denote symmetric or
@@ -116,7 +82,8 @@
Loading
116 82
#'   `"zone2"` are present, then the argument to `zones` must be
117 83
#'   `NULL`.}
118 84
#'
119 -
#' \item{`array`}{containing four-dimensions where cell values
85 +
#' \item{`data` as an `array` object}{
86 +
#'   containing four-dimensions where cell values
120 87
#'   indicate the strength of connectivity between planning units
121 88
#'   when they are assigned to specific management zones. The first two
122 89
#'   dimensions (i.e. rows and columns) indicate the strength of
@@ -128,7 +95,47 @@
Loading
128 95
#'
129 96
#' }
130 97
#'
131 -
#' @inherit add_boundary_penalties return seealso
98 +
#' @section Mathematical formulation:
99 +
#' The connectivity penalties are implemented using the following equations.
100 +
#' Let \eqn{I} represent the set of planning units
101 +
#' (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent the set
102 +
#' of management zones (indexed by \eqn{z} or \eqn{y}), and \eqn{X_{iz}}{Xiz}
103 +
#' represent the decision variable for planning unit \eqn{i} for in zone
104 +
#' \eqn{z} (e.g. with binary
105 +
#' values one indicating if planning unit is allocated or not). Also, let
106 +
#' \eqn{p} represent the argument to `penalty`, \eqn{D} represent the
107 +
#' argument to `data`, and \eqn{W} represent the argument
108 +
#' to `zones`.
109 +
#'
110 +
#' If the argument to `data` is supplied as a `matrix` or
111 +
#' `Matrix` object, then the penalties are calculated as:
112 +
#'
113 +
#' \deqn{
114 +
#' \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz}
115 +
#' \times X_{jy} \times D_{ij} \times W_{zy})}{
116 +
#' sum_i^I sum_j^I sum_z^Z sum_y^Z (-p * Xiz * Xjy * Dij * Wzy)
117 +
#' }
118 +
#'
119 +
#' Otherwise, if the argument to `data` is supplied as a
120 +
#' `data.frame` or `array` object, then the penalties are
121 +
#' calculated as:
122 +
#'
123 +
#' \deqn{
124 +
#' \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz}
125 +
#' \times X_{jy} \times D_{ijzy})}{
126 +
#' sum_i^I sum_j^I sum_z^Z sum_y^Z (-p * Xiz * Xjy * Dijzy)
127 +
#' }
128 +
#'
129 +
#' Note that when the problem objective is to maximize some measure of
130 +
#' benefit and not minimize some measure of cost, the term \eqn{-p} is
131 +
#' replaced with \eqn{p}.
132 +
#'
133 +
#' @inherit add_boundary_penalties return
134 +
#'
135 +
#' @seealso
136 +
#' See [penalties] for an overview of all functions for adding penalties.
137 +
#'
138 +
#' @family penalties
132 139
#'
133 140
#' @references
134 141
#' Beger M, Linke S, Watts M, Game E, Treml E, Ball I, and Possingham, HP (2010)

@@ -53,7 +53,10 @@
Loading
53 53
#'
54 54
#' @aliases eval_feature_representation_summary,ConservationProblem,numeric-method eval_feature_representation_summary,ConservationProblem,matrix-method eval_feature_representation_summary,ConservationProblem,data.frame-method eval_feature_representation_summary,ConservationProblem,Spatial-method eval_feature_representation_summary,ConservationProblem,sf-method eval_feature_representation_summary,ConservationProblem,Raster-method
55 55
#'
56 -
#' @inherit eval_cost_summary seealso
56 +
#' @seealso
57 +
#' See [summaries] for an overview of all functions for summarizing solutions.
58 +
#'
59 +
#' @family summaries
57 60
#'
58 61
#' @examples
59 62
#' # set seed for reproducibility

@@ -11,7 +11,7 @@
Loading
11 11
#' @param n `integer` number of threads.
12 12
#'
13 13
#' @details This function returns a `list` containing an element for
14 -
#'   each worker. Each element contains a `integer` `vector`
14 +
#'   each worker. Each element contains a `integer` vector
15 15
#'   specifying the indices that the worker should process.
16 16
#'
17 17
#' @return `list` object.

@@ -13,7 +13,12 @@
Loading
13 13
#'
14 14
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
15 15
#'
16 -
#' @inherit add_binary_decisions details return seealso
16 +
#' @inherit add_binary_decisions details return
17 +
#'
18 +
#' @seealso
19 +
#' See [decisions] for an overview of all functions for adding decisions.
20 +
#'
21 +
#' @family decisions
17 22
#'
18 23
#' @examples
19 24
#' # set seed for reproducibility

@@ -4,53 +4,54 @@
Loading
4 4
#' Add minimum shortfall objective
5 5
#'
6 6
#' Set the objective of a conservation planning [problem()] to
7 -
#' minimize the overall shortfall for as many targets as possible while
7 +
#' minimize the overall shortfall for as many [targets] as possible while
8 8
#' ensuring that the cost of the solution does not exceed a budget.
9 9
#'
10 10
#' @inheritParams add_max_features_objective
11 11
#'
12 -
#' @details A problem objective is used to specify the overall goal of the
13 -
#'   conservation planning problem. Please note that all conservation
14 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
15 -
#'   addition of objectives---failing to do so will return an error
16 -
#'   message when attempting to solve problem.
17 -
#'
18 -
#'   The minimum shortfall objective aims to
19 -
#'   find the set of planning units that minimize the overall
20 -
#'   (weighted sum) shortfall for the
21 -
#'   representation targets---that is, the fraction of each target that
22 -
#'   remains unmet---for as many features as possible while staying within a
23 -
#'   fixed budget (inspired by Table 1, equation IV, Arponen *et al.*
24 -
#'   2005). Additionally, weights can be used
25 -
#'   to favor the representation of certain features over other features (see
26 -
#'   [add_feature_weights()].
27 -
#'
28 -
#'   The minimum shortfall objective for the reserve design problem can be
29 -
#'   expressed mathematically for a set of planning units (\eqn{I}{I} indexed by
30 -
#'   \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
31 -
#'
32 -
#'   \deqn{\mathit{Minimize} \space  \sum_{j = 1}^{J} w_j \frac{y_j}{t_j} \\
33 -
#'   \mathit{subject \space to} \\
34 -
#'   \sum_{i = 1}^{I} x_i r_{ij} + y_j \geq t_j \forall j \in J \\
35 -
#'   \sum_{i = 1}^{I} x_i c_i \leq B}{
36 -
#'   Minimize sum_j^J wj * (yj / tj) subject to
37 -
#'   sum_i^I (xi * rij) + yj >= tj for all j in J &
38 -
#'   sum_i^I (xi * ci) <= B}
39 -
#'
40 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
41 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
42 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
43 -
#'   unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
44 -
#'   \eqn{j}{j}, \eqn{y_j}{yj} denotes the representation shortfall for
45 -
#'   the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and \eqn{w_j}{wj} is the
46 -
#'   weight for feature \eqn{j}{j} (defaults to 1 for all features; see
47 -
#'   [add_feature_weights()] to specify weights). Additionally,
48 -
#'   \eqn{B}{B} is the budget allocated for the solution, \eqn{c_i}{ci} is the
49 -
#'   cost of planning unit \eqn{i}{i}. Note that \eqn{y_j}{yj} is a continuous
50 -
#'   variable bounded between zero and infinity, and denotes the shortfall
51 -
#'   for target \eqn{j}{j}.
52 -
#'
53 -
#' @seealso [add_feature_weights()], [objectives].
12 +
#' @details
13 +
#' The minimum shortfall objective aims to
14 +
#' find the set of planning units that minimize the overall
15 +
#' (weighted sum) shortfall for the
16 +
#' representation targets---that is, the fraction of each target that
17 +
#' remains unmet---for as many features as possible while staying within a
18 +
#' fixed budget (inspired by Table 1, equation IV, Arponen *et al.*
19 +
#' 2005). Additionally, weights can be used
20 +
#' to favor the representation of certain features over other features (see
21 +
#' [add_feature_weights()].
22 +
#'
23 +
#' @section Mathematical formulation:
24 +
#' This objective can be expressed mathematically for a set of planning units
25 +
#' (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed
26 +
#' by \eqn{j}{j}) as:
27 +
#'
28 +
#' \deqn{\mathit{Minimize} \space  \sum_{j = 1}^{J} w_j \frac{y_j}{t_j} \\
29 +
#' \mathit{subject \space to} \\
30 +
#' \sum_{i = 1}^{I} x_i r_{ij} + y_j \geq t_j \forall j \in J \\
31 +
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
32 +
#' Minimize sum_j^J wj * (yj / tj) subject to
33 +
#' sum_i^I (xi * rij) + yj >= tj for all j in J &
34 +
#' sum_i^I (xi * ci) <= B}
35 +
#'
36 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
37 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
38 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
39 +
#' unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
40 +
#' \eqn{j}{j}, \eqn{y_j}{yj} denotes the representation shortfall for
41 +
#' the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and \eqn{w_j}{wj} is the
42 +
#' weight for feature \eqn{j}{j} (defaults to 1 for all features; see
43 +
#' [add_feature_weights()] to specify weights). Additionally,
44 +
#' \eqn{B}{B} is the budget allocated for the solution, \eqn{c_i}{ci} is the
45 +
#' cost of planning unit \eqn{i}{i}. Note that \eqn{y_j}{yj} is a continuous
46 +
#' variable bounded between zero and infinity, and denotes the shortfall
47 +
#' for target \eqn{j}{j}.
48 +
#'
49 +
#' @seealso
50 +
#' See [objectives] for an overview of all functions for adding objectives.
51 +
#' Also, see [targets] for an overview of all functions for adding targets, and
52 +
#' [add_feature_weights()] to specify weights for different features.
53 +
#'
54 +
#' @family objectives
54 55
#'
55 56
#' @inherit add_min_set_objective return
56 57
#'
57 58
imilarity index 97%
58 59
ename from R/add_neighbor_contraints.R
59 60
ename to R/add_neighbor_constraints.R

@@ -28,9 +28,9 @@
Loading
28 28
#'
29 29
#' # create minimal problem
30 30
#' p <- problem(sim_pu_raster, sim_features) %>%
31 -
#'       add_min_set_objective() %>%
32 -
#'       add_relative_targets(0.1) %>%
33 -
#'       add_binary_decisions()
31 +
#'      add_min_set_objective() %>%
32 +
#'      add_relative_targets(0.1) %>%
33 +
#'      add_binary_decisions()
34 34
#'
35 35
#' # save problem to file (using the Rsymphony R package)
36 36
#' write_problem(p, "model.lp")

@@ -147,15 +147,15 @@
Loading
147 147
#'
148 148
#' @param name `character` name of parameter.
149 149
#'
150 -
#' @param value `vector` of values.
150 +
#' @param value `numeric` vector of values.
151 151
#'
152 -
#' @param label `character` `vector` of labels for each value.
152 +
#' @param label `character` vector of labels for each value.
153 153
#'
154 -
#' @param lower_limit `vector` of values denoting the minimum acceptable
154 +
#' @param lower_limit `numeric` vector of values denoting the minimum acceptable
155 155
#'   value for each element in `value`. Defaults to the
156 156
#'   smallest possible number on the system.
157 157
#'
158 -
#' @param upper_limit `vector` of values denoting the maximum acceptable
158 +
#' @param upper_limit `numeric` vector of values denoting the maximum acceptable
159 159
#'   value for each element in `value`. Defaults to the
160 160
#'   largest  possible number on the system.
161 161
#'

@@ -18,6 +18,7 @@
Loading
18 18
extern SEXP _prioritizr_rcpp_apply_decisions(SEXP, SEXP, SEXP, SEXP);
19 19
extern SEXP _prioritizr_rcpp_apply_feature_contiguity_constraints(SEXP, SEXP, SEXP);
20 20
extern SEXP _prioritizr_rcpp_apply_feature_weights(SEXP, SEXP);
21 +
extern SEXP _prioritizr_rcpp_apply_linear_constraints(SEXP, SEXP, SEXP, SEXP);
21 22
extern SEXP _prioritizr_rcpp_apply_linear_penalties(SEXP, SEXP, SEXP);
22 23
extern SEXP _prioritizr_rcpp_apply_locked_constraints(SEXP, SEXP, SEXP, SEXP);
23 24
extern SEXP _prioritizr_rcpp_apply_max_cover_objective(SEXP, SEXP, SEXP);
@@ -71,6 +72,7 @@
Loading
71 72
    {"_prioritizr_rcpp_apply_decisions",                                   (DL_FUNC) &_prioritizr_rcpp_apply_decisions,                                   4},
72 73
    {"_prioritizr_rcpp_apply_feature_contiguity_constraints",              (DL_FUNC) &_prioritizr_rcpp_apply_feature_contiguity_constraints,              3},
73 74
    {"_prioritizr_rcpp_apply_feature_weights",                             (DL_FUNC) &_prioritizr_rcpp_apply_feature_weights,                             2},
75 +
    {"_prioritizr_rcpp_apply_linear_constraints",                          (DL_FUNC) &_prioritizr_rcpp_apply_linear_constraints,                          4},
74 76
    {"_prioritizr_rcpp_apply_linear_penalties",                            (DL_FUNC) &_prioritizr_rcpp_apply_linear_penalties,                            3},
75 77
    {"_prioritizr_rcpp_apply_locked_constraints",                          (DL_FUNC) &_prioritizr_rcpp_apply_locked_constraints,                          4},
76 78
    {"_prioritizr_rcpp_apply_max_cover_objective",                         (DL_FUNC) &_prioritizr_rcpp_apply_max_cover_objective,                         3},

@@ -26,7 +26,12 @@
Loading
26 26
#'   when problems are quick to solve and multiple threads are available for
27 27
#'   solving each problem separately.
28 28
#'
29 -
#' @inherit add_cuts_portfolio seealso return
29 +
#' @inherit add_cuts_portfolio return
30 +
#'
31 +
#' @seealso
32 +
#' See [portfolios] for an overview of all functions for adding a portfolio.
33 +
#'
34 +
#' @family portfolios
30 35
#'
31 36
#' @examples
32 37
#' # set seed for reproducibility

@@ -35,28 +35,32 @@
Loading
35 35
#'
36 36
#' The argument to `weights` can be specified using the following formats.
37 37
#'
38 -
#'   \describe{
39 -
#'
40 -
#'   \item{`numeric`}{containing weights for each feature. Note that this
41 -
#'     type of argument cannot be used to specify weights for problems with
42 -
#'     multiple zones.}
43 -
#'
44 -
#'   \item{`matrix`}{containing weights for each feature in each zone.
45 -
#'      Here, each row corresponds to a different feature in argument to
46 -
#'      `x`, each column corresponds to a different zone in argument to
47 -
#'      `x`, and each cell contains the weight value for a given feature
48 -
#'      that the solution can to secure in a given zone. Note that
49 -
#'      if the problem contains targets created using
50 -
#'      [add_manual_targets()] then a `matrix` should be
51 -
#'      supplied containing a single column that indicates that weight for
52 -
#'      fulfilling each target.}
38 +
#' \describe{
39 +
#'
40 +
#' \item{`weights` as a `numeric` vector}{containing weights for each feature.
41 +
#'   Note that this format cannot be used to specify weights for problems with
42 +
#'   multiple zones.}
43 +
#'
44 +
#' \item{`weights` as a `matrix` object}{containing weights
45 +
#'   for each feature in each zone.
46 +
#'   Here, each row corresponds to a different feature in argument to
47 +
#'   `x`, each column corresponds to a different zone in argument to
48 +
#'   `x`, and each cell contains the weight value for a given feature
49 +
#'   that the solution can to secure in a given zone. Note that
50 +
#'   if the problem contains targets created using
51 +
#'   [add_manual_targets()] then a `matrix` should be
52 +
#'   supplied containing a single column that indicates that weight for
53 +
#'   fulfilling each target.}
53 54
#'
54 55
#'   }
55 56
#'
56 57
#' @return Object (i.e. [`ConservationProblem-class`]) with the weights
57 58
#'  added to it.
58 59
#'
59 -
#' @seealso [objectives].
60 +
#' @seealso
61 +
#' See [penalties] for an overview of all functions for adding penalties.
62 +
#'
63 +
#' @family penalties
60 64
#'
61 65
#' @examples
62 66
#' # load ape package

@@ -13,8 +13,7 @@
Loading
13 13
#'
14 14
#' @details Conservation planning problems involve making decisions on planning
15 15
#'   units. These decisions are then associated with actions (e.g. turning a
16 -
#'   planning unit into a protected area). If no decision is explicitly added to
17 -
#'   a problem, then the binary decision class will be used by default. Only a
16 +
#'   planning unit into a protected area). Only a
18 17
#'   single decision should be added to a `ConservationProblem` object.
19 18
#'   Note that if multiple decisions are added to a problem object, then the
20 19
#'   last one to be added will be used.
@@ -22,7 +21,10 @@
Loading
22 21
#' @return Object (i.e. [`ConservationProblem-class`]) with the decisions added
23 22
#'   to it.
24 23
#'
25 -
#' @seealso [decisions].
24 +
#' @seealso
25 +
#' See [decisions] for an overview of all functions for adding decisions.
26 +
#'
27 +
#' @family decisions
26 28
#'
27 29
#' @examples
28 30
#' # set seed for reproducibility

@@ -1,7 +1,7 @@
Loading
1 1
#' @include internal.R ConservationProblem-proto.R
2 2
NULL
3 3
4 -
#' Evaluate number of planning units selected.
4 +
#' Evaluate number of planning units selected
5 5
#'
6 6
#' Calculate the number of planning units selected within a solution
7 7
#' to a conservation planning [problem()].
@@ -37,7 +37,10 @@
Loading
37 37
#'
38 38
#' @name eval_n_summary
39 39
#'
40 -
#' @inherit eval_cost_summary seealso
40 +
#' @seealso
41 +
#' See [summaries] for an overview of all functions for summarizing solutions.
42 +
#'
43 +
#' @family summaries
41 44
#'
42 45
#' @examples
43 46
#' \dontrun{

@@ -23,7 +23,12 @@
Loading
23 23
#'   problem with multiple zones must be allocated to a management zone (i.e.
24 24
#'   zone allocation is mandatory).
25 25
#'
26 -
#' @inherit add_contiguity_constraints return seealso
26 +
#' @inherit add_contiguity_constraints return
27 +
#'
28 +
#' @seealso
29 +
#' See [constraints] for an overview of all functions for adding constraints.
30 +
#'
31 +
#' @family constraints
27 32
#'
28 33
#' @examples
29 34
#' # set seed for reproducibility

@@ -72,6 +72,12 @@
Loading
72 72
#'   unit in the solution. Specifically, the returned object is in the
73 73
#'   same format as the planning unit data in the argument to `x`.
74 74
#'
75 +
#' @seealso
76 +
#' See [importance] for an overview of all functions for evaluating
77 +
#' the importance of planning units selected in a solution.
78 +
#.
79 +
#' @family importances
80 +
#'
75 81
#' @examples
76 82
#' \dontrun{
77 83
#' # seed seed for reproducibility
@@ -184,8 +190,6 @@
Loading
184 190
#' value for cost-effective reserve planning. *Biological Conservation*,
185 191
#' 132: 336--342.
186 192
#'
187 -
#' @seealso [importance].
188 -
#'
189 193
#' @aliases eval_replacement_importance,ConservationProblem,numeric-method eval_replacement_importance,ConservationProblem,matrix-method eval_replacement_importance,ConservationProblem,data.frame-method eval_replacement_importance,ConservationProblem,Spatial-method eval_replacement_importance,ConservationProblem,sf-method eval_replacement_importance,ConservationProblem,Raster-method
190 194
#'
191 195
#' @name eval_replacement_importance

@@ -20,10 +20,15 @@
Loading
20 20
#' @param locked_out Object that determines which planning units that should be
21 21
#'   locked out. See the Data format section for more information.
22 22
#'
23 -
#' @inherit add_contiguity_constraints return seealso
23 +
#' @inherit add_contiguity_constraints return
24 24
#' @inherit add_locked_in_constraints details
25 25
#' @inheritSection add_locked_in_constraints Data format
26 26
#'
27 +
#' @seealso
28 +
#' See [constraints] for an overview of all functions for adding constraints.
29 +
#'
30 +
#' @family constraints
31 +
#'
27 32
#' @examples
28 33
#' # set seed for reproducibility
29 34
#' set.seed(500)

@@ -0,0 +1,30 @@
Loading
1 +
#include "package.h"
2 +
#include "optimization_problem.h"
3 +
4 +
// [[Rcpp::export]]
5 +
bool rcpp_apply_linear_constraints(SEXP x, double threshold, std::string sense,
6 +
                                   arma::sp_mat data) {
7 +
  // initialization
8 +
  Rcpp::XPtr<OPTIMIZATIONPROBLEM> ptr = Rcpp::as<Rcpp::XPtr<OPTIMIZATIONPROBLEM>>(x);
9 +
  std::size_t i = ptr->_rhs.size();
10 +
11 +
  // add model coefficients
12 +
  for (auto itr = data.begin(); itr != data.end(); ++itr) {
13 +
    ptr->_A_i.push_back(i);
14 +
    ptr->_A_j.push_back((itr.col() * ptr->_number_of_planning_units) +
15 +
                        itr.row());
16 +
    ptr->_A_x.push_back(*itr);
17 +
  }
18 +
19 +
  // add sense
20 +
  ptr->_sense.push_back(sense);
21 +
22 +
  // add rhs
23 +
  ptr->_rhs.push_back(threshold);
24 +
25 +
  // add row id
26 +
  ptr->_row_ids.push_back("lc");
27 +
28 +
  // return success
29 +
  return true;
30 +
}

@@ -65,7 +65,10 @@
Loading
65 65
#'
66 66
#' @name eval_cost_summary
67 67
#'
68 -
#' @seealso [problem()], [summaries].
68 +
#' @seealso
69 +
#' See [summaries] for an overview of all functions for summarizing solutions.
70 +
#'
71 +
#' @family summaries
69 72
#'
70 73
#' @examples
71 74
#' \dontrun{

@@ -46,13 +46,16 @@
Loading
46 46
#' @return Object (i.e. [`ConservationProblem-class`]) with the solver
47 47
#'  added to it.
48 48
#'
49 +
#' @seealso
50 +
#' See [solvers] for an overview of all functions for adding a solver.
51 +
#'
52 +
#' @family solvers
53 +
#'
49 54
#' @references
50 55
#' Forrest J and Lougee-Heimer R (2005) CBC User Guide. In Emerging theory,
51 56
#' Methods, and Applications (pp. 257--277). INFORMS, Catonsville, MD.
52 57
#' \doi{10.1287/educ.1053.0020}.
53 58
#'
54 -
#' @seealso [solvers].
55 -
#'
56 59
#' @examples
57 60
#' \dontrun{
58 61
#' # load data

@@ -12,87 +12,81 @@
Loading
12 12
#' This function was inspired by Faith (1992) and Rodrigues *et al.*
13 13
#' (2002).
14 14
#'
15 -
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
16 -
#'
17 -
#' @param budget `numeric` value specifying the maximum expenditure of
18 -
#'   the prioritization. For problems with multiple zones, the argument
19 -
#'   to `budget` can be a single `numeric` value to specify a budget
20 -
#'   for the entire solution or a `numeric` `vector` to specify
21 -
#'   a budget for each each management zone.
15 +
#' @inheritParams add_max_utility_objective
22 16
#'
23 17
#' @param tree [phylo()] object specifying a phylogenetic tree
24 18
#'   for the conservation features.
25 19
#'
26 -
#' @details A problem objective is used to specify the overall goal of the
27 -
#'   conservation planning problem. Please note that all conservation
28 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
29 -
#'   addition of objectives---failing to do so will return an error
30 -
#'   message when attempting to solve problem.
31 -
#'
32 -
#'   The maximum phylogenetic diversity objective finds the set of
33 -
#'   planning units that meets representation targets for a phylogenetic tree
34 -
#'   while staying within a fixed budget. If multiple solutions can meet all
35 -
#'   targets while staying within budget, the cheapest solution is chosen.
36 -
#'   Note that this objective is similar to the maximum
37 -
#'   features objective ([add_max_features_objective()]) in that it
38 -
#'   allows for both a budget and targets to be set for each feature. However,
39 -
#'   unlike the maximum feature objective, the aim of this objective is to
40 -
#'   maximize the total phylogenetic diversity of the targets met in the
41 -
#'   solution, so if multiple targets are provided for a single feature, the
42 -
#'   problem will only need to meet a single target for that feature
43 -
#'   for the phylogenetic benefit for that feature to be counted when
44 -
#'   calculating the phylogenetic diversity of the solution. In other words,
45 -
#'   for multi-zone problems, this objective does not aim to maximize the
46 -
#'   phylogenetic diversity in each zone, but rather this objective
47 -
#'   aims to maximize the phylogenetic diversity of targets that can be met
48 -
#'   through allocating planning units to any of the different zones in a
49 -
#'   problem. This can be useful for problems where targets pertain to the total
50 -
#'   amount held for each feature across multiple zones. For example,
51 -
#'   each feature might have a non-zero amount of suitable habitat in each
52 -
#'   planning unit when the planning units are assigned to a (i) not restored,
53 -
#'   (ii) partially restored, or (iii) completely restored management zone.
54 -
#'   Here each target corresponds to a single feature and can be met through
55 -
#'   the total amount of habitat in planning units present to the three
56 -
#'   zones.
20 +
#' @details
21 +
#' The maximum phylogenetic diversity objective finds the set of
22 +
#' planning units that meets representation targets for a phylogenetic tree
23 +
#' while staying within a fixed budget. If multiple solutions can meet all
24 +
#' targets while staying within budget, the cheapest solution is chosen.
25 +
#' Note that this objective is similar to the maximum
26 +
#' features objective ([add_max_features_objective()]) in that it
27 +
#' allows for both a budget and targets to be set for each feature. However,
28 +
#' unlike the maximum feature objective, the aim of this objective is to
29 +
#' maximize the total phylogenetic diversity of the targets met in the
30 +
#' solution, so if multiple targets are provided for a single feature, the
31 +
#' problem will only need to meet a single target for that feature
32 +
#' for the phylogenetic benefit for that feature to be counted when
33 +
#' calculating the phylogenetic diversity of the solution. In other words,
34 +
#' for multi-zone problems, this objective does not aim to maximize the
35 +
#' phylogenetic diversity in each zone, but rather this objective
36 +
#' aims to maximize the phylogenetic diversity of targets that can be met
37 +
#' through allocating planning units to any of the different zones in a
38 +
#' problem. This can be useful for problems where targets pertain to the total
39 +
#' amount held for each feature across multiple zones. For example,
40 +
#' each feature might have a non-zero amount of suitable habitat in each
41 +
#' planning unit when the planning units are assigned to a (i) not restored,
42 +
#' (ii) partially restored, or (iii) completely restored management zone.
43 +
#' Here each target corresponds to a single feature and can be met through
44 +
#' the total amount of habitat in planning units present to the three
45 +
#' zones.
57 46
#'
58 -
#'   The maximum phylogenetic diversity objective for the reserve design
59 -
#'   problem can be expressed mathematically for a set of planning units
60 -
#'   (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J}
61 -
#'   indexed by \eqn{j}{j}) as:
47 +
#' @section Mathematical formulation:
48 +
#' This objective can be expressed mathematically for a set of planning units
49 +
#' (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J}
50 +
#' indexed by \eqn{j}{j}) as:
62 51
#'
63 -
#'   \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
64 -
#'   \sum_{j = 1}^{J} m_b l_b \\
65 -
#'   \mathit{subject \space to} \\
66 -
#'   \sum_{i = 1}^{I} x_i r_{ij} \geq y_j t_j \forall j \in J \\
67 -
#'   m_b \leq y_j \forall j \in T(b) \\
68 -
#'   \sum_{i = 1}^{I} x_i c_i \leq B}{
69 -
#'   Maximize sum_i^I (-s * ci * xi) + sum_j^J (mb * lb) subject to sum_i^I
70 -
#'   (xi * rij) >= (yj * tj) for all j in J & mb <= yj for all j in T(b) &
71 -
#'   sum_i^I (xi * ci) <= B}
52 +
#' \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
53 +
#' \sum_{j = 1}^{J} m_b l_b \\
54 +
#' \mathit{subject \space to} \\
55 +
#' \sum_{i = 1}^{I} x_i r_{ij} \geq y_j t_j \forall j \in J \\
56 +
#' m_b \leq y_j \forall j \in T(b) \\
57 +
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
58 +
#' Maximize sum_i^I (-s * ci * xi) + sum_j^J (mb * lb) subject to sum_i^I
59 +
#' (xi * rij) >= (yj * tj) for all j in J & mb <= yj for all j in T(b) &
60 +
#' sum_i^I (xi * ci) <= B}
72 61
#'
73 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
74 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
75 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
76 -
#'   unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
77 -
#'   \eqn{j}{j}, \eqn{y_j}{yj} indicates if the solution has meet
78 -
#'   the target \eqn{t_j}{tj} for feature \eqn{j}{j}. Additionally,
79 -
#'   \eqn{T}{T} represents a phylogenetic tree containing features \eqn{j}{j}
80 -
#'   and has the branches \eqn{b} associated within lengths \eqn{l_b}{lb}.
81 -
#'   The binary variable \eqn{m_b}{mb} denotes if
82 -
#'   at least one feature associated with the branch \eqn{b}{b} has met its
83 -
#'   representation as indicated by \eqn{y_j}{yj}. For brevity, we denote
84 -
#'   the features \eqn{j}{j} associated with branch \eqn{b}{b} using
85 -
#'   \eqn{T(b)}{T(b)}. Finally, \eqn{B}{B} is the budget allocated for the
86 -
#'   solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
87 -
#'   \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
88 -
#'   will return a cheapest solution when there are multiple solutions that
89 -
#'   represent the same amount of all features within the budget.
62 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
63 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
64 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
65 +
#' unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
66 +
#' \eqn{j}{j}, \eqn{y_j}{yj} indicates if the solution has meet
67 +
#' the target \eqn{t_j}{tj} for feature \eqn{j}{j}. Additionally,
68 +
#' \eqn{T}{T} represents a phylogenetic tree containing features \eqn{j}{j}
69 +
#' and has the branches \eqn{b} associated within lengths \eqn{l_b}{lb}.
70 +
#' The binary variable \eqn{m_b}{mb} denotes if
71 +
#' at least one feature associated with the branch \eqn{b}{b} has met its
72 +
#' representation as indicated by \eqn{y_j}{yj}. For brevity, we denote
73 +
#' the features \eqn{j}{j} associated with branch \eqn{b}{b} using
74 +
#' \eqn{T(b)}{T(b)}. Finally, \eqn{B}{B} is the budget allocated for the
75 +
#' solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
76 +
#' \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
77 +
#' will return a cheapest solution when there are multiple solutions that
78 +
#' represent the same amount of all features within the budget.
90 79
#'
91 80
#' @section Notes:
92 81
#' In early versions, this function was named as the
93 82
#' `add_max_phylo_div_objective` function.
94 83
#'
95 -
#' @seealso [objectives], [branch_matrix()].
84 +
#' @seealso
85 +
#' See [objectives] for an overview of all functions for adding objectives.
86 +
#' Also, see [targets] for an overview of all functions for adding targets, and
87 +
#' [add_feature_weights()] to specify weights for different features.
88 +
#'
89 +
#' @family objectives
96 90
#'
97 91
#' @inherit add_min_set_objective return
98 92
#'

@@ -37,6 +37,12 @@
Loading
37 37
#' to real-world planning, and a research agenda for further refinement.
38 38
#' *Biological Conservation*, 93: 303--325.
39 39
#'
40 +
#' @seealso
41 +
#' See [importance] for an overview of all functions for evaluating
42 +
#' the importance of planning units selected in a solution.
43 +
#.
44 +
#' @family importances
45 +
#'
40 46
#' @examples
41 47
#' # seed seed for reproducibility
42 48
#' set.seed(600)
@@ -96,8 +102,6 @@
Loading
96 102
#'
97 103
#' }
98 104
#'
99 -
#' @inherit eval_replacement_importance seealso
100 -
#'
101 105
#' @aliases eval_ferrier_importance,ConservationProblem,numeric-method eval_ferrier_importance,ConservationProblem,matrix-method eval_ferrier_importance,ConservationProblem,data.frame-method eval_ferrier_importance,ConservationProblem,Spatial-method eval_ferrier_importance,ConservationProblem,sf-method eval_ferrier_importance,ConservationProblem,Raster-method
102 106
#'
103 107
#' @name eval_ferrier_importance

@@ -20,7 +20,12 @@
Loading
20 20
#' @param upper_limit `numeric` value specifying the maximum proportion
21 21
#'   of a planning unit that can be reserved (e.g. set to 0.8 for 80%).
22 22
#'
23 -
#' @inherit add_binary_decisions details return seealso
23 +
#' @inherit add_binary_decisions details return
24 +
#'
25 +
#' @seealso
26 +
#' See [decisions] for an overview of all functions for adding decisions.
27 +
#'
28 +
#' @family decisions
24 29
#'
25 30
#' @examples
26 31
#' # set seed for reproducibility

@@ -12,9 +12,7 @@
Loading
12 12
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
13 13
#'
14 14
#' @param targets Object that specifies the targets for each feature.
15 -
#'   See the Targets data format section for more information.
16 -
#'
17 -
#' @inherit add_manual_targets return seealso
15 +
#'   See the Targets format section for more information.
18 16
#'
19 17
#' @details
20 18
#' Targets are used to specify the minimum amount or proportion of a
@@ -40,31 +38,38 @@
Loading
40 38
#' management zone, or through allocating the planning units to different
41 39
#' combinations of management zones.
42 40
#'
43 -
#' @section Targets data format:
44 -
#' The targets for a problem can be specified using the following formats.
41 +
#' @section Targets format:
42 +
#' The `targets` for a problem can be specified using the following formats.
45 43
#'
46 44
#' \describe{
47 45
#'
48 -
#' \item{`numeric`}{`vector` of target values for each feature.
49 -
#'   Additionally, for convenience, this type of argument can be a single
50 -
#'   value to assign the same target to each feature. Note that this type of
51 -
#'   argument cannot be used to specify targets for problems with multiple
52 -
#'   zones.}
46 +
#' \item{`targets` as a `numeric` vector}{containing target values for each
47 +
#'   feature.
48 +
#'   Additionally, for convenience, this format can be a single
49 +
#'   value to assign the same target to each feature. Note that this format
50 +
#'   cannot be used to specify targets for problems with multiple zones.}
53 51
#'
54 -
#' \item{`matrix`}{containing a target for each feature in each zone.
52 +
#' \item{`targets` as a `matrix` object}{containing a target for each feature
53 +
#'   in each zone.
55 54
#'   Here, each row corresponds to a different feature in argument to
56 55
#'   `x`, each column corresponds to a different zone in argument to
57 56
#'   `x`, and each cell contains the target value for a given feature
58 57
#'   that the solution needs to secure in a given zone.}
59 58
#'
60 -
#' \item{`character`}{containing the names of fields (columns) in the
61 -
#'   feature data associated with the argument to `x` that contain
62 -
#'   targets. This type of argument can only be used when the
59 +
#' \item{`targets` as a `character` vector}{containing the names of fields
60 +
#'   (columns) in the feature data associated with the argument to `x` that
61 +
#'   contain targets. This format can only be used when the
63 62
#'   feature data associated with `x` is a `data.frame`.
64 63
#'   This argument must contain a field (column) name for each zone.}
65 64
#'
66 65
#' }
67 66
#'
67 +
#' @inherit add_manual_targets return
68 +
#'
69 +
#' @seealso
70 +
#' See [targets] for an overview of all functions for adding targets.
71 +
#'
72 +
#' @family targets
68 73
#'
69 74
#' @examples
70 75
#' # set seed for reproducibility

@@ -11,7 +11,7 @@
Loading
11 11
#' @inheritParams add_connectivity_penalties
12 12
#' @inheritParams eval_cost_summary
13 13
#'
14 -
#' @details`
14 +
#' @details
15 15
#' This summary statistic is comparable to the `Connectivity_In` metric
16 16
#' reported by the
17 17
#' [*Marxan* software](https://marxansolutions.org) (Ball *et al.* 2009).
@@ -53,7 +53,12 @@
Loading
53 53
#' prioritisation: Quantitative methods and computational tools. Eds Moilanen
54 54
#' A, Wilson KA, and Possingham HP. Oxford University Press, Oxford, UK.
55 55
#'
56 -
#' @seealso [problem()], [summaries], [add_connectivity_penalties()].
56 +
#' @seealso
57 +
#' See [summaries] for an overview of all functions for summarizing solutions.
58 +
#' Also, see [add_connectivity_penalties()] to penalize solutions with low
59 +
#' connectivity.
60 +
#'
61 +
#' @family summaries
57 62
#'
58 63
#' @examples
59 64
#' \dontrun{

@@ -4,7 +4,7 @@
Loading
4 4
#' Category vector
5 5
#'
6 6
#' Convert an object containing binary (`integer`) fields (columns) into a
7 -
#' `integer` `vector` indicating the column index where each row is
7 +
#' `integer` vector indicating the column index where each row is
8 8
#' `1`.
9 9
#'
10 10
#' @param x `matrix`, `data.frame`, [`Spatial-class`],
@@ -15,7 +15,7 @@
Loading
15 15
#'   value of zero. Also, note that in the argument to `x`, each row must
16 16
#'   contain only a single value equal to `1`.
17 17
#'
18 -
#' @return `integer` `vector`
18 +
#' @return `integer` vector.
19 19
#'
20 20
#' @seealso [base::max.col()]
21 21
#'

@@ -5,65 +5,61 @@
Loading
5 5
#'
6 6
#' Set the objective of a conservation planning [problem()] to
7 7
#' represent at least one instance of as many features as possible within a
8 -
#' given budget. This type of objective does not use targets, and feature
9 -
#' weights should be used instead to increase the representation of different
10 -
#' features in solutions.
8 +
#' given budget. This objective does not use targets, and feature
9 +
#' weights should be used instead to increase the representation of certain
10 +
#' features by a solution.
11 11
#'
12 12
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
13 13
#'
14 14
#' @param budget `numeric` value specifying the maximum expenditure of
15 15
#'   the prioritization. For problems with multiple zones, the argument
16 16
#'   to `budget` can be a single `numeric` value to specify a budget
17 -
#'   for the entire solution or a `numeric` `vector` to specify
17 +
#'   for the entire solution or a `numeric` vector to specify
18 18
#'   a budget for each each management zone.
19 19
#'
20 -
#' @details A problem objective is used to specify the overall goal of the
21 -
#'   conservation planning problem. Please note that all conservation
22 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
23 -
#'   addition of objectives---failing to do so will return an error
24 -
#'   message when attempting to solve problem.
25 -
#'
26 -
#'   The maximum coverage objective seeks to find the set of planning units that
27 -
#'   maximizes the number of represented features, while keeping cost within a
28 -
#'   fixed budget. Here, features are treated as being represented if
29 -
#'   the reserve system contains at least a single instance of a feature
30 -
#'   (i.e. an amount greater than 1). This formulation has often been
31 -
#'   used in conservation planning problems dealing with binary biodiversity
32 -
#'   data that indicate the presence/absence of suitable habitat
33 -
#'   (e.g. Church & Velle 1974). Additionally, weights can be used to favor the
34 -
#'   representation of certain features over other features (see
35 -
#'   [add_feature_weights()]). Check out the
36 -
#'   [add_max_features_objective()] for a more
37 -
#'   generalized formulation which can accommodate user-specified representation
38 -
#'   targets.
39 -
#'
40 -
#'   This formulation is based on the historical maximum coverage reserve
41 -
#'   selection formulation (Church & Velle 1974; Church *et al.* 1996).
42 -
#'   The maximum coverage objective for the reserve design problem can be
43 -
#'   expressed mathematically for a set of planning units (\eqn{I}{I} indexed by
44 -
#'   \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
45 -
#'
46 -
#'   \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
47 -
#'   \sum_{j = 1}^{J} y_j w_j \\
48 -
#'   \mathit{subject \space to} \\
49 -
#'   \sum_{i = 1}^{I} x_i r_{ij} \geq y_j \times 1 \forall j \in J \\
50 -
#'   \sum_{i = 1}^{I} x_i c_i \leq B}{
51 -
#'   Maximize sum_i^I (-s * ci * xi) + sum_j^J (yj * wj) subject to
52 -
#'   sum_i^I (xi * rij) >= (yj * 1) for all j in J &
53 -
#'   sum_i^I (xi * ci) <= B}
54 -
#'
55 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
56 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
57 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
58 -
#'   unit \eqn{i}{i}, \eqn{y_j}{yj} indicates if the solution has meet
59 -
#'   the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and \eqn{w_j}{wj} is the
60 -
#'   weight for feature \eqn{j}{j} (defaults to 1 for all features; see
61 -
#'   [add_feature_weights()] to specify weights). Additionally,
62 -
#'   \eqn{B}{B} is the budget allocated for the solution, \eqn{c_i}{ci} is the
63 -
#'   cost of planning unit \eqn{i}{i}, and \eqn{s}{s} is a scaling factor used
64 -
#'   to shrink the costs so that the problem will return a cheapest solution
65 -
#'   when there are multiple solutions that represent the same amount of all
66 -
#'   features within the budget.
20 +
#' @details
21 +
#' The maximum coverage objective seeks to find the set of planning units that
22 +
#' maximizes the number of represented features, while keeping cost within a
23 +
#' fixed budget. Here, features are treated as being represented if
24 +
#' the reserve system contains at least a single instance of a feature
25 +
#' (i.e. an amount greater than 1). This formulation has often been
26 +
#' used in conservation planning problems dealing with binary biodiversity
27 +
#' data that indicate the presence/absence of suitable habitat
28 +
#' (e.g. Church & Velle 1974). Additionally, weights can be used to favor the
29 +
#' representation of certain features over other features (see
30 +
#' [add_feature_weights()]). Check out the
31 +
#' [add_max_features_objective()] for a more
32 +
#' generalized formulation which can accommodate user-specified representation
33 +
#' targets.
34 +
#'
35 +
#' @section Mathematical formulation:
36 +
#' This objective is based on the maximum coverage reserve
37 +
#' selection problem (Church & Velle 1974; Church *et al.* 1996).
38 +
#' The maximum coverage objective for the reserve design problem can be
39 +
#' expressed mathematically for a set of planning units (\eqn{I}{I} indexed by
40 +
#' \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
41 +
#'
42 +
#' \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
43 +
#' \sum_{j = 1}^{J} y_j w_j \\
44 +
#' \mathit{subject \space to} \\
45 +
#' \sum_{i = 1}^{I} x_i r_{ij} \geq y_j \times 1 \forall j \in J \\
46 +
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
47 +
#' Maximize sum_i^I (-s * ci * xi) + sum_j^J (yj * wj) subject to
48 +
#' sum_i^I (xi * rij) >= (yj * 1) for all j in J &
49 +
#' sum_i^I (xi * ci) <= B}
50 +
#'
51 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
52 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
53 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
54 +
#' unit \eqn{i}{i}, \eqn{y_j}{yj} indicates if the solution has meet
55 +
#' the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and \eqn{w_j}{wj} is the
56 +
#' weight for feature \eqn{j}{j} (defaults to 1 for all features; see
57 +
#' [add_feature_weights()] to specify weights). Additionally,
58 +
#' \eqn{B}{B} is the budget allocated for the solution, \eqn{c_i}{ci} is the
59 +
#' cost of planning unit \eqn{i}{i}, and \eqn{s}{s} is a scaling factor used
60 +
#' to shrink the costs so that the problem will return a cheapest solution
61 +
#' when there are multiple solutions that represent the same amount of all
62 +
#' features within the budget.
67 63
#'
68 64
#' @section Notes:
69 65
#' In early versions (< 3.0.0.0), the mathematical formulation
@@ -79,7 +75,13 @@
Loading
79 75
#' Church RL, Stoms DM, and Davis FW (1996) Reserve selection as a maximum
80 76
#' covering location problem. *Biological Conservation*, 76: 105--112.
81 77
#'
82 -
#' @inherit add_max_features_objective seealso return
78 +
#' @inherit add_max_features_objective return
79 +
#'
80 +
#' @seealso
81 +
#' See [objectives] for an overview of all functions for adding objectives.
82 +
#' Also, see [add_feature_weights()] to specify weights for different features.
83 +
#'
84 +
#' @family objectives
83 85
#'
84 86
#' @examples
85 87
#' # load data

@@ -26,7 +26,7 @@
Loading
26 26
#'
27 27
#' @param data `character`, `numeric`,
28 28
#'   [`Raster-class`], `matrix`, or `Matrix` object
29 -
#'   containing the data used to penalize solutions. Planning units that are
29 +
#'   containing the values used to penalize solutions. Planning units that are
30 30
#'   associated with higher data values are penalized more strongly
31 31
#'   in the solution. See the Data format section for more information.
32 32
#'
@@ -35,76 +35,83 @@
Loading
35 35
#' to the sum of the penalty values associated with each planning unit,
36 36
#' weighted by status of each planning unit in the solution.
37 37
#'
38 -
#' Specifically, the linear penalties are calculated using the following
39 -
#' equations.
40 -
#' Let \eqn{I} denote the set of planning units
41 -
#' (indexed by \eqn{i}), \eqn{Z} the set of management zones (indexed by
42 -
#' \eqn{z}), and \eqn{X_{iz}}{Xiz} the decision variable for allocating
43 -
#' planning unit \eqn{i} to zone \eqn{z} (e.g. with binary
44 -
#' values one indicating if planning unit is allocated or not). Also, let
45 -
#' \eqn{P_z} represent the penalty scaling value for zones
46 -
#' \eqn{z \in Z}{z in Z} (argument to `penalty`), and
47 -
#' \eqn{D_{iz}}{Diz} the penalty data for allocating planning unit
48 -
#' \eqn{i \in I}{i in I} to zones \eqn{z \in Z}{z in Z} (argument to
49 -
#' `data` if supplied as a `matrix` object).
50 -
#'
51 -
#' \deqn{
52 -
#' \sum_{i}^{I} \sum_{z}^{Z} P_z \times D_{iz} \times X_{iz}
53 -
#' }{
54 -
#' sum_i^I sum_z^Z (Pz * Diz * Xiz)
55 -
#' }
56 -
#'
57 -
#' Note that when the problem objective is to maximize some measure of
58 -
#' benefit and not minimize some measure of cost, the term \eqn{P_z} is
59 -
#' replaced with \eqn{-P_z}.
60 -
#'
61 38
#' @section Data format:
62 39
#'
63 40
#' The argument to `data` can be specified using the following formats.
64 41
#'
65 42
#' \describe{
66 43
#'
67 -
#' \item{`character`}{field (column) name(s) that contain the data for
68 -
#'   penalizing planning units. This type of argument is only
44 +
#' \item{`data` as `character` vector}{containing field (column) name(s) that
45 +
#'   contain penalty values for planning units. This format is only
69 46
#'   compatible if the planning units in the argument to `x` are a
70 47
#'   [`Spatial-class`], [sf::sf()], or
71 48
#'   `data.frame` object. The fields (columns) must have `numeric`
72 49
#'   values, and must not contain any missing (`NA`) values.
73 -
#'   For problems involving multiple zones, the argument to `data` must
50 +
#'   For problems that contain a single zone, the argument to `data` must
51 +
#'   contain a single field name. Otherwise, for problems that
52 +
#'   contain multiple zones, the argument to `data` must
74 53
#'   contain a field name for each zone.}
75 54
#'
76 -
#' \item{`numeric`}{`vector` containing the data for penalizing
77 -
#'   each planning unit. These values must not contain any missing
78 -
#'   (`NA`) values. Note that this type of argument is only available
55 +
#' \item{`data` as a `numeric` vector}{containing values for
56 +
#'   planning units. These values must not contain any missing
57 +
#'   (`NA`) values. Note that this format is only available
79 58
#'   for planning units that contain a single zone.}
80 59
#'
81 -
#' \item{[`Raster-class`]}{containing the data for
82 -
#'   penalizing planning units. This type of argument is only
60 +
#' \item{`data` as a `matrix`/`Matrix` object}{containing `numeric` values
61 +
#'   that specify data for each planning unit.
62 +
#'   Each row corresponds to a planning unit, each column corresponds to a
63 +
#'   zone, and each cell indicates the data for penalizing a planning unit
64 +
#'   when it is allocated to a given zone.}
65 +
#'
66 +
#' \item{`data` as a [`Raster-class`] object}{containing values for planning
67 +
#'   units. This format is only
83 68
#'   compatible if the planning units in the argument to `x` are
84 69
#'   [`Spatial-class`], [sf::sf()], or
85 -
#'   or [`Raster-class`] (i.e. they are in a spatially
86 -
#'   referenced format).
70 +
#'   [`Raster-class`] objects.
87 71
#'   If the planning unit data are a [`Spatial-class`] or
88 -
#'   [sf::sf()] object, then the
89 -
#'   penalty `data` are calculated by overlaying the planning units with
90 -
#'   the argument to `data` and calculating the sum of the values.
91 -
#'   If the planning unit data are in the
92 -
#'   [`Raster-class`] then the penalty `data` are
93 -
#'   calculated by extracting the cell values (note that the
94 -
#'   planning unit data and the argument to code{data} must have exactly
95 -
#'   the same dimensionality, extent, and missingness).
72 +
#'   [sf::sf()] object, then the values are calculated by overlaying the
73 +
#'   planning units with the argument to `data` and calculating the sum of the
74 +
#'   values associated with each planning unit.
75 +
#'   If the planning unit data are a
76 +
#'   [`Raster-class`] object then the values are calculated by extracting the
77 +
#'   cell
78 +
#'   values (note that the planning unit data and the argument to `data` must
79 +
#'   have exactly the same dimensionality, extent, and missingness).
96 80
#'   For problems involving multiple zones, the argument to `data` must
97 81
#'   contain a layer for each zone.}
98 82
#'
99 -
#' \item{`matrix`, `Matrix`}{containing `numeric` values
100 -
#'   that specify data for penalizing each planning unit.
101 -
#'   Each row corresponds to a planning unit, each column corresponds to a
102 -
#'   zone, and each cell indicates the data for penalizing a planning unit
103 -
#'   when it is allocated to a given zone.}
83 +
#' }
84 +
#'
85 +
#' @section Mathematical formulation:
86 +
#' The linear penalties are implemented using the following
87 +
#' equations.
88 +
#' Let \eqn{I} denote the set of planning units
89 +
#' (indexed by \eqn{i}), \eqn{Z} the set of management zones (indexed by
90 +
#' \eqn{z}), and \eqn{X_{iz}}{Xiz} the decision variable for allocating
91 +
#' planning unit \eqn{i} to zone \eqn{z} (e.g. with binary
92 +
#' values indicating if each planning unit is allocated or not). Also, let
93 +
#' \eqn{P_z} represent the penalty scaling value for zones
94 +
#' \eqn{z \in Z}{z in Z} (argument to `penalty`), and
95 +
#' \eqn{D_{iz}}{Diz} the penalty data for allocating planning unit
96 +
#' \eqn{i \in I}{i in I} to zones \eqn{z \in Z}{z in Z} (argument to
97 +
#' `data`, if supplied as a `matrix` object).
104 98
#'
99 +
#' \deqn{
100 +
#' \sum_{i}^{I} \sum_{z}^{Z} P_z \times D_{iz} \times X_{iz}
101 +
#' }{
102 +
#' sum_i^I sum_z^Z (Pz * Diz * Xiz)
105 103
#' }
106 104
#'
107 -
#' @inherit add_linear_penalties return seealso
105 +
#' Note that when the problem objective is to maximize some measure of
106 +
#' benefit and not minimize some measure of cost, the term \eqn{P_z} is
107 +
#' replaced with \eqn{-P_z}.
108 +
#'
109 +
#' @inherit add_boundary_penalties return
110 +
#'
111 +
#' @seealso
112 +
#' See [penalties] for an overview of all functions for adding penalties.
113 +
#'
114 +
#' @family penalties
108 115
#'
109 116
#' @examples
110 117
#' # set seed for reproducibility

@@ -4,50 +4,52 @@
Loading
4 4
#' Add minimum set objective
5 5
#'
6 6
#' Set the objective of a conservation planning [problem()] to
7 -
#' minimize the cost of the solution whilst ensuring that all targets are met.
7 +
#' minimize the cost of the solution whilst ensuring that all [targets] are met.
8 8
#' This objective is similar to that used in
9 9
#' *Marxan* and is detailed in Rodrigues *et al.* (2000).
10 10
#'
11 11
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
12 12
#'
13 -
#' @details A problem objective is used to specify the overall goal of the
14 -
#'   conservation planning problem. Please note that all conservation
15 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
16 -
#'   addition of objectives---failing to do so will return an error
17 -
#'   message when attempting to solve problem.
18 -
#'
19 -
#'   In the context of systematic reserve design, the minimum set objective
20 -
#'   seeks to find the set of planning units that minimizes the overall cost of
21 -
#'   a reserve network, while meeting a set of representation targets for the
22 -
#'   conservation features. This objective is equivalent to a simplified
23 -
#'   *Marxan* reserve design problem with the Boundary Length Modifier
24 -
#'   (BLM) set to zero.
25 -
#'
26 -
#'   The minimum set objective for the reserve design problem can be expressed
27 -
#'   mathematically for a set of planning units (\eqn{I}{I} indexed by
28 -
#'   \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
29 -
#'
30 -
#'   \deqn{\mathit{Minimize} \space \sum_{i = 1}^{I} x_i c_i \\
31 -
#'   \mathit{subject \space to} \\
32 -
#'   \sum_{i = 1}^{I} x_i r_{ij} \geq T_j \space \forall \space j \in J}{
33 -
#'   Minimize sum_i^I (xi * ci) subject to sum_i^I (xi * rij) >= Tj for all
34 -
#'   j in J}
35 -
#'
36 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
37 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
38 -
#'   (0)), \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i},
39 -
#'   \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning unit
40 -
#'   \eqn{i}{i}, and \eqn{T_j}{Tj} is the target for feature \eqn{j}{j}. The
41 -
#'   first term is the objective function and the second is the set of
42 -
#'   constraints. In words this says find the set of planning units that meets
43 -
#'   all the representation targets while minimizing the overall cost.
13 +
#' @details
14 +
#' The minimum set objective -- in the the context of systematic reserve
15 +
#' design --  seeks to find the set of planning units that minimizes the
16 +
#' overall cost of a reserve network, while meeting a set of representation
17 +
#' targets for the conservation features. This objective is equivalent to a
18 +
#' simplified *Marxan* reserve design problem with the Boundary Length Modifier
19 +
#' (BLM) set to zero. The difference between this objective and the
20 +
#' *Marxan* software is that the targets for the features will always be met
21 +
#' (and as such it does not use Species Penalty Factors).
22 +
#'
23 +
#' @section Mathematical formulation:
24 +
#' This objective can be expressed
25 +
#' mathematically for a set of planning units (\eqn{I}{I} indexed by
26 +
#' \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
27 +
#'
28 +
#' \deqn{\mathit{Minimize} \space \sum_{i = 1}^{I} x_i c_i \\
29 +
#' \mathit{subject \space to} \\
30 +
#' \sum_{i = 1}^{I} x_i r_{ij} \geq T_j \space \forall \space j \in J}{
31 +
#' Minimize sum_i^I (xi * ci) subject to sum_i^I (xi * rij) >= Tj for all
32 +
#' j in J}
33 +
#'
34 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
35 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
36 +
#' (0)), \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i},
37 +
#' \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning unit
38 +
#' \eqn{i}{i}, and \eqn{T_j}{Tj} is the target for feature \eqn{j}{j}. The
39 +
#' first term is the objective function and the second is the set of
40 +
#' constraints. In words this says find the set of planning units that meets
41 +
#' all the representation targets while minimizing the overall cost.
44 42
#'
45 43
#' @references
46 44
#' Rodrigues AS, Cerdeira OJ, and Gaston KJ (2000) Flexibility,
47 45
#' efficiency, and accountability: adapting reserve selection algorithms to
48 46
#' more complex conservation problems. *Ecography*, 23: 565--574.
49 47
#'
50 -
#' @seealso [objectives], [targets].
48 +
#' @seealso
49 +
#' See [objectives] for an overview of all functions for adding objectives.
50 +
#' Also see [targets] for an overview of all functions for adding targets.
51 +
#'
52 +
#' @family objectives
51 53
#'
52 54
#' @return Object (i.e. [`ConservationProblem-class`]) with the objective
53 55
#'   added to it.

@@ -12,10 +12,15 @@
Loading
12 12
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
13 13
#'
14 14
#' @param targets Object that specifies the targets for each feature.
15 -
#'   See the Targets data format section for more information.
15 +
#'   See the Targets format section for more information.
16 16
#'
17 -
#' @inherit add_absolute_targets details return seealso
18 -
#' @inheritSection add_absolute_targets Targets data format
17 +
#' @inherit add_absolute_targets details return
18 +
#' @inheritSection add_absolute_targets Targets format
19 +
#'
20 +
#' @seealso
21 +
#' See [targets] for an overview of all functions for adding targets.
22 +
#'
23 +
#' @family targets
19 24
#'
20 25
#' @examples
21 26
#' # set seed for reproducibility

@@ -1,7 +1,7 @@
Loading
1 1
#' @include internal.R pproto.R ConservationProblem-proto.R zones.R add_manual_targets.R
2 2
NULL
3 3
4 -
#' Add manually specified bounds constraints
4 +
#' Add manually specified bound constraints
5 5
#'
6 6
#' Add constraints to a conservation planning [problem()] to ensure
7 7
#' that the planning unit values (e.g. proportion, binary) in a solution
@@ -18,7 +18,8 @@
Loading
18 18
#'   See the Data format section for more information.
19 19
#'
20 20
#' @section Data format:
21 -
#' The argument to `data` must contain the following fields (columns):
21 +
#' The argument to `data` should be a `data.frame` with the following fields
22 +
#' (columns):
22 23
#'
23 24
#' \describe{
24 25
#'
@@ -38,7 +39,12 @@
Loading
38 39
#'
39 40
#' }
40 41
#'
41 -
#' @inherit add_contiguity_constraints return seealso
42 +
#' @inherit add_contiguity_constraints return
43 +
#'
44 +
#' @seealso
45 +
#' See [constraints] for an overview of all functions for adding constraints.
46 +
#'
47 +
#' @family constraints
42 48
#'
43 49
#' @examples
44 50
#' # set seed for reproducibility
@@ -125,7 +131,6 @@
Loading
125 131
#' spplot(s4, zcol = c("solution", "solution_bounded"), axes = FALSE,
126 132
#'        box = FALSE)
127 133
#' }
128 -
#' @seealso [constraints].
129 134
#'
130 135
#' @name add_manual_bounded_constraints
131 136
#'

@@ -36,6 +36,12 @@
Loading
36 36
#'
37 37
#' @inherit eval_replacement_importance return
38 38
#'
39 +
#' @seealso
40 +
#' See [importance] for an overview of all functions for evaluating
41 +
#' the importance of planning units selected in a solution.
42 +
#.
43 +
#' @family importances
44 +
#'
39 45
#' @examples
40 46
#' \dontrun{
41 47
#' # seed seed for reproducibility
@@ -98,8 +104,6 @@
Loading
98 104
#' areas for conserving diversity using British birds.
99 105
#' *Conservation Biology*, 10: 155--174.
100 106
#'
101 -
#' @inherit eval_replacement_importance seealso
102 -
#'
103 107
#' @aliases eval_rare_richness_importance,ConservationProblem,numeric-method eval_rare_richness_importance,ConservationProblem,matrix-method eval_rare_richness_importance,ConservationProblem,data.frame-method eval_rare_richness_importance,ConservationProblem,Spatial-method eval_rare_richness_importance,ConservationProblem,sf-method eval_rare_richness_importance,ConservationProblem,Raster-method
104 108
#'
105 109
#' @name eval_rare_richness_importance

@@ -24,7 +24,12 @@
Loading
24 24
#' run time and solution quality of different solvers when applied to
25 25
#' different sized datasets.
26 26
#'
27 -
#' @inherit add_gurobi_solver seealso return references
27 +
#' @inherit add_gurobi_solver return references
28 +
#'
29 +
#' @seealso
30 +
#' See [solvers] for an overview of all functions for adding a solver.
31 +
#'
32 +
#' @family solvers
28 33
#'
29 34
#' @references
30 35
#' Ralphs TK and Güzelsoy M (2005) The SYMPHONY callable library for mixed

@@ -13,53 +13,53 @@
Loading
13 13
#'
14 14
#' @inheritParams add_max_features_objective
15 15
#'
16 -
#' @details A problem objective is used to specify the overall goal of the
17 -
#'   conservation planning problem. Please note that all conservation
18 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
19 -
#'   addition of objectives---failing to do so will return an error
20 -
#'   message when attempting to solve problem.
16 +
#' @details
17 +
#' The minimum largest shortfall objective aims to
18 +
#' find the set of planning units that minimize the largest
19 +
#' shortfall for any of the representation targets---that is, the fraction of
20 +
#' each target that remains unmet---for as many features as possible while
21 +
#' staying within a fixed budget. This objective is different from the
22 +
#' minimum shortfall objective ([add_min_shortfall_objective()]) because this
23 +
#' objective minimizes the largest (maximum) target shortfall,
24 +
#' whereas the minimum shortfall objective
25 +
#' minimizes the total (weighted sum) of the target shortfalls.
26 +
#' Note that this objective function is not compatible with feature weights
27 +
#' ([add_feature_weights()]).
21 28
#'
22 -
#'   The minimum largest shortfall objective aims to
23 -
#'   find the set of planning units that minimize the largest
24 -
#'   shortfall for any of the representation targets---that is, the fraction of
25 -
#'   each target that remains unmet---for as many features as possible while
26 -
#'   staying within a fixed budget. This objective is different from the
27 -
#'   minimum shortfall objective ([add_min_shortfall_objective()]) because this
28 -
#'   objective minimizes the largest (maximum) target shortfall,
29 -
#'   whereas the minimum shortfall objective
30 -
#'   minimizes the total (weighted sum) of the target shortfalls.
31 -
#'   Note that this objective function is not compatible with feature weights
32 -
#'   ([add_feature_weights()]).
29 +
#' @section Mathematical formulation:
30 +
#' This objective can be expressed mathematically for a set of planning units
31 +
#' (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J}
32 +
#' indexed by \eqn{j}{j}) as:
33 33
#'
34 -
#'   The minimum largest shortfall objective for the reserve design problem can
35 -
#'   be expressed mathematically for a set of planning units (\eqn{I}{I}
36 -
#'   indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by
37 -
#'   \eqn{j}{j}) as:
34 +
#' \deqn{\mathit{Minimize} \space l \\
35 +
#' \mathit{subject \space to} \\
36 +
#' \sum_{i = 1}^{I} x_i r_{ij} + y_j \geq t_j \forall j \in J \\
37 +
#' l \geq \frac{y_j}{t_j} \forall j \in J \\
38 +
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
39 +
#' Minimize l subject to
40 +
#' sum_i^I (xi * rij) + yj >= tj for all j in J &
41 +
#' l >= (yj / tj) for all j in J &
42 +
#' sum_i^I (xi * ci) <= B}
38 43
#'
39 -
#'   \deqn{\mathit{Minimize} \space l \\
40 -
#'   \mathit{subject \space to} \\
41 -
#'   \sum_{i = 1}^{I} x_i r_{ij} + y_j \geq t_j \forall j \in J \\
42 -
#'   l \geq \frac{y_j}{t_j} \forall j \in J \\
43 -
#'   \sum_{i = 1}^{I} x_i c_i \leq B}{
44 -
#'   Minimize l subject to
45 -
#'   sum_i^I (xi * rij) + yj >= tj for all j in J &
46 -
#'   l >= (yj / tj) for all j in J &
47 -
#'   sum_i^I (xi * ci) <= B}
44 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
45 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
46 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
47 +
#' unit \eqn{i}{i}, and \eqn{t_j}{tj} is the representation target for feature
48 +
#' \eqn{j}{j}.
49 +
#' Additionally, \eqn{y_j}{yj} denotes the target shortfall for
50 +
#' the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and
51 +
#' \eqn{l}{l} denotes the largest target shortfall.
52 +
#' Furthermore, \eqn{B}{B} is the budget allocated for the solution,
53 +
#' \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}. Note that
54 +
#' \eqn{y_j}{yj} and \eqn{s} are continuous variables bounded between zero
55 +
#' and infinity.
48 56
#'
49 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
50 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
51 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
52 -
#'   unit \eqn{i}{i}, and \eqn{t_j}{tj} is the representation target for feature
53 -
#'   \eqn{j}{j}.
54 -
#'   Additionally, \eqn{y_j}{yj} denotes the target shortfall for
55 -
#'   the target \eqn{t_j}{tj} for feature \eqn{j}{j}, and
56 -
#'   \eqn{l}{l} denotes the largest target shortfall.
57 -
#'   Furthermore, \eqn{B}{B} is the budget allocated for the solution,
58 -
#'   \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}. Note that
59 -
#'   \eqn{y_j}{yj} and \eqn{s} are continuous variables bounded between zero
60 -
#'   and infinity.
57 +
#' @seealso
58 +
#' See [objectives] for an overview of all functions for adding objectives.
59 +
#' Also, see [targets] for an overview of all functions for adding targets, and
60 +
#' [add_feature_weights()] to specify weights for different features.
61 61
#'
62 -
#' @seealso [objectives].
62 +
#' @family objectives
63 63
#'
64 64
#' @inherit add_min_set_objective return
65 65
#'

@@ -0,0 +1,392 @@
Loading
1 +
#' @include internal.R
2 +
NULL
3 +
4 +
#' Add linear constraints
5 +
#'
6 +
#' Add constraints to a conservation planning [problem()] to ensure
7 +
#' that all selected planning units meet certain criteria.
8 +
#'
9 +
#' @inheritParams add_contiguity_constraints
10 +
#'
11 +
#' @param sense `character` sense for the constraint. Available
12 +
#'  options include `">="`, `"<="`, or `"="` values.
13 +
#'
14 +
#' @param threshold `numeric` value.
15 +
#'   This threshold value is also known as a "right-hand-side" value
16 +
#'   per integer programming terminology.
17 +
#'
18 +
#' @param data `character`, `numeric`,
19 +
#'   [`Raster-class`], `matrix`, or `Matrix` object
20 +
#'   containing the constraint values.
21 +
#'   These constraint values are also known as constraint coefficients
22 +
#'   per integer programming terminology.
23 +
#'   See the Data format section for more information.
24 +
#'
25 +
#' @inherit add_contiguity_constraints return
26 +
#'
27 +
#' @inheritSection add_linear_penalties Data format
28 +
#'
29 +
#' @details
30 +
#' This function adds general purpose constraints that can be used to
31 +
#' ensure that solutions meet certain criteria
32 +
#' (see Examples section below for details).
33 +
#' For example, these constraints can be used to add multiple budgets.
34 +
#' They can also be used to ensure that the total number of planning units
35 +
#' allocated to a certain administrative area (e.g. country) does not exceed
36 +
#' a certain threshold (e.g. 30% of its total area). Furthermore,
37 +
#' they can also be used to ensure that features have a minimal level
38 +
#' of representation (e.g. 30%) when using an objective
39 +
#' function that aims to enhance feature representation given a budget
40 +
#' (e.g. [add_min_shortfall_objective()]).
41 +
#'
42 +
#' @section Mathematical formulation:
43 +
#' The linear constraints are implemented using the following
44 +
#' equation.
45 +
#' Let \eqn{I} denote the set of planning units
46 +
#' (indexed by \eqn{i}), \eqn{Z} the set of management zones (indexed by
47 +
#' \eqn{z}), and \eqn{X_{iz}}{Xiz} the decision variable for allocating
48 +
#' planning unit \eqn{i} to zone \eqn{z} (e.g. with binary
49 +
#' values indicating if each planning unit is allocated or not). Also, let
50 +
#' \eqn{D_{iz}}{Diz} denote the constraint data associated with
51 +
#' planning units \eqn{i \in I}{i in I} for zones \eqn{z \in Z}{z in Z}
52 +
#' (argument to `data`, if supplied as a `matrix` object),
53 +
#' \eqn{\theta} denote the constraint sense
54 +
#' (argument to `sense`, e.g. \eqn{<=}), and \eqn{t} denote the constraint
55 +
#' threshold (argument to `threshold`).
56 +
#'
57 +
#' \deqn{
58 +
#' \sum_{i}^{I} \sum_{z}^{Z} (D_{iz} \times X_{iz}) \space \theta \space t
59 +
#' }{
60 +
#' sum_i^I sum (Diz * Xiz) \theta t
61 +
#' }
62 +
#'
63 +
#' @seealso
64 +
#' See [constraints] for an overview of all functions for adding constraints.
65 +
#'
66 +
#' @family constraints
67 +
#'
68 +
#' @examples
69 +
#' # load data
70 +
#' data(sim_pu_raster, sim_features)
71 +
#'
72 +
#' \dontrun{
73 +
#' # create a baseline problem with minimum shortfall objective
74 +
#' p0 <- problem(sim_pu_raster, sim_features) %>%
75 +
#'       add_min_shortfall_objective(1800) %>%
76 +
#'       add_relative_targets(0.2) %>%
77 +
#'       add_binary_decisions() %>%
78 +
#'       add_default_solver(verbose = FALSE)
79 +
#'
80 +
#' # solve problem
81 +
#' s0 <- solve(p0)
82 +
#'
83 +
#' # plot solution
84 +
#' plot(s0, main = "solution", axes = FALSE, box = FALSE)
85 +
#'
86 +
#' # now let's create some modified versions of this baseline problem by
87 +
#' # adding additional criteria using linear constraints
88 +
#'
89 +
#' # first, let's create a modified version of p0 that contains
90 +
#' # an additional budget of 1600 based on a secondary cost dataset
91 +
#'
92 +
#' # create a secondary cost dataset by simulating values
93 +
#' sim_pu_raster2 <- simulate_cost(sim_pu_raster)
94 +
#'
95 +
#' # plot the primary cost dataset (sim_pu_raster) and
96 +
#' # the secondary cost dataset (sim_pu_raster2)
97 +
#' plot(stack(sim_pu_raster, sim_pu_raster2),
98 +
#'      main = c("sim_pu_raster", "sim_pu_raster2"),
99 +
#'      axes = FALSE, box = FALSE)
100 +
#'
101 +
#' # create a modified version of p0 with linear constraints that
102 +
#' # specify that the planning units in the solution must not have
103 +
#' # values in sim_pu_raster2 that sum to a total greater than 1600
104 +
#' p1 <- p0 %>%
105 +
#'       add_linear_constraints(threshold = 1600,
106 +
#'                              sense = "<=",
107 +
#'                              data = sim_pu_raster2)
108 +
#'
109 +
#' # solve problem
110 +
#' s1 <- solve(p1)
111 +
#'
112 +
#' # plot solutions s1 and s2 to compare them
113 +
#' plot(stack(s0, s1), main = c("s0", "s1"), axes = FALSE, box = FALSE)
114 +
#'
115 +
#' # second, let's create a modified version of p0 that contains
116 +
#' # additional constraints to ensure that each feature has
117 +
#' # at least 8% of its overall distribution represented by the solution
118 +
#'
119 +
#' # to achieve this, we need to calculate the total amount of each feature
120 +
#' # within the planning units so we can, in turn, set the constraint thresholds
121 +
#' feat_abund <- feature_abundances(p0)$absolute_abundance
122 +
#'
123 +
#' # create a modified version of p0 with additional constraints for each
124 +
#' # feature to specify that the planning units in the solution must
125 +
#' # secure at least 8% of the total abundance for each feature
126 +
#' p2 <- p0
127 +
#' for (i in seq_len(nlayers(sim_features))) {
128 +
#'   p2 <- p2 %>%
129 +
#'         add_linear_constraints(threshold = feat_abund[i] * 0.08,
130 +
#'                                sense = ">=",
131 +
#'                                data = sim_features[[i]])
132 +
#' }
133 +
#'
134 +
#' # overall, p2 could be described as an optimization problem
135 +
#' # that maximizes feature representation as much as possible
136 +
#' # towards securing 20% of the total amount of each feature,
137 +
#' # whilst ensuring that (i) the total cost of the solution does
138 +
#' # not exceed 1800 (per cost values in sim_pu_raster) and (ii)
139 +
#' # the solution secures at least 8% of the total amount of each feature
140 +
#' # (if 20% is not possible due to the budget)
141 +
#'
142 +
#' # solve problem
143 +
#' s2 <- solve(p2)
144 +
#'
145 +
#' # plot solutions s0 and s2 to compare them
146 +
#' plot(stack(s0, s2), main = c("s1", "s2"), axes = FALSE, box = FALSE)
147 +
#'
148 +
#' # third, let's create a modified version of p0 that contains
149 +
#' # additional constraints to ensure that the solution equitably
150 +
#' # distributes conservation effort across different administrative areas
151 +
#' # (e.g. countries) within the study region
152 +
#'
153 +
#' # to begin with, we will simulate a dataset describing the spatial extent of
154 +
#' # four different administrative areas across the study region
155 +
#' sim_admin <- sim_pu_raster
156 +
#' sim_admin <- aggregate(sim_admin, fact = 5)
157 +
#' values(sim_admin) <- seq_along(values(sim_admin))
158 +
#' sim_admin <- resample(sim_admin, sim_pu_raster, method = "ngb")
159 +
#' sim_admin <- mask(sim_admin, sim_pu_raster)
160 +
#'
161 +
#' # plot administrative areas layer,
162 +
#' # we can see that the administrative areas subdivide
163 +
#' # the study region into four quadrants, and the sim_admin object is a
164 +
#' # RasterLayer with integer values denoting ids for the administrative areas
165 +
#' plot(sim_admin)
166 +
#'
167 +
#' # next we will convert the sim_admin RasterLayer object into a RasterStack
168 +
#' # object (with a layer for each administrative area) indicating which
169 +
#' # planning units belong to each administrative area using binary
170 +
#' # (presence/absence) values
171 +
#' sim_admin2 <- binary_stack(sim_admin)
172 +
#'
173 +
#' # plot administrative areas stack
174 +
#' plot(sim_admin2)
175 +
#'
176 +
#' # we will now calculate the total amount of planning units associated
177 +
#' # with each administrative area, so that we can set the constraint threshold
178 +
#'
179 +
#' # since we are using raster data, we won't bother explicitly
180 +
#' # accounting for the total area of each planning unit (because all
181 +
#' # planning units have the same area in raster formats) -- but if we were
182 +
#' # using vector data then we would need to account for the area of each unit
183 +
#' admin_total <- rowSums(rij_matrix(sim_pu_raster, sim_admin2))
184 +
#'
185 +
#' # create a modified version of p0 with additional constraints for each
186 +
#' # administrative area to specify that the planning units in the solution must
187 +
#' # not encompass more than 10% of the total extent of the administrative
188 +
#' # area
189 +
#' p3 <- p0
190 +
#' for (i in seq_len(nlayers(sim_admin2))) {
191 +
#'   p3 <- p3 %>%
192 +
#'         add_linear_constraints(threshold = admin_total[i] * 0.1,
193 +
#'                                sense = "<=",
194 +
#'                                data = sim_admin2[[i]])
195 +
#' }
196 +
#'
197 +
#' # solve problem
198 +
#' s3 <- solve(p3)
199 +
#'
200 +
#' # plot solutions s0 and s3 to compare them
201 +
#' plot(stack(s0, s3), main = c("s0", "s3"), axes = FALSE, box = FALSE)
202 +
#' }
203 +
#'
204 +
#' @name add_linear_constraints
205 +
#'
206 +
#' @exportMethod add_linear_constraints
207 +
#'
208 +
#' @aliases add_linear_constraints,ConservationProblem,ANY,ANY,Matrix-method add_linear_constraints,ConservationProblem,ANY,ANY,matrix-method add_linear_constraints,ConservationProblem,ANY,ANY,dgCMatrix-method add_linear_constraints,ConservationProblem,ANY,ANY,character-method add_linear_constraints,ConservationProblem,ANY,ANY,numeric-method add_linear_constraints,ConservationProblem,ANY,ANY,Raster-method
209 +
NULL
210 +
211 +
#' @export
212 +
methods::setGeneric("add_linear_constraints",
213 +
  signature = methods::signature("x", "threshold", "sense", "data"),
214 +
  function(x, threshold, sense, data)
215 +
    standardGeneric("add_linear_constraints"))
216 +
217 +
#' @name add_linear_constraints
218 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,character}(x, threshold, sense, data)
219 +
#' @rdname add_linear_constraints
220 +
methods::setMethod("add_linear_constraints",
221 +
  methods::signature("ConservationProblem", "ANY", "ANY", "character"),
222 +
  function(x, threshold, sense, data) {
223 +
    # validate arguments
224 +
    assertthat::assert_that(
225 +
      inherits(x$data$cost, c("data.frame", "Spatial", "sf")),
226 +
      msg = paste("argument to data is a character and planning units",
227 +
                  "specified in x are not a data.frame, Spatial, or sf object"))
228 +
    assertthat::assert_that(
229 +
      assertthat::is.number(threshold),
230 +
      assertthat::noNA(threshold),
231 +
      assertthat::noNA(data),
232 +
      number_of_zones(x) == length(data))
233 +
    assertthat::assert_that(
234 +
      assertthat::is.string(sense),
235 +
      assertthat::noNA(sense),
236 +
      sense %in% c("<=", "=", ">="))
237 +
    assertthat::assert_that(
238 +
      all(data %in% names(x$data$cost)),
239 +
      msg = paste("argument to data is not a field name in the planning units",
240 +
                  "specified in x"))
241 +
    # extract planning unit data
242 +
    d <- x$data$cost
243 +
    if (inherits(d, "Spatial")) {
244 +
      d <- as.matrix(d@data[, data, drop = FALSE])
245 +
    } else if (inherits(d, "sf")) {
246 +
      d <- as.matrix(sf::st_drop_geometry(d)[, data, drop = FALSE])
247 +
    } else {
248 +
      d <- as.matrix(d[, data, drop = FALSE])
249 +
    }
250 +
    # additional checks
251 +
    assertthat::assert_that(
252 +
      is.numeric(d),
253 +
      msg = paste("argument to data correspond to non-numeric fields in",
254 +
                  "the planning unit data associated with x"))
255 +
    assertthat::assert_that(
256 +
      assertthat::noNA(d),
257 +
      msg = paste("argument to data correspond to fields with NA values in",
258 +
                  "the planning unit data associated with x"))
259 +
    # add penalties
260 +
    add_linear_constraints(x, threshold, sense, d)
261 +
})
262 +
263 +
#' @name add_linear_constraints
264 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,numeric}(x, threshold, sense, data)
265 +
#' @rdname add_linear_constraints
266 +
methods::setMethod("add_linear_constraints",
267 +
  methods::signature("ConservationProblem", "ANY", "ANY", "numeric"),
268 +
  function(x, threshold, sense, data) {
269 +
    assertthat::assert_that(
270 +
      assertthat::is.number(threshold),
271 +
      assertthat::noNA(threshold),
272 +
      assertthat::is.string(sense),
273 +
      assertthat::noNA(sense),
274 +
      sense %in% c("<=", "=", ">="),
275 +
      assertthat::noNA(data),
276 +
      number_of_total_units(x) == length(data))
277 +
    add_linear_constraints(x, threshold, sense, matrix(data, ncol = 1))
278 +
})
279 +
280 +
#' @name add_linear_constraints
281 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,matrix}(x, threshold, sense, data)
282 +
#' @rdname add_linear_constraints
283 +
methods::setMethod("add_linear_constraints",
284 +
  methods::signature("ConservationProblem", "ANY", "ANY", "matrix"),
285 +
  function(x, threshold, sense, data) {
286 +
    assertthat::assert_that(
287 +
      assertthat::is.number(threshold),
288 +
      assertthat::noNA(threshold),
289 +
      assertthat::is.string(sense),
290 +
      assertthat::noNA(sense),
291 +
      sense %in% c("<=", "=", ">="),
292 +
      assertthat::noNA(c(data)),
293 +
      number_of_total_units(x) == nrow(data),
294 +
      number_of_zones(x) == ncol(data))
295 +
    add_linear_constraints(x, threshold, sense, methods::as(data, "dgCMatrix"))
296 +
})
297 +
298 +
#' @name add_linear_constraints
299 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,Matrix}(x, threshold, sense, data)
300 +
#' @rdname add_linear_constraints
301 +
methods::setMethod("add_linear_constraints",
302 +
  methods::signature("ConservationProblem", "ANY", "ANY", "Matrix"),
303 +
  function(x, threshold, sense, data) {
304 +
    assertthat::assert_that(
305 +
      assertthat::is.number(threshold),
306 +
      assertthat::noNA(threshold),
307 +
      assertthat::is.string(sense),
308 +
      assertthat::noNA(sense),
309 +
      sense %in% c("<=", "=", ">="),
310 +
      assertthat::noNA(c(data)),
311 +
      number_of_total_units(x) == nrow(data),
312 +
      number_of_zones(x) == ncol(data))
313 +
    add_linear_constraints(x, threshold, sense, methods::as(data, "dgCMatrix"))
314 +
})
315 +
316 +
#' @name add_linear_constraints
317 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,Raster}(x, threshold, sense, data)
318 +
#' @rdname add_linear_constraints
319 +
methods::setMethod("add_linear_constraints",
320 +
  methods::signature("ConservationProblem", "ANY", "ANY", "Raster"),
321 +
  function(x, threshold, sense, data) {
322 +
    # assert valid arguments
323 +
    assertthat::assert_that(
324 +
      inherits(x, "ConservationProblem"),
325 +
      inherits(data, "Raster"),
326 +
      assertthat::is.number(threshold),
327 +
      assertthat::noNA(threshold),
328 +
      assertthat::is.string(sense),
329 +
      assertthat::noNA(sense),
330 +
      sense %in% c("<=", "=", ">="),
331 +
      number_of_zones(x) == raster::nlayers(data),
332 +
      inherits(x$data$cost, c("sf", "Spatial", "Raster")))
333 +
    # extract constraint data
334 +
    if (inherits(x$data$cost, c("sf", "Spatial"))) {
335 +
      d <- fast_extract(data, x$data$cost, fun = "sum")
336 +
    } else {
337 +
      assertthat::assert_that(is_comparable_raster(x$data$cost, data[[1]]))
338 +
      d <- as.matrix(raster::as.data.frame(data))
339 +
    }
340 +
    d[is.na(d)] <- 0
341 +
    # add constraints
342 +
    add_linear_constraints(x, threshold, sense, methods::as(d, "dgCMatrix"))
343 +
})
344 +
345 +
#' @name add_linear_constraints
346 +
#' @usage \S4method{add_linear_constraints}{ConservationProblem,ANY,ANY,dgCMatrix}(x, threshold, sense, data)
347 +
#' @rdname add_linear_constraints
348 +
methods::setMethod("add_linear_constraints",
349 +
  methods::signature("ConservationProblem", "ANY", "ANY", "dgCMatrix"),
350 +
  function(x, threshold, sense, data) {
351 +
    # assert valid arguments
352 +
    assertthat::assert_that(
353 +
      inherits(x, "ConservationProblem"),
354 +
      assertthat::is.number(threshold),
355 +
      assertthat::noNA(threshold),
356 +
      assertthat::is.string(sense),
357 +
      assertthat::noNA(sense),
358 +
      sense %in% c("<=", "=", ">="),
359 +
      is.numeric(data@x),
360 +
      all(is.finite(data@x),
361 +
      number_of_total_units(x) == nrow(data),
362 +
      number_of_zones(x) == ncol(data)))
363 +
    # assert that constraint is even remotely possible
364 +
    if (identical(sense, ">=")) {
365 +
      assertthat::assert_that(
366 +
        any(Matrix::colSums(data) >= threshold),
367 +
        msg = paste("linear constraint cannot achieve threshold even if all",
368 +
                    "planning units selected.")
369 +
      )
370 +
    }
371 +
    # add penalties
372 +
    x$add_constraint(pproto(
373 +
      "LinearConstraint",
374 +
      Constraint,
375 +
      name = "Linear constraints",
376 +
      data = list(data = data, sense = sense),
377 +
      parameters = parameters(numeric_parameter("threshold", threshold)),
378 +
      apply = function(self, x, y) {
379 +
        assertthat::assert_that(inherits(x, "OptimizationProblem"),
380 +
                                inherits(y, "ConservationProblem"))
381 +
        # extract parameters
382 +
        th <- self$parameters$get("threshold")
383 +
        # extract data
384 +
        indices <- y$planning_unit_indices()
385 +
        d <- self$get_data("data")[indices, , drop = FALSE]
386 +
        s <- self$get_data("sense")
387 +
        # apply constraints
388 +
        rcpp_apply_linear_constraints(x$ptr, th, s, d)
389 +
        # return success
390 +
        invisible(TRUE)
391 +
    }))
392 +
})

@@ -9,7 +9,12 @@
Loading
9 9
#'
10 10
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
11 11
#'
12 -
#' @seealso [decisions].
12 +
#' @inherit add_binary_decisions return
13 +
#'
14 +
#' @seealso
15 +
#' See [decisions] for an overview of all functions for adding decisions.
16 +
#'
17 +
#' @family decisions
13 18
#'
14 19
#' @export
15 20
add_default_decisions <- function(x) {

@@ -4,62 +4,67 @@
Loading
4 4
#' Add maximum utility objective
5 5
#'
6 6
#' Set the objective of a conservation planning [problem()] to
7 -
#' secure as much of the features as possible without exceeding a budget. This
8 -
#' type of objective does not use targets, and feature weights should be used
9 -
#' instead to increase the representation of different features in solutions.
7 +
#' secure as much of the features as possible without exceeding a budget.
8 +
#' This objective does not use targets, and feature
9 +
#' weights should be used instead to increase the representation of certain
10 +
#' features by a solution.
10 11
#' Note that this objective does not aim to maximize as much of each feature as
11 -
#' possible and so often results in solutions that are heavily biased towards
12 -
#' specific features.
12 +
#' possible, and so often results in solutions that are heavily biased towards
13 +
#' just a few features.
13 14
#'
14 15
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
15 16
#'
16 17
#' @param budget `numeric` value specifying the maximum expenditure of
17 18
#'   the prioritization. For problems with multiple zones, the argument
18 -
#'   to `budget` can be a single `numeric` value to specify a budget
19 -
#'   for the entire solution or a `numeric` `vector` to specify
20 -
#'   a budget for each each management zone.
21 -
#'
22 -
#' @details A problem objective is used to specify the overall goal of the
23 -
#'   conservation planning problem. Please note that all conservation
24 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
25 -
#'   addition of objectives---failing to do so will return an error
26 -
#'   message when attempting to solve problem.
27 -
#'
28 -
#'   The maximum utility objective seeks to find the set of planning units that
29 -
#'   maximizes the overall level of representation across a suite of
30 -
#'   conservation features, while keeping cost within a fixed budget.
31 -
#'   Additionally, weights can be used to favor the
32 -
#'   representation of certain features over other features (see
33 -
#'   [add_feature_weights()]). This objective can be
34 -
#'   expressed mathematically for a set of planning units (\eqn{I}{I} indexed by
35 -
#'   \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed by \eqn{j}{j}) as:
36 -
#'
37 -
#'   \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
38 -
#'   \sum_{j = 1}^{J} a_j w_j \\
39 -
#'   \mathit{subject \space to} \\ a_j = \sum_{i = 1}^{I} x_i r_{ij} \space
40 -
#'   \forall j \in J \\ \sum_{i = 1}^{I} x_i c_i \leq B}{
41 -
#'   Maximize sum_i^I (-s * ci * xi) + sum_j^J (aj * wj) subject to
42 -
#'   aj = sum_i^I (xi * rij) for all j in J & sum_i^I (xi * ci) <= B}
43 -
#'
44 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
45 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
46 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
47 -
#'   unit \eqn{i}{i}, \eqn{A_j}{Aj} is the amount of feature \eqn{j}{j}
48 -
#'   represented in in the solution, and \eqn{w_j}{wj} is the weight for
49 -
#'   feature \eqn{j}{j} (defaults to 1 for all features; see
50 -
#'   [add_feature_weights()]
51 -
#'   to specify weights). Additionally, \eqn{B}{B} is the budget allocated for
52 -
#'   the solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
53 -
#'   \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
54 -
#'   will return a cheapest solution when there are multiple solutions that
55 -
#'   represent the same amount of all features within the budget.
19 +
#'   to `budget` can be (i) a single `numeric` value to specify a single budget
20 +
#'   for the entire solution or (ii) a `numeric` vector to specify
21 +
#'   a separate budget for each management zone.
22 +
#'
23 +
#' @details
24 +
#' The maximum utility objective seeks to maximize the overall level of
25 +
#' representation across a suite of conservation features, while keeping cost
26 +
#' within a fixed budget.
27 +
#' Additionally, weights can be used to favor the
28 +
#' representation of certain features over other features (see
29 +
#' [add_feature_weights()]).
30 +
#'
31 +
#' @section Mathematical formulation:
32 +
#' This objective can be expressed mathematically for a set of planning units
33 +
#' (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J} indexed
34 +
#' by \eqn{j}{j}) as:
35 +
#'
36 +
#' \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
37 +
#' \sum_{j = 1}^{J} a_j w_j \\
38 +
#' \mathit{subject \space to} \\ a_j = \sum_{i = 1}^{I} x_i r_{ij} \space
39 +
#' \forall j \in J \\ \sum_{i = 1}^{I} x_i c_i \leq B}{
40 +
#' Maximize sum_i^I (-s * ci * xi) + sum_j^J (aj * wj) subject to
41 +
#' aj = sum_i^I (xi * rij) for all j in J & sum_i^I (xi * ci) <= B}
42 +
#'
43 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
44 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
45 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
46 +
#' unit \eqn{i}{i}, \eqn{A_j}{Aj} is the amount of feature \eqn{j}{j}
47 +
#' represented in in the solution, and \eqn{w_j}{wj} is the weight for
48 +
#' feature \eqn{j}{j} (defaults to 1 for all features; see
49 +
#' [add_feature_weights()]
50 +
#' to specify weights). Additionally, \eqn{B}{B} is the budget allocated for
51 +
#' the solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
52 +
#' \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
53 +
#' will return a cheapest solution when there are multiple solutions that
54 +
#' represent the same amount of all features within the budget.
56 55
#'
57 56
#' @section Notes:
58 57
#' In early versions (< 3.0.0.0), this function was named as
59 58
#' the `add_max_cover_objective` function. It was renamed to avoid
60 59
#' confusion with existing terminology.
61 60
#'
62 -
#' @inherit add_max_features_objective seealso return
61 +
#' @inherit add_max_features_objective return
62 +
#'
63 +
#' @seealso
64 +
#' See [objectives] for an overview of all functions for adding objectives.
65 +
#' Also, see [add_feature_weights()] to specify weights for different features.
66 +
#'
67 +
#' @family objectives
63 68
#'
64 69
#' @examples
65 70
#' # load data

@@ -12,87 +12,79 @@
Loading
12 12
#' history as possible. This function was inspired by Faith (1992),
13 13
#' Rodrigues *et al.* (2002), and Rosauer *et al.* (2009).
14 14
#'
15 -
#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
15 +
#' @inheritParams add_max_phylo_div_objective
16 16
#'
17 -
#' @param budget `numeric` value specifying the maximum expenditure of
18 -
#'   the prioritization. For problems with multiple zones, the argument
19 -
#'   to `budget` can be a single `numeric` value to specify a budget
20 -
#'   for the entire solution or a `numeric` `vector` to specify
21 -
#'   a budget for each each management zone.
17 +
#' @details
18 +
#' The maximum phylogenetic endemism objective finds the set of
19 +
#' planning units that meets representation targets for a phylogenetic tree
20 +
#' while staying within a fixed budget. If multiple solutions can meet all
21 +
#' targets while staying within budget, the cheapest solution is chosen.
22 +
#' Note that this objective is similar to the maximum
23 +
#' features objective ([add_max_features_objective()]) in that it
24 +
#' allows for both a budget and targets to be set for each feature. However,
25 +
#' unlike the maximum feature objective, the aim of this objective is to
26 +
#' maximize the total phylogenetic endemism of the targets met in the
27 +
#' solution, so if multiple targets are provided for a single feature, the
28 +
#' problem will only need to meet a single target for that feature
29 +
#' for the phylogenetic benefit for that feature to be counted when
30 +
#' calculating the phylogenetic endemism of the solution. In other words,
31 +
#' for multi-zone problems, this objective does not aim to maximize the
32 +
#' phylogenetic endemism in each zone, but rather this objective
33 +
#' aims to maximize the phylogenetic endemism of targets that can be met
34 +
#' through allocating planning units to any of the different zones in a
35 +
#' problem. This can be useful for problems where targets pertain to the total
36 +
#' amount held for each feature across multiple zones. For example,
37 +
#' each feature might have a non-zero amount of suitable habitat in each
38 +
#' planning unit when the planning units are assigned to a (i) not restored,
39 +
#' (ii) partially restored, or (iii) completely restored management zone.
40 +
#' Here each target corresponds to a single feature and can be met through
41 +
#' the total amount of habitat in planning units present to the three
42 +
#' zones.
22 43
#'
23 -
#' @param tree [phylo()] object specifying a phylogenetic tree
24 -
#'   for the conservation features.
44 +
#' @section Mathematical formulation:
45 +
#' This objective can be expressed mathematically for a set of planning units
46 +
#' (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J}
47 +
#' indexed by \eqn{j}{j}) as:
25 48
#'
26 -
#' @details A problem objective is used to specify the overall goal of the
27 -
#'   conservation planning problem. Please note that all conservation
28 -
#'   planning problems formulated in the \pkg{prioritizr} package require the
29 -
#'   addition of objectives---failing to do so will return an error
30 -
#'   message when attempting to solve problem.
49 +
#' \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
50 +
#' \sum_{j = 1}^{J} m_b l_b \frac{1}{a_b} \\
51 +
#' \mathit{subject \space to} \\
52 +
#' \sum_{i = 1}^{I} x_i r_{ij} \geq y_j t_j \forall j \in J \\
53 +
#' m_b \leq y_j \forall j \in T(b) \\
54 +
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
55 +
#' Maximize sum_i^I (-s * ci * xi) + sum_j^J (mb * lb * (1 / ab))
56 +
#' subject to sum_i^I (xi * rij) >= (yj * tj) for all j in J &
57 +
#' mb <= yj for all j in T(b) & sum_i^I (xi * ci) <= B}
31 58
#'
32 -
#'   The maximum phylogenetic endemism objective finds the set of
33 -
#'   planning units that meets representation targets for a phylogenetic tree
34 -
#'   while staying within a fixed budget. If multiple solutions can meet all
35 -
#'   targets while staying within budget, the cheapest solution is chosen.
36 -
#'   Note that this objective is similar to the maximum
37 -
#'   features objective ([add_max_features_objective()]) in that it
38 -
#'   allows for both a budget and targets to be set for each feature. However,
39 -
#'   unlike the maximum feature objective, the aim of this objective is to
40 -
#'   maximize the total phylogenetic endemism of the targets met in the
41 -
#'   solution, so if multiple targets are provided for a single feature, the
42 -
#'   problem will only need to meet a single target for that feature
43 -
#'   for the phylogenetic benefit for that feature to be counted when
44 -
#'   calculating the phylogenetic endemism of the solution. In other words,
45 -
#'   for multi-zone problems, this objective does not aim to maximize the
46 -
#'   phylogenetic endemism in each zone, but rather this objective
47 -
#'   aims to maximize the phylogenetic endemism of targets that can be met
48 -
#'   through allocating planning units to any of the different zones in a
49 -
#'   problem. This can be useful for problems where targets pertain to the total
50 -
#'   amount held for each feature across multiple zones. For example,
51 -
#'   each feature might have a non-zero amount of suitable habitat in each
52 -
#'   planning unit when the planning units are assigned to a (i) not restored,
53 -
#'   (ii) partially restored, or (iii) completely restored management zone.
54 -
#'   Here each target corresponds to a single feature and can be met through
55 -
#'   the total amount of habitat in planning units present to the three
56 -
#'   zones.
59 +
#' Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
60 +
#' specifying whether planning unit \eqn{i}{i} has been selected (1) or not
61 +
#' (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
62 +
#' unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
63 +
#' \eqn{j}{j}, \eqn{y_j}{yj} indicates if the solution has meet
64 +
#' the target \eqn{t_j}{tj} for feature \eqn{j}{j}. Additionally,
65 +
#' \eqn{T}{T} represents a phylogenetic tree containing features \eqn{j}{j}
66 +
#' and has the branches \eqn{b} associated within lengths \eqn{l_b}{lb}.
67 +
#' Each branch \eqn{b \in B}{b in B} is associated with a total amount
68 +
#' \eqn{a_b}{ab} indicating the total geographic extent or amount of habitat.
69 +
#' The \eqn{a_b}{ab} variable for a given branch is calculated by summing the
70 +
#' \eqn{r_{ij}}{rij} data for all features \eqn{j \in J}{j in J} that are
71 +
#' associated with the branch. The binary variable \eqn{m_b}{mb} denotes if
72 +
#' at least one feature associated with the branch \eqn{b}{b} has met its
73 +
#' representation as indicated by \eqn{y_j}{yj}. For brevity, we denote
74 +
#' the features \eqn{j}{j} associated with branch \eqn{b}{b} using
75 +
#' \eqn{T(b)}{T(b)}. Finally, \eqn{B}{B} is the budget allocated for the
76 +
#' solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
77 +
#' \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
78 +
#' will return a cheapest solution when there are multiple solutions that
79 +
#' represent the same amount of all features within the budget.
57 80
#'
58 -
#'   The maximum phylogenetic endemism objective for the reserve design
59 -
#'   problem can be expressed mathematically for a set of planning units
60 -
#'   (\eqn{I}{I} indexed by \eqn{i}{i}) and a set of features (\eqn{J}{J}
61 -
#'   indexed by \eqn{j}{j}) as:
81 +
#' @seealso
82 +
#' See [objectives] for an overview of all functions for adding objectives.
83 +
#' Also, see [targets] for an overview of all functions for adding targets, and
84 +
#' [add_feature_weights()] to specify weights for different features.
62 85
#'
63 -
#'   \deqn{\mathit{Maximize} \space \sum_{i = 1}^{I} -s \space c_i \space x_i +
64 -
#'   \sum_{j = 1}^{J} m_b l_b \frac{1}{a_b} \\
65 -
#'   \mathit{subject \space to} \\
66 -
#'   \sum_{i = 1}^{I} x_i r_{ij} \geq y_j t_j \forall j \in J \\
67 -
#'   m_b \leq y_j \forall j \in T(b) \\
68 -
#'   \sum_{i = 1}^{I} x_i c_i \leq B}{
69 -
#'   Maximize sum_i^I (-s * ci * xi) + sum_j^J (mb * lb * (1 / ab))
70 -
#'   subject to sum_i^I (xi * rij) >= (yj * tj) for all j in J &
71 -
#'   mb <= yj for all j in T(b) & sum_i^I (xi * ci) <= B}
86 +
#' @family objectives
72 87
#'
73 -
#'   Here, \eqn{x_i}{xi} is the [decisions] variable (e.g.
74 -
#'   specifying whether planning unit \eqn{i}{i} has been selected (1) or not
75 -
#'   (0)), \eqn{r_{ij}}{rij} is the amount of feature \eqn{j}{j} in planning
76 -
#'   unit \eqn{i}{i}, \eqn{t_j}{tj} is the representation target for feature
77 -
#'   \eqn{j}{j}, \eqn{y_j}{yj} indicates if the solution has meet
78 -
#'   the target \eqn{t_j}{tj} for feature \eqn{j}{j}. Additionally,
79 -
#'   \eqn{T}{T} represents a phylogenetic tree containing features \eqn{j}{j}
80 -
#'   and has the branches \eqn{b} associated within lengths \eqn{l_b}{lb}.
81 -
#'   Each branch \eqn{b \in B}{b in B} is associated with a total amount
82 -
#'   \eqn{a_b}{ab} indicating the total geographic extent or amount of habitat.
83 -
#'   The \eqn{a_b}{ab} variable for a given branch is calculated by summing the
84 -
#'   \eqn{r_{ij}}{rij} data for all features \eqn{j \in J}{j in J} that are
85 -
#'   associated with the branch. The binary variable \eqn{m_b}{mb} denotes if
86 -
#'   at least one feature associated with the branch \eqn{b}{b} has met its
87 -
#'   representation as indicated by \eqn{y_j}{yj}. For brevity, we denote
88 -
#'   the features \eqn{j}{j} associated with branch \eqn{b}{b} using
89 -
#'   \eqn{T(b)}{T(b)}. Finally, \eqn{B}{B} is the budget allocated for the
90 -
#'   solution, \eqn{c_i}{ci} is the cost of planning unit \eqn{i}{i}, and
91 -
#'   \eqn{s}{s} is a scaling factor used to shrink the costs so that the problem
92 -
#'   will return a cheapest solution when there are multiple solutions that
93 -
#'   represent the same amount of all features within the budget.
94 -
#'
95 -
#' @seealso [objectives], [branch_matrix()].
96 88
#'
97 89
#' @inherit add_min_set_objective return
98 90
#'

@@ -23,72 +23,76 @@
Loading
23 23
#'   the presolve checks. Defaults to `FALSE`.
24 24
#'
25 25
#' @details
26 -
#'   After formulating a conservation planning [problem()],
27 -
#'   it can be solved using an exact algorithm solver (see [solvers]
28 -
#'   for available solvers). If no solver has been explicitly specified,
29 -
#'   then the best available exact algorithm solver will be used by default
30 -
#'   (see [add_default_solver()]. Although these exact algorithm
31 -
#'   solvers will often display a lot of information that isn't really that
32 -
#'   helpful (e.g. nodes, cutting planes), they do display information
33 -
#'   about the progress they are making on solving the problem (e.g. the
34 -
#'   performance of the best solution found at a given point in time). If
35 -
#'   potential issues were detected during the
36 -
#'   presolve checks (see [presolve_check()])
37 -
#'   and the problem is being forcibly solved (i.e. with `force = TRUE`),
38 -
#'   then it is also worth checking for any warnings displayed by the solver
39 -
#'   to see if these potential issues are actually causing issues
40 -
#'   (e.g. *Gurobi* can display warnings that include
41 -
#'   `"Warning: Model contains large matrix coefficient range"` and
42 -
#'   `"Warning: Model contains large rhs"`).
43 -
#'
44 -
#'   The object returned from this function depends on the argument to
45 -
#'   `a`. If the argument to `a` is an
46 -
#'   [`OptimizationProblem-class`] object, then the
47 -
#'   solution is returned as a `logical` `vector` showing the status
48 -
#'   of each planning unit in each zone. However, in most cases, the argument
49 -
#'   to `a` is an [`ConservationProblem-class`] object, and so
50 -
#'   the type of object returned depends on the number of solutions
51 -
#'   generated and the type data used to represent the planning units:
26 +
#' After formulating a conservation planning [problem()],
27 +
#' it can be solved using an exact algorithm solver (see [solvers]
28 +
#' for available solvers). If no solver has been explicitly specified,
29 +
#' then the best available exact algorithm solver will be used by default
30 +
#' (see [add_default_solver()]. Although these exact algorithm
31 +
#' solvers will often display a lot of information that isn't really that
32 +
#' helpful (e.g. nodes, cutting planes), they do display information
33 +
#' about the progress they are making on solving the problem (e.g. the
34 +
#' performance of the best solution found at a given point in time). If
35 +
#' potential issues were detected during the
36 +
#' presolve checks (see [presolve_check()])
37 +
#' and the problem is being forcibly solved (i.e. with `force = TRUE`),
38 +
#' then it is also worth checking for any warnings displayed by the solver
39 +
#' to see if these potential issues are actually causing issues
40 +
#' (e.g. *Gurobi* can display warnings that include
41 +
#' `"Warning: Model contains large matrix coefficient range"` and
42 +
#' `"Warning: Model contains large rhs"`).
43 +
#'
44 +
#' The object returned from this function depends on the argument to
45 +
#' `a`. If the argument to `a` is an
46 +
#' [`OptimizationProblem-class`] object, then the
47 +
#' solution is returned as a `logical` vector showing the status
48 +
#' of each planning unit in each zone. However, in most cases, the argument
49 +
#' to `a` will be a [`ConservationProblem-class`] object, and so
50 +
#' the type of object returned depends on the number of solutions
51 +
#' generated and the data format used to specify the planning units:
52 52
#'
53 53
#'   \describe{
54 54
#'
55 -
#'   \item{`numeric`}{`vector` containing the solution. Here,
56 -
#'     Each element corresponds to a different planning unit. If
57 -
#'     multiple solutions are generated, then the solution is returned as
58 -
#'     a `list` of `numeric` `vectors`.}
55 +
#'   \item{`a` has `numeric` planning units}{The solution will be
56 +
#'    returned as a `numeric` vector. Here, each element in the vector
57 +
#'     corresponds to a different planning unit.
58 +
#'     Note that if a portfolio is used to generate multiple solutions,
59 +
#'     then a `list` of such `numeric` vectors will be returned.}
59 60
#'
60 -
#'   \item{`matrix`}{containing `numeric` values for the solution.
61 +
#'   \item{`a` has `matrix` planning units}{The solution will be
62 +
#'     returned as a `matrix` object.
61 63
#'     Here, rows correspond to different planning units,
62 -
#'     and fields (columns) correspond to different  management zones. If
63 -
#'     multiple solutions are generated, then the solution is returned as
64 -
#'     a `list` of `matrix` objects.}
65 -
#'
66 -
#'   \item{[`Raster-class`]}{object containing the solution
67 -
#'     in pixel values. If the argument to `x` contains a single
68 -
#'     management zone, then a `RasterLayer` object will be returned.
64 +
#'     and fields (columns) correspond to different  management zones.
65 +
#'     Note that if a portfolio is used to generate multiple solutions,
66 +
#'     then a `list` of such `matrix` objects will be returned.}
67 +
#'
68 +
#'   \item{`a` has [`Raster-class`] planning units}{The solution
69 +
#'     will be returned as a [`Raster-class`] object.
70 +
#'     If the argument to `x` contains a single
71 +
#'     management zone, then a [`RasterLayer-class`] object will be returned.
69 72
#'     Otherwise, if the argument to `x` contains multiple zones, then a
70 73
#'     [`RasterStack-class`] object
71 74
#'     will be returned containing a different layer for each management zone.
72 -
#'     If multiple solutions are generated, then the solution is returned as
73 -
#'     a `list` of `Raster` objects.}
74 -
#'
75 -
#'   \item{[`Spatial-class`], [sf::sf()], or
76 -
#'     `data.frame`}{
77 -
#'     containing the solution in fields (columns). Here, each row
78 -
#'     corresponds to a different planning unit. If the argument to `x`
79 -
#'     contains a single zone, the fields containing solutions are named
80 -
#'     `"solution_XXX"` where `"XXX"` corresponds to the solution
81 -
#'     number. If the argument to `x` contains multiple zones, the fields
82 -
#'     containing solutions are named `"solution_XXX_YYY"` where
83 -
#'     `"XXX"` corresponds to the solution and `"YYY"` is the name
84 -
#'     of the management zone.}
75 +
#'     Note that if a portfolio is used to generate multiple solutions,
76 +
#'     then a `list` of such [`Raster-class`] objects will be returned.}
77 +
#'
78 +
#'   \item{`a` has [`Spatial-class`], [sf::sf()], or `data.frame`
79 +
#'     planning units}{
80 +
#'     The solution will be returned in the same data format as the planning
81 +
#'     units.
82 +
#'     Here, each row corresponds to a different planning unit,
83 +
#'     and fields contain solutions.
84 +
#'     If the argument to `a` contains a single zone, then the solution object
85 +
#'     will contain fields (columns) that solution the values.
86 +
#'     Specifically, the field name(s) containing the solution values
87 +
#'     be will named as `"solution_XXX"` where `"XXX"` corresponds to a solution
88 +
#'     identifier (e.g. `"solution_1"`).
89 +
#'     If the argument to `a` contains multiple zones, then the fields
90 +
#'     containing solutions will be named as `"solution_XXX_YYY"` where
91 +
#'     `"XXX"` corresponds to the solution identifier and `"YYY"` is the name
92 +
#'     of the management zone (e.g. `"solution_1_zone1"`).}
85 93
#'
86 94
#'   }
87 95
#'
88 -
#'   After solving problems that contain multiple zones,
89 -
#'   it may be useful to use the [category_layer()] or
90 -
#'   [category_vector()] function to reformat the output.
91 -
#'
92 96
#' @return A `numeric`, `matrix`,
93 97
#'   [`RasterLayer-class`], [`Spatial-class`],
94 98
#'   or [sf::sf()] object containing the solution to the problem.
@@ -97,14 +101,16 @@
Loading
97 101
#'   `"runtime"` denoting the number of seconds that elapsed while solving
98 102
#'   the problem, and `"status"` describing the status of the solution
99 103
#'   (e.g. `"OPTIMAL"` indicates that the optimal solution was found).
100 -
#'   In most cases, the first solution (e.g. `"solution_001"`)
104 +
#'   In most cases, the first solution (e.g. `"solution_1"`)
101 105
#'   will contain the best solution found by the solver (note that this
102 106
#'   may not be an optimal solution depending on the gap used to solve
103 107
#'   the problem and noting that the default gap is 0.1).
104 108
#'
105 -
#' @seealso [eval_feature_representation_summary()], [problem()],
106 -
#'   [solvers], [category_layer()],
107 -
#'   [presolve_check()].
109 +
#' @seealso
110 +
#' See [problem()] to create conservation planning problems, and
111 +
#' [presolve_check()] to check problems for potential issues.
112 +
#' Also, see the [category_layer()] and [category_vector()] function to
113 +
#' reformat solutions that contain multiple zones.
108 114
#'
109 115
#' @examples
110 116
#' # set seed for reproducibility

@@ -49,7 +49,7 @@
Loading
49 49
       ptr->_obj.push_back(0.0);
50 50
  // add target totals to convert total amounts to proportions
51 51
  for (std::size_t i = 0; i < n_targets; ++i)
52 -
    ptr->_obj.push_back(1.0 / targets_value[i]);
52 +
    ptr->_obj.push_back(targets_value[i] > 1.0e-5 ? 1.0 / targets_value[i] : 0);
53 53
  // add in upper and lower bounds for the decision variables representing if
54 54
  // each species is adequately conserved
55 55
  for (std::size_t i = 0; i < n_targets; ++i)

@@ -51,77 +51,83 @@
Loading
51 51
#'   planning units (i.e. planning units that are adjacent to each other).
52 52
#'   See the Data format section for more information.
53 53
#'
54 -
#' @details This function adds penalties to a conservation planning problem
55 -
#'   to penalize fragmented solutions. It was is inspired by Ball *et al.*
56 -
#'   (2009) and Beyer *et al.* (2016). The `penalty` argument is
57 -
#'   equivalent to the boundary length modifier (`BLM`) used in
58 -
#'   [*Marxan*](https://marxansolutions.org).
59 -
#'   Note that this function can only
60 -
#'   be used to represent symmetric relationships between planning units. If
61 -
#'   asymmetric relationships are required, use the
62 -
#'   [add_connectivity_penalties()] function.
63 -
#'
64 -
#'   The boundary penalties are calculated using the following equations. Let
65 -
#'   \eqn{I} represent the set of planning units
66 -
#'   (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent
67 -
#'   the set of management zones (indexed by \eqn{z} or \eqn{y}), and
68 -
#'   \eqn{X_{iz}}{Xiz} represent the decision
69 -
#'   variable for planning unit \eqn{i} for in zone \eqn{z} (e.g. with binary
70 -
#'   values one indicating if planning unit is allocated or not). Also, let
71 -
#'   \eqn{p} represent the argument to `penalty`, \eqn{E_z}{Ez} represent the
72 -
#'   argument to `edge_factor`, \eqn{B_{ij}}{Bij} represent the matrix argument
73 -
#'   to `data` (e.g. generated using [boundary_matrix()]), and
74 -
#'   \eqn{W_{zz}}{Wzz} represent the matrix argument to `zones`.
75 -
#'
76 -
#'   \deqn{
77 -
#'   \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} (\mathit{ifelse}(i == j, E_z, 1)
78 -
#'   \times p \times W_{zz} B_{ij}) + \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z}
79 -
#'   \sum_{y}^{Z} (-2 \times p \times X_{iz} \times X_{jy} \times W_{zy} \times
80 -
#'   B_{ij})}{
81 -
#'   sum_i^I sum_j^I sum_z^Z (ifelse(i == j, Ez, 1) * p * Wzz * Bij) + sum_i^I
82 -
#'   sum_j^I sum_z^Z sum_y^Z (-2 * p * Xiz * Xjy * Wzy * Bij)
83 -
#'   }
84 -
#'
85 -
#'  Note that when the problem objective is to maximize some measure of
86 -
#'  benefit and not minimize some measure of cost, the term \eqn{p} is
87 -
#'  replaced with \eqn{-p}.
54 +
#' @details
55 +
#' This function adds penalties to a conservation planning problem
56 +
#' to penalize fragmented solutions. It was is inspired by Ball *et al.*
57 +
#' (2009) and Beyer *et al.* (2016). The `penalty` argument is
58 +
#' equivalent to the boundary length modifier (`BLM`) used in
59 +
#' [*Marxan*](https://marxansolutions.org).
60 +
#' Note that this function can only
61 +
#' be used to represent symmetric relationships between planning units. If
62 +
#' asymmetric relationships are required, use the
63 +
#' [add_connectivity_penalties()] function.
88 64
#'
89 65
#' @section Data format:
90 -
#'   The argument to `data` can be specified using the following formats.
91 -
#'   Note that boundary data must always describe symmetric relationships
92 -
#'   between planning units.
93 -
#'
94 -
#'   \describe{
95 -
#'
96 -
#'   \item{`NULL`}{boundary data are automatically calculated
97 -
#'     using the [boundary_matrix()] function. This argument is the
98 -
#'     default. Note that the boundary data must be supplied
99 -
#'     using one of the other formats below if the planning unit data
100 -
#'     in the argument to `x` do not explicitly contain spatial information
101 -
#'     (e.g. planning unit data are a `data.frame` or `numeric` class).}
102 -
#'
103 -
#'   \item{`matrix`, `Matrix`}{where rows and columns represent
104 -
#'     different planning units and the value of each cell represents the
105 -
#'     amount of shared boundary length between two different planning units.
106 -
#'     Cells that occur along the matrix diagonal represent the amount of
107 -
#'     exposed boundary associated with each planning unit that has
108 -
#'     no neighbor (e.g. these value might pertain to boundaries along a
109 -
#'     coastline).}
110 -
#'
111 -
#'   \item{`data.frame`}{with the columns `"id1"`,
112 -
#'     `"id2"`, and `"boundary"`. The `"id1"` and `"id2"` columns contain
113 -
#'     identifiers (indices) for a pair of planning units, and the `"boundary"`
114 -
#'     column contains the amount of shared boundary length between these
115 -
#'     two planning units.
116 -
#'     This format follows the the standard *Marxan* format for boundary
117 -
#'     data (i.e. per the "bound.dat" file).}
118 -
#'
119 -
#'   }
66 +
#' The argument to `data` can be specified using the following formats.
67 +
#' Note that boundary data must always describe symmetric relationships
68 +
#' between planning units.
69 +
#'
70 +
#' \describe{
71 +
#'
72 +
#' \item{`data` as a `NULL` value}{indicating that the data should be
73 +
#'   automatically calculated using the [boundary_matrix()] function.
74 +
#'   This argument is the default.
75 +
#'   Note that the boundary data must be supplied
76 +
#'   using one of the other formats below if the planning unit data
77 +
#'   in the argument to `x` do not explicitly contain spatial information
78 +
#'   (e.g. planning unit data are a `data.frame` or `numeric` class).}
79 +
#'
80 +
#' \item{`data` as a `matrix`/`Matrix` object}{where rows and columns represent
81 +
#'   different planning units and the value of each cell represents the
82 +
#'   amount of shared boundary length between two different planning units.
83 +
#'   Cells that occur along the matrix diagonal represent the amount of
84 +
#'   exposed boundary associated with each planning unit that has
85 +
#'   no neighbor (e.g. these value might pertain to boundaries along a
86 +
#'   coastline).}
87 +
#'
88 +
#' \item{`data` as a `data.frame` object}{with the columns `"id1"`,
89 +
#'   `"id2"`, and `"boundary"`. The `"id1"` and `"id2"` columns contain
90 +
#'   identifiers (indices) for a pair of planning units, and the `"boundary"`
91 +
#'   column contains the amount of shared boundary length between these
92 +
#'   two planning units.
93 +
#'   This format follows the the standard *Marxan* format for boundary
94 +
#'   data (i.e. per the "bound.dat" file).}
95 +
#'
96 +
#' }
97 +
#'
98 +
#' @section Mathematical formulation:
99 +
#' The boundary penalties are implemented using the following equations. Let
100 +
#' \eqn{I} represent the set of planning units
101 +
#' (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent
102 +
#' the set of management zones (indexed by \eqn{z} or \eqn{y}), and
103 +
#' \eqn{X_{iz}}{Xiz} represent the decision
104 +
#' variable for planning unit \eqn{i} for in zone \eqn{z} (e.g. with binary
105 +
#' values one indicating if planning unit is allocated or not). Also, let
106 +
#' \eqn{p} represent the argument to `penalty`, \eqn{E_z}{Ez} represent the
107 +
#' argument to `edge_factor`, \eqn{B_{ij}}{Bij} represent the matrix argument
108 +
#' to `data` (e.g. generated using [boundary_matrix()]), and
109 +
#' \eqn{W_{zz}}{Wzz} represent the matrix argument to `zones`.
110 +
#'
111 +
#' \deqn{
112 +
#' \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} (\mathit{ifelse}(i == j, E_z, 1)
113 +
#' \times p \times W_{zz} B_{ij}) + \sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z}
114 +
#' \sum_{y}^{Z} (-2 \times p \times X_{iz} \times X_{jy} \times W_{zy} \times
115 +
#' B_{ij})}{
116 +
#' sum_i^I sum_j^I sum_z^Z (ifelse(i == j, Ez, 1) * p * Wzz * Bij) + sum_i^I
117 +
#' sum_j^I sum_z^Z sum_y^Z (-2 * p * Xiz * Xjy * Wzy * Bij)
118 +
#' }
119 +
#'
120 +
#' Note that when the problem objective is to maximize some measure of
121 +
#' benefit and not minimize some measure of cost, the term \eqn{p} is
122 +
#' replaced with \eqn{-p}.
120 123
#'
121 124
#' @return Object (i.e. [`ConservationProblem-class`]) with the penalties
122 125
#'  added to it.
123 126
#'
124 -
#' @seealso [penalties].
127 +
#' @seealso
128 +
#' See [penalties] for an overview of all functions for adding penalties.
129 +
#'
130 +
#' @family penalties
125 131
#'
126 132
#' @references
127 133
#' Ball IR, Possingham HP, and Watts M (2009) *Marxan and relatives:

@@ -43,21 +43,22 @@
Loading
43 43
#'
44 44
#' \describe{
45 45
#'
46 -
#' \item{`NULL`}{neighborhood data should be calculated automatically
46 +
#' \item{`data` as a `NULL` value}{neighborhood data should be calculated
47 +
#'   automatically
47 48
#'   using the [adjacency_matrix()] function. This is the default
48 49
#'   argument. Note that the neighborhood data must be manually defined
49 50
#'   using one of the other formats below when the planning unit data
50 51
#'   in the argument to `x` is not spatially referenced (e.g.
51 52
#'   in `data.frame` or `numeric` format).}
52 53
#'
53 -
#' \item{`matrix`, `Matrix`}{where rows and columns represent
54 +
#' \item{`data` as a `matrix`/`Matrix` object}{where rows and columns represent
54 55
#'   different planning units and the value of each cell indicates if the
55 56
#'   two planning units are neighbors or not. Cell values should be binary
56 57
#'   `numeric` values (i.e. one or zero). Cells that occur along the
57 58
#'   matrix diagonal have no effect on the solution at all because each
58 59
#'   planning unit cannot be a neighbor with itself.}
59 60
#'
60 -
#' \item{`data.frame`}{containing the fields (columns)
61 +
#' \item{`data` as a `data.frame` object}{containing the fields (columns)
61 62
#'   `"id1"`, `"id2"`, and `"boundary"`. Here, each row
62 63
#'   denotes the connectivity between two planning units following the
63 64
#'   *Marxan* format. The field `boundary` should contain
@@ -76,7 +77,7 @@
Loading
76 77
#'   names of the zones. If the columns `"zone1"` and `"zone2"`
77 78
#'   are present, then the argument to `zones` must be `NULL`.}
78 79
#'
79 -
#' \item{`array`}{containing four-dimensions where binary
80 +
#' \item{`data` as an `array` object}{containing four-dimensions where binary
80 81
#'   `numeric` values indicate if planning unit should be treated
81 82
#'   as being neighbors with every other planning unit when they
82 83
#'   are allocated to every combination of management zone. The first two

@@ -119,7 +119,10 @@
Loading
119 119
#'
120 120
#' @aliases eval_target_coverage_summary,ConservationProblem,numeric-method eval_target_coverage_summary,ConservationProblem,matrix-method eval_target_coverage_summary,ConservationProblem,data.frame-method eval_target_coverage_summary,ConservationProblem,Spatial-method eval_target_coverage_summary,ConservationProblem,sf-method eval_target_coverage_summary,ConservationProblem,Raster-method
121 121
#'
122 -
#' @inherit eval_cost_summary seealso
122 +
#' @seealso
123 +
#' See [summaries] for an overview of all functions for summarizing solutions.
124 +
#'
125 +
#' @family summaries
123 126
#'
124 127
#' @examples
125 128
#' \dontrun{

@@ -17,7 +17,8 @@
Loading
17 17
#'   See the Data format section for more information.
18 18
#'
19 19
#' @section Data format:
20 -
#' The argument to `data` must contain the following fields  (columns):
20 +
#' The argument to `data` should be a `data.frame` with the following fields
21 +
#' (columns):
21 22
#'
22 23
#' \describe{
23 24
#'
@@ -38,7 +39,12 @@
Loading
38 39
#'
39 40
#'  }
40 41
#'
41 -
#' @inherit add_contiguity_constraints return seealso
42 +
#' @inherit add_contiguity_constraints return
43 +
#'
44 +
#' @seealso
45 +
#' See [constraints] for an overview of all functions for adding constraints.
46 +
#'
47 +
#' @family constraints
42 48
#'
43 49
#' @examples
44 50
#' # set seed for reproducibility
@@ -124,7 +130,6 @@
Loading
124 130
#' spplot(s4, zcol = c("solution", "solution_locked"), axes = FALSE,
125 131
#'        box = FALSE)
126 132
#' }
127 -
#' @seealso [constraints].
128 133
#'
129 134
#' @name add_manual_locked_constraints
130 135
#'

@@ -21,9 +21,10 @@
Loading
21 21
#'
22 22
#' @inherit add_absolute_targets details
23 23
#'
24 -
#' @section Target data format:
24 +
#' @section Targets format:
25 25
#'
26 -
#'  The `targets` argument should contain the following fields (columns):
26 +
#' The `targets` argument should be a `data.frame` with the following
27 +
#' fields (columns):
27 28
#'
28 29
#' \describe{
29 30
#'
@@ -51,7 +52,10 @@
Loading
51 52
#' @return Object (i.e. [`ConservationProblem-class`]) with the targets added
52 53
#'   to it.
53 54
#'
54 -
#' @seealso [targets].
55 +
#' @seealso
56 +
#' See [targets] for an overview of all functions for adding targets.
57 +
#'
58 +
#' @family targets
55 59
#'
56 60
#' @examples
57 61
#' # set seed for reproducibility

@@ -11,7 +11,9 @@
Loading
11 11
#' customized to meet specific goals using [objectives],
12 12
#' [targets], [constraints], and
13 13
#' [penalties]. After building the problem, the
14 -
#'  [solve()] function can be used to identify solutions.
14 +
#' [solve()] function can be used to identify solutions.
15 +
#' **Note that problems require an objective, and failing to specify an
16 +
#' an objective will throw an error when attempting to solve it.**
15 17
#'
16 18
#' @param x [`Raster-class`],
17 19
#'   [sf::st_sf()],
@@ -141,69 +143,136 @@
Loading
141 143
#'
142 144
#' @param ... not used.
143 145
#'
144 -
#' @details A reserve design exercise starts by dividing the study region
145 -
#'   into planning units (typically square or hexagonal cells) and, for
146 -
#'   each planning unit, assigning values that quantify socioeconomic
147 -
#'   cost and conservation benefit for a set of conservation features. The
148 -
#'   cost can be the acquisition cost of the land, the cost of management,
149 -
#'   the opportunity cost of foregone commercial activities (e.g. from logging
150 -
#'   or agriculture), or simply the area. The conservation features are
151 -
#'   typically species (e.g. Clouded Leopard) or habitats (e.g. mangroves or
152 -
#'   cloud forest). The benefit that each feature derives from a planning unit
153 -
#'   can take a variety of forms, but is typically either occupancy (i.e.
154 -
#'   presence or absence) or area of occurrence within each planning unit.
155 -
#'   Finally, in some types of reserve design models, representation targets
156 -
#'   must be set for each conservation feature, such as 20% of the current
157 -
#'   extent of cloud forest or 10,000 km^2 of Clouded Leopard habitat
158 -
#'   (see [targets]).
146 +
#' @details
147 +
#' A systematic conservation planning exercise leverages data to help inform
148 +
#' conservation decision making. To help ensure that the
149 +
#' data -- and resulting prioritizations -- are relevant to the over-arching
150 +
#' goals of the exercise, you should decide on the management action
151 +
#' (or set of actions) that need be considered in the exercise.
152 +
#' For example, these actions could include establishing protected areas,
153 +
#' selecting land for conservation easements, restoring habitat,
154 +
#' planting trees for carbon sequestration, eradicating invasive
155 +
#' species, or some combination of the previous actions.
156 +
#' If the exercise involves multiple different actions, they can
157 +
#' be incorporated by using multiple zones
158 +
#' (see the Management Zones vignette for details). After deciding
159 +
#' on the management action(s), you can compile the following data.
159 160
#'
160 -
#'   The goal of the reserve design exercise is then to optimize the trade-off
161 -
#'   between conservation benefit and socioeconomic cost, i.e. to get the most
162 -
#'   benefit for your limited conservation funds. In general, the goal of an
163 -
#'   optimization problem is to minimize an objective function over a set of
164 -
#'   decision variables, subject to a series of constraints. The decision
165 -
#'   variables are what we control, usually there is one binary variable for
166 -
#'   each planning unit specifying whether or not to protect that unit (but
167 -
#'   other approaches are available, see [decisions]). The
168 -
#'   constraints can be thought of as rules that need to be followed, for
169 -
#'   example, that the reserve must stay within a certain budget or meet the
170 -
#'   representation targets.
161 +
#' First, you will need to create a set of planning units
162 +
#' (i.e. discrete spatial areas) to inform decision making.
163 +
#' Planning units are often created by subdividing a study region
164 +
#' into a set square or hexagonal cells. They can also be created using
165 +
#' administrative boundaries (e.g. provinces), land management boundaries
166 +
#' (e.g. property boundaries derived from cadastral data), or
167 +
#' ecological boundaries (e.g. based on ecosystem classification data).
168 +
#' The size (i.e. spatial grain) of the planning units is often determined
169 +
#' based on a compromise between the scale needed to inform decision making, the
170 +
#' spatial accuracy (resolution) of available datasets, and
171 +
#' the computational resources available for generating prioritizations
172 +
#' (e.g. RAM and number of CPUs on your computer).
171 173
#'
172 -
#'   Integer linear programming (ILP) is the subset of optimization algorithms
173 -
#'   used in this package to solve reserve design problems. The general form of
174 -
#'   an integer programming problem can be expressed in matrix notation using
175 -
#'   the following equation.
174 +
#' Second, you will need data to quantify the cost of implementing
175 +
#' implementing each management action within each planning unit.
176 +
#' Critically, the cost data should reflect the management action(s)
177 +
#' considered in the exercise.
178 +
#' For example, costs are often specified using data that reflect economic
179 +
#' expenditure (e.g. land acquisition cost),
180 +
#' socioeconomic conditions (e.g. human population density),
181 +
#' opportunity costs of foregone commercial activities
182 +
#' (e.g. logging or agriculture), or
183 +
#' opportunity costs of foregone recreational activities
184 +
#' (e.g. recreational fishing) activities,
185 +
#' In some cases -- depending on the management action(s) considered --
186 +
#' it can make sense to use a constant cost value
187 +
#' (e.g. all planning units are assigned a cost value equal to one)
188 +
#' or use a cost value based on spatial extent
189 +
#' (e.g. each planning unit is assigned a cost value based on its total area).
190 +
#' Also, in most cases, you want to avoid negative cost values.
191 +
#' This because a negative value means that a place is *desirable*
192 +
#' for implementing a management action, and such places will almost
193 +
#' always be selected for prioritization even if they provide no benefit.
176 194
#'
177 -
#'   \deqn{\mathit{Minimize} \space \mathbf{c}^{\mathbf{T}}\mathbf{x} \space
178 -
#'   \mathit{subject \space to} \space
179 -
#'   \mathbf{Ax}\geq= or\leq \mathbf{b}}{Minimize (c^T)*x subject to Ax \ge, =,
180 -
#'   or \le b}
195 +
#' Third, you will need data to quantify the benefits of implementing
196 +
#' management actions within planning units.
197 +
#' To achieve this, you will need to select a set of conservation features
198 +
#' that relate to the over-arching goals of the exercise.
199 +
#' For example, conservation features often include
200 +
#' species (e.g. Clouded Leopard), habitats (e.g. mangroves or
201 +
#' cloud forest), or ecosystems.
202 +
#' The benefit that each feature derives from a planning unit
203 +
#' can take a variety of forms, but is typically occupancy (i.e.
204 +
#' presence or absence), area of occurrence within each planning unit
205 +
#' (e.g. based on species' geographic range data), or
206 +
#' a measure of habitat suitability (e.g. estimated using a statistical model).
207 +
#' After compiling these data, you have the minimal data need to generate
208 +
#' a prioritization.
181 209
#'
182 -
#'   Here, \eqn{x} is a vector of decision variables, \eqn{c} and \eqn{b} are
183 -
#'   vectors of known coefficients, and \eqn{A} is the constraint
184 -
#'   matrix. The final term specifies a series of structural
185 -
#'   constraints where relational operators for the constraint can be either
186 -
#'   \eqn{\ge}, \eqn{=}, or \eqn{\le} the coefficients. For example, in the
187 -
#'   minimum set
188 -
#'   cover problem, \eqn{c} would be a vector of costs for each planning unit,
189 -
#'   \eqn{b} a vector of targets for each conservation feature, the relational
190 -
#'   operator would be \eqn{\ge} for all features, and \eqn{A} would be the
191 -
#'   representation matrix with \eqn{A_{ij}=r_{ij}}{Aij = rij}, the
192 -
#'   representation level of feature \eqn{i} in planning unit \eqn{j}.
210 +
#' A systematic conservation planning exercise involves prioritizing a set of
211 +
#' management actions to be implemented within certain planning units.
212 +
#' Critically, this prioritization should ideally optimize the trade-off