-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
133 lines (95 loc) · 9.54 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
---
output:
rmarkdown::github_document:
html_preview: no
---
<!--- README.md is generated from README.Rmd. Please edit that file -->
# oppr: Optimal Project Prioritization
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://github.com/prioritizr/oppr/actions)
[](https://github.com/prioritizr/oppr/actions)
[](https://github.com/prioritizr/oppr/actions)
[](https://app.codecov.io/gh/prioritizr/oppr/branch/master)
[](https://CRAN.R-project.org/package=oppr)
```{r, include = FALSE}
knitr::opts_chunk$set(fig.path = "man/figures/README-", fig.align = "center")
```
```{r, include = FALSE}
devtools::load_all()
h = 3.5
w = 3.5
ow = "400"
```
The _oppr R_ package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact algorithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ['Gurobi' optimizer](https://www.gurobi.com) because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits.
## Installation
The latest official version of the _oppr R_ package can be installed from the [Comprehensive R Archive Network (CRAN)](https://cran.r-project.org/) using the following _R_ code.
```{r, eval = FALSE}
install.packages("oppr", repos = "https://cran.rstudio.com/")
```
Alternatively, the latest development version can be installed from [GitHub](https://github.com/prioritizr/oppr) using the following code. Please note that while developmental versions may contain additional features not present in the official version, they may also contain coding errors.
```{r, eval = FALSE}
if (!require(remotes)) install.packages("remotes")
remotes::install_github("prioritizr/oppr")
```
## Citation
To cite the _oppr R_ package in publications, please use:
> Hanson JO, Schuster R, Strimas-Mackey M & Bennett JR (2019) Optimality in prioritizing conservation projects. _Methods in Ecology & Evolution_, **10**: 1655--1663.
You can also use the following _R_ code to determine which version you have installed: `packageVersion("oppr")`
## Usage
Here we will provide a short example showing how the _oppr R_ package can be used to prioritize funding for conservation projects. To start off, we will set the seed for the random number generator to ensure you get the same results as shown here, and load the _oppr R_ package.
```{r}
set.seed(500)
library(oppr)
```
Now we will load some data sets that are distributed with the package. First, we will load the `sim_features` object. This table contains information on the conservation features (e.g. species). Specifically, each row corresponds to a different feature, and each column contains information associated with the features. In this table, the `"name"` column contains the name of each feature, and the `"weight"` column denotes the relative importance for each feature.
```{r, message = FALSE, warning = FALSE}
# load data
data(sim_features)
# print table
print(sim_features)
```
Next, we will load the `sim_actions` object. This table stores information about the various management actions (i.e. `tibble`). Each row corresponds to a different action, and each column describes different properties associated with the actions. These actions correspond to specific management actions that have known costs. For example, they may relate to pest eradication activities (e.g. trapping) in sites of conservation importance. In this table, the `"name"` column contains the name of each action, and the `"cost"` column denotes the cost of each action. It also contains additional columns for customizing the solutions, but we will ignore them for now. Note that the last action---the `"baseline_action"`---has a zero cost and is used with the a baseline project (see below).
```{r}
# load data
data(sim_actions)
# print table
print(sim_actions)
```
Additionally, we will load the `sim_projects` object. This table stores information about various conservation projects. Each row corresponds to a different project, and each column describes various properties associated with the projects. These projects correspond to groups of conservation actions. For example, a conservation project may pertain to a set of conservation actions that relate to a single feature or single geographic locality. In this table, the `"name"` column contains the name of each project, the `"success"` column denotes the probability of each project succeeding if it is funded, the `"F1"`--`"F5"` columns show the probability of each feature is expected to persist if each project is funded (`NA` values mean that a feature does not benefit from a project), and the `"F1_action"`--`"F5_action"` columns indicate which actions are associated with which projects. Note that the last project---the `"baseline_project"`---is associated with the `"baseline_action"` action. This project has a zero cost and represents the baseline probability of each feature persisting if no other project is funded. This is important because we can't find a cost-effective solution if we don't know how much better each project improves a species' chance at persistence. Finally, although most projects in this example directly relate to a single feature, you can input projects that directly affect the persistence of multiple features.
```{r}
# load data
data(sim_projects)
# print table
print(sim_projects, width = Inf)
```
After loading the data, we can begin formulating the project prioritization problem. Here our goal is to maximize the overall probability that each feature is expected to persist into the future (i.e. the feature richness), whilst also accounting for the relative importance of each feature and the fact that our resources are limited such that we can only spend at most $400 on funding management actions. Now, let's build a project prioritization problem object that represents our goal.
```{r}
# build problem
p <- problem(projects = sim_projects, actions = sim_actions,
features = sim_features, project_name_column = "name",
project_success_column = "success", action_name_column = "name",
action_cost_column = "cost", feature_name_column = "name") %>%
add_max_richness_objective(budget = 400) %>%
add_feature_weights(weight = "weight") %>%
add_binary_decisions() %>%
add_default_solver(verbose = FALSE)
# print problem
print(p)
```
Next, we can solve this problem to obtain a solution. By default, we will obtain the optimal solution to our problem using an exact algorithm solver (e.g. using [Gurobi](https://www.gurobi.com/) or [lpSolveAPI](https://cran.r-project.org/package=lpSolveAPI)).
```{r, message = FALSE, warning = FALSE}
# solve problem
s <- solve(p)
```
```{r}
# print solution
print(s, width = Inf)
```
The `s` table contains the solution and also various statistics associated with the solution. Here, each row corresponds to a different solution. Specifically, the `"solution"` column contains an identifier for the solution (which may be useful for methods that output multiple solutions), the `"obj"` column contains the objective value (i.e. the expected feature richness for this problem), the `"cost"` column stores the cost of the solution, and the `"status"` column contains information from the solver about the solution. Additionally, it contains columns for each action (`"F1_action"`, `"F2_actions"`, `"F3_actions"`, ..., `"baseline_action"`) which indicate if each action was prioritized for funding in the solution. Additionally, it contains columns for each project (`"F1_project"`, `"F2_project"`, `"F3_project"`, ..., `"baseline_project"`) that indicate if the project was completely funded or not. Finally, it contains column for each feature (`"F1`, `"F2"`, `"F3`, ...) which indicate the probability that each feature is expected to persist into the future under each solution (for information on how this is calculated see `?add_max_richness_objective`). Since tabular data can be difficult to understand, let's visualize how well this solution would conserve the features. Note that features which benefit from fully funded projects, excepting the baseline project, are denoted with an asterisk.
```{r "readme-plot"}
# visualize solution
plot(p, s)
```
This has just been a taster of the _oppr R_ package. For more information, see the [package vignette](https://prioritizr.github.io/oppr/articles/oppr.html).
## Getting help
If you have any questions about using the _oppr R_ package or suggestions for improving it, please [file an issue at the package's online code repository](https://github.com/prioritizr/oppr/issues/new).