Randomly prioritize conservation projects under expected phylogenetic diversity

Generate random solutions for the 'Project Prioritization Protocol' problem (Joseph, Maloney & Possingham 2009) and evaluate them using 'expected phylogenetic diversity' (Faith 2008). Although conservation projects should, ideally, not be funded based on random allocations, it can be useful to compare the effectiveness of solutions to random decisions in order to evaluate their effectiveness. When informing conservation actions, it is strongly recommended to use the ppp_exact_phylo_solution method because it can identify optimal funding schemes with a guarantee.

ppp_random_phylo_solution(x, y, tree, budget, project_column_name,
  success_column_name, action_column_name, cost_column_name,
  locked_in_column_name = NULL, locked_out_column_name = NULL,
  number_solutions = 1L)

Arguments

x	data.frame or tibble table containing project data. Here, each row should correspond to a different project and columns should contain data that correspond to each project. This object should contain data that denote (i) the name of each project (specified in the argument to project_column_name), (ii) the probability that each project will succeed if all of its actions are funded (specified in the argument to success_column_name), (iii) the enhanced probability that each species will persist if it is funded, and (iv) and which actions are associated with which projects (specified in the action names in the argument to y). To account for the combined benefits of multiple actions (e.g. baiting and trapping different invasive species in the same area), additional projects should be created that indicate the combined cost and corresponding species' persistence probabilities. Furthermore, this object must have a baseline project, with a zero cost, that represents the probability that each species will persist if no other conservation project is funded.
y	data.frame or tibble table containing the action data. Here, each row should correspond to a different action and columns should contain data that correspond to each action. This object should contain data that denote (i) the name of each action (specified in the argument to action_column_name), (ii) the cost of each action (specified in the argument to cost_column_name). If certain actions should be locked in or out of the solution, then this object should also contain data that denote (iii) which actions should be locked in (specified using the argument to locked_in_column_name if relevant) and (iv) which actions should be locked out (specified using the argument to locked_out_column_name if relevant).
tree	phylo phylogenetic tree describing the evolutionary history of the species affected by the conservation projects that could potentially be funded. Note that every single species that is affected by the various conservation projects should be represented in this tree.
budget	numeric value that represents the total budget available for funding conservation actions.
project_column_name	character name of column that contains the name for each conservation project. This argument corresponds to the argument to x. Note that the project names must not contain any duplicates or missing values.
success_column_name	character name of column that denotes the probability that each project will succeed. This argument corresponds to the argument to x. This column must have numeric values which lay between zero and one. No missing values are permitted.
action_column_name	character name of column that contains the name for each conservation action. This argument corresponds to the argument to y. Note that the project names must not contain any duplicates or missing values.
cost_column_name	character name of column that indicates the cost for funding each action. This argument corresponds to the argument to y. This column must have numeric values which are equal to or greater than zero. No missing values are permitted.
locked_in_column_name	character name of column that indicates which actions should be locked into the funding scheme. This argument corresponds to the argument to y. For example, it may be desirable to mandate that projects for iconic species are funded in the prioritization. This column should contain logical values, and projects associated with TRUE values are locked into the solution. No missing values are permitted. Defaults to NULL such that no projects are locked into the solution.
locked_out_column_name	character name of column that indicates which actions should be locked out of the funding scheme. This argument corresponds to the argument to y. For example, it may be desirable to lock out projects for certain species that are expected to have little support from the public. This column should contain logical values, and projects associated with TRUE values are locked out of the solution. No missing values are permitted. Defaults to NULL such that no projects are locked out of the solution.
number_solutions	numeric number of solutions to return. If the argument is greater than 1, then the output will contain the set number of solutions that are closest to optimality. No missing values are permitted. Defaults to 1.

Details

Each random solution is generated using the following algorithm. Firstly, all actions are initially selected for funding (excepting actions which are locked out). Secondly, an action is randomly selected and defunded. Thirdly, the second step is repeated until the total cost of the remaining actions that are prioritized for funding is within the budget. Note that actions that have zero cost are never deselected for funding, and are always included in the solutions. Additionally, actions that are locked in are never deselected for funding.

References

Faith DP (2008) Threatened species and the potential loss of phylogenetic diversity: conservation scenarios based on estimated extinction probabilities and phylogenetic risk analysis. Conservation Biology, 22: 1461--1470.

Joseph LN, Maloney RF & Possingham HP (2009) Optimal allocation of resources among threatened species: A project prioritization protocol. Conservation Biology, 23, 328--338.

