simulate_ptm_data {oppr}

Simulate data for 'Priority threat management'

Description

Simulate data for developing project prioritizations for a priority threat management exercise (Carwardine et al. 2019). Here, data are simulated for a pre-specified number of features, actions, and projects. Features can benefit from multiple projects, and different projects can share actions.

Usage

simulate_ptm_data(
  number_projects,
  number_actions,
  number_features,
  cost_mean = 100,
  cost_sd = 5,
  success_min_probability = 0.7,
  success_max_probability = 0.99,
  funded_min_persistence_probability = 0.5,
  funded_max_persistence_probability = 0.9,
  baseline_min_persistence_probability = 0.01,
  baseline_max_persistence_probability = 0.4,
  locked_in_proportion = 0,
  locked_out_proportion = 0
)

Arguments

number_projects

numeric number of projects. Note that this does not include the baseline project.

number_actions

numeric number of actions. Note that this does not include the baseline action.

number_features

numeric number of features.

cost_mean

numeric average cost for the actions. Defaults to 100.

cost_sd

numeric standard deviation in action costs. Defaults to 5.

success_min_probability

numeric minimum probability of the projects succeeding if they are funded. Defaults to 0.7.

success_max_probability

numeric maximum probability of the projects succeeding if they are funded. Defaults to 0.99.

funded_min_persistence_probability

numeric minimum probability of the features persisting if projects are funded and successful. Defaults to 0.5.

funded_max_persistence_probability

numeric maximum probability of the features persisting if projects are funded and successful. Defaults to 0.9.

baseline_min_persistence_probability

numeric minimum probability of the features persisting if only the baseline project is funded. Defaults to 0.01.

baseline_max_persistence_probability

numeric maximum probability of the features persisting if only the baseline project is funded. Defaults to 0.4.

locked_in_proportion

numeric of actions that are locked into the solution. Defaults to 0.

locked_out_proportion

numeric of actions that are locked into the solution. Defaults to 0.

Details

The simulated data set will contain one conservation project for each features, and also a "baseline" (do nothing) project to reflect features' persistence when their conservation project is not funded. Each conservation project is associated with a single action, and no conservation projects share any actions. Specifically, the data are simulated as follows:

1. A specified number of conservation projects, features, and management actions are created.

2. Cost data for each action are simulated using a normal distribution and the cost_mean and cost_sd arguments.

3. A set proportion of the actions are randomly set to be locked in and out of the solutions using the locked_in_proportion and locked_out_proportion arguments.

4. The probability of each project succeeding if its action is funded is simulated by drawing probabilities from a uniform distribution with the upper and lower bounds set as the success_min_probability and success_max_probability arguments.

5. The probability of each feature persisting if various projects are funded and is successful is simulated by drawing probabilities from a uniform distribution with the upper and lower bounds set as the funded_min_persistence_probability and funded_max_persistence_probability arguments. To prevent

6. An additional project is created which represents the "baseline" (do nothing) scenario. The probability of each feature persisting when managed under this project is simulated by drawing probabilities from a uniform distribution with the upper and lower bounds set as the baseline_min_persistence_probability and baseline_max_persistence_probability arguments.

7. A phylogenetic tree is simulated for the features using ape::rcoal().

8. Feature data are created from the phylogenetic tree. The weights are calculated as the amount of evolutionary history that has elapsed between each feature and its last common ancestor.

Value

A list object containing the elements:

"projects"

A tibble::tibble() containing the data for the conservation projects. It contains the following columns:

"name"

character name for each project.

"success"

numeric probability of each project succeeding if it is funded.

"F1" ... "FN"

numeric columns for each feature, ranging from "F1" to "FN" where N is the number of features, indicating the enhanced probability that each feature will persist if it funded. Missing values (NA) indicate that a feature does not benefit from a project being funded.

"F1_action" ... "FN_action"

logical columns for each action, ranging from "F1_action" to "FN_action" where N is the number of actions (equal to the number of features in this simulated data), indicating if an action is associated with a project (TRUE) or not (FALSE).

"baseline_action"

logical column indicating if a project is associated with the baseline action (TRUE) or not (FALSE). This action is only associated with the baseline project.

"actions"

A tibble::tibble() containing the data for the conservation actions. It contains the following columns:

"name"

character name for each action.

"cost"

numeric cost for each action.

"locked_in"

logical indicating if certain actions should be locked into the solution.

"locked_out"

logical indicating if certain actions should be locked out of the solution.

"features"

A tibble::tibble() containing the data for the conservation features (e.g. species). It contains the following columns:

"name"

character name for each feature.

"weight"

numeric weight for each feature. For each feature, this is calculated as the amount of time that elapsed between the present and the features' last common ancestor. In other words, the weights are calculated as the unique amount of evolutionary history that each feature has experienced.

"tree"

ape::phylo() phylogenetic tree for the features.

References

Carwardine J, Martin TG, Firn J, Ponce-Reyes P, Nicol S, Reeson A, Grantham HS, Stratford D, Kehoe L, Chades I (2019) Priority Threat Management for biodiversity conservation: A handbook. Journal of Applied Ecology, 56: 481–490.

See Also

simulate_ppp_data().

Examples

# create a simulated data set
s <- simulate_ptm_data(number_projects = 6,
                       number_actions = 8,
                       number_features = 5,
                       cost_mean = 100,
                       cost_sd = 5,
                       success_min_probability = 0.7,
                       success_max_probability = 0.99,
                       funded_min_persistence_probability = 0.5,
                       funded_max_persistence_probability = 0.9,
                       baseline_min_persistence_probability = 0.01,
                       baseline_max_persistence_probability = 0.4,
                       locked_in_proportion = 0.01,
                       locked_out_proportion = 0.01)

# print data set
print(s)