See also

For other methods for generating solutions for the 'Project Prioritization Protocol' problem using phylogenetic data, see ppp_heuristic_phylo_solution ppp_exact_phylo_solution, and ppp_manual_phylo_solution. To visualize the effectiveness of a particular solution, see ppp_plot_phylo_solution.

Examples

# set seed for reproducibility
set.seed(500)

# load built-in data
data(sim_project_data, sim_action_data, sim_tree)

# print simulated project data
print(sim_project_data)
#> # A tibble: 6 x 13
#>   name  success    S1    S2     S3    S4    S5 S1_action S2_action S3_action
#>   <chr>   <dbl> <dbl> <dbl>  <dbl> <dbl> <dbl> <lgl>     <lgl>     <lgl>    
#> 1 S1_p~   0.919 0.791 0     0      0     0     TRUE      FALSE     FALSE    
#> 2 S2_p~   0.923 0     0.888 0      0     0     FALSE     TRUE      FALSE    
#> 3 S3_p~   0.829 0     0     0.502  0     0     FALSE     FALSE     TRUE     
#> 4 S4_p~   0.848 0     0     0      0.690 0     FALSE     FALSE     FALSE    
#> 5 S5_p~   0.814 0     0     0      0     0.617 FALSE     FALSE     FALSE    
#> 6 base~   1     0.298 0.250 0.0865 0.249 0.182 FALSE     FALSE     FALSE    
#> # ... with 3 more variables: S4_action <lgl>, S5_action <lgl>,
#> #   baseline_action <lgl>

# print simulated action data
print(sim_action_data)
#> # A tibble: 6 x 4
#>   name             cost locked_in locked_out
#>   <chr>           <dbl> <lgl>     <lgl>     
#> 1 S1_action        94.4 FALSE     FALSE     
#> 2 S2_action       101.  FALSE     FALSE     
#> 3 S3_action       103.  TRUE      FALSE     
#> 4 S4_action        99.2 FALSE     FALSE     
#> 5 S5_action        99.9 FALSE     TRUE      
#> 6 baseline_action   0   FALSE     FALSE     

# print simulated phylogenetic tree data
print(sim_tree)
#> 
#> Phylogenetic tree with 5 tips and 4 internal nodes.
#> 
#> Tip labels:
#> [1] "S3" "S1" "S5" "S2" "S4"
#> 
#> Rooted; includes branch lengths.

# plot the simulated phylogeny
plot(sim_tree, main = "simulated phylogeny")

# generate 10 random solutions that meet a budget of 300
s1 <- ppp_random_phylo_solution(sim_project_data, sim_action_data, sim_tree,
                                300, "name", "success", "name", "cost",
                                number_solutions = 10)

# print solutions
print(s1)
#> # A tibble: 10 x 12
#>    solution method   obj budget  cost optimal S1_action S2_action S3_action
#>       <int> <chr>  <dbl>  <dbl> <dbl> <lgl>   <lgl>     <lgl>     <lgl>    
#>  1        1 random  2.92    300  295. NA      TRUE      TRUE      FALSE    
#>  2        2 random  2.60    300  297. NA      TRUE      FALSE     TRUE     
#>  3        3 random  2.64    300  200. NA      FALSE     TRUE      FALSE    
#>  4        4 random  2.50    300  299. NA      TRUE      TRUE      TRUE     
#>  5        5 random  2.20    300  298. NA      TRUE      FALSE     TRUE     
#>  6        6 random  2.50    300  299. NA      TRUE      TRUE      TRUE     
#>  7        7 random  1.96    300  203. NA      FALSE     FALSE     TRUE     
#>  8        8 random  2.50    300  295. NA      TRUE      TRUE      FALSE    
#>  9        9 random  2.20    300  298. NA      TRUE      FALSE     TRUE     
#> 10       10 random  2.28    300  202. NA      FALSE     FALSE     TRUE     
#> # ... with 3 more variables: S4_action <lgl>, S5_action <lgl>,
#> #   baseline_action <lgl>

# plot first solution
ppp_plot_phylo_solution(sim_project_data, sim_action_data, sim_tree, s1,
                        "name", "success", "name", "cost", n = 1)

# view histogram of their expected phylogenetic diversity
hist(s1$obj, xlab = "Expected phylogenetic diversity")

# view histogram of their costs
hist(s1$cost, xlab = "Solution cost ($)")