Creates the multi-action planning problem

Create the data object with information about the multi-action conservation planning problem. This function is used to specify all the data that defines the spatial prioritization problem (planning units data, feature data, threats data, and their spatial distributions.)

inputData(pu, features, dist_features, threats, dist_threats, ...)

# S4 method for data.frame,data.frame,data.frame,data.frame,data.frame
inputData(
  pu,
  features,
  dist_features,
  threats,
  dist_threats,
  sensitivity = NULL,
  boundary = NULL
)

Arguments

pu

Object of class data.frame() that specifies the planning units (PU) of the corresponding instance and their corresponding monitoring cost and status. Each row corresponds to a different planning unit. This file is inherited from the pu.dat in Marxan. It must contain the following columns:

id: integer unique identifier for each planning unit.
monitoring_cost: numeric cost of including each planning unit in the reserve system.
status: integer (optional) value that indicate if each planning unit should be available to be selected (0), locked-in (2) as part of the solution, or locked-out (3) and excluded from the solution.

features

Object of class data.frame() that specifies the conservation features to consider in the optimization problem. Each row corresponds to a different feature. This file is inherited from marxan's spec.dat.

The prioriactions package supports two types of purposes when optimizing: focus on recovery of features threatened (through the recovery target), where only take into account benefits when taking action against threats and there is no benefit when selecting planning units where the features are not threatened; or include the benefits of the features sites where they are not threatened (through the conservation target).

Note that by default only information on recovery targets is necessary, while conservation targets equal to zero are assumed. The maximum values of benefits to achieve both recovery and conservation per feature can be verified with the getPotentialBenefit() function. For more information on the implications of these targets in the solutions see the recovery vignette.

This file must contain the following columns:

id: integer unique identifier for each conservation feature.
target_recovery: numeric amount of recovery target to achieve for each conservation feature. This field is required if a minimizeCosts model is used.
target_conservation: numeric (optional) amount of conservation target to achieve for each conservation feature. This field is used only if a model of the type minimizeCosts is applied.
name: character (optional) name for each conservation feature.

dist_features

Object of class data.frame() that specifies the spatial distribution of conservation features across planning units. Each row corresponds to a combination of planning unit and feature. This file is inherited from marxan's puvspr.dat. It must contain the following columns:

pu: integer id of a planning unit where the conservation feature listed on the same row occurs.
feature: integer id of each conservation feature.
amount: numeric amount of the feature in the planning unit. Set to 1 to work with presence/absence.

threats

Object of class data.frame() that specifies the threats to consider in the optimization exercise. Each row corresponds to a different threats. It must contain the following columns:

id: integer unique identifier for each threat.
blm_actions: numeric (optional) penalty of connectivity between threats. Default is 0.
name: character (optional) name for each threat.

dist_threats

Object of class data.frame() that specifies the spatial distribution of threats across planning units. Each row corresponds to a combination of planning unit and threat. It must contain the following columns:

pu: integer id of a planning unit where the threat listed on the same row occurs.
threat: integer id of each threat.
amount: numeric amount of the threat in the planning unit. Set to 1 to work with presence/absence. Continuous amount values require that feature sensitivities to threats be established (more info in sensitivities vignette).
action_cost: numeric cost of an action to abate the threat in each planning unit.
status: integer (optional) value that indicates if each action to abate the threat is available to be selected (0), locked-in (2) as part of the solution, or locked-out (3) and therefore excluded from the solution.

...

Unused arguments, reserved for future expansion.

sensitivity

(optional) Object of class data.frame() that specifies the sensitivity of each feature to each threat. Each row corresponds to a combination of feature and threat. If not informed, all features are assumed to be sensitive to all threats.

Sensitivity can be parameterized in two ways: binary; the feature is sensitive or not, or continuous; with response curves of the probability of persistence of the features to threats. For the first case, it is only necessary to indicate the ids of the threats and the respective features sensitive to them. In the second case, the response can be parameterized through four values: \(\delta_1\), \(\delta_2\), \(\delta_3\) and \(\delta_4\). See sensitivities vignette for more information on continuous sensitivities. Then, the sensitivity input must contain the following columns:

feature: integer id of each conservation feature.
threat: integer id of each threat.
delta1: numeric (optional) the minimum intensity of the threat at which the features probability of persistence starts to decline. The more sensitive the feature is to the threat, the lowest this value will be. Default is 0.
delta2: numeric (optional) the value of intensity of the threat over which the feature has a probability of persistence of 0. If it is not established,it is assumed as the maximum value of the threat across all planning units in the study area. Note that this might overestimate the sensitivity of features to threats, as they will only be assumed to disappear from planning units if the threats reach the maximum intensity value in the study area.
delta3: numeric (optional) minimum probability of persistence of a features when a threat reaches its maximum intensity value. Default is 0.
delta4: numeric (optional) maximum probability of persistence of a features in absence threats. Default is 1.

Note that optional parameters delta1, delta2, delta3 and delta4 can be provided independently.

boundary

(optional) Object of class data.frame() that specifies the spatial relationship between pair of planning units. Each row corresponds to a combination of planning unit. This file is inherited from marxan's bound.dat. It must contain the following columns:

id1: integer id of each planning unit.
id2: integer id of each planning unit.
boundary: numeric penalty applied in the objective function when only one of the planning units is present in the solution.

Value

An object of class data.

References

Ball I, Possingham H, Watts, M. Marxan and relatives: software for spatial conservation prioritization. Spatial conservation prioritisation: quantitative methods and computational tools 2009.

Examples

## set seed for reproducibility
set.seed(14)

## Set prioriactions path
prioriactions_path <- system.file("extdata/example_input/", package = "prioriactions")

## Load in planning unit data
pu_data <- data.table::fread(paste0(prioriactions_path,"/pu.dat"),
                             data.table = FALSE)
head(pu_data)
#>   id monitoring_cost status
#> 1  1               2      0
#> 2  2               2      0
#> 3  3               2      0
#> 4  4               2      0
#> 5  5               2      0
#> 6  6               2      0

## Load in feature data
features_data <- data.table::fread(paste0(prioriactions_path,"/features.dat"),
                                   data.table = FALSE)
head(features_data)
#>   id target_recovery     name
#> 1  1              11 feature1
#> 2  2              16 feature2
#> 3  3               8 feature3
#> 4  4               9 feature4

## Load in planning unit vs feature data
dist_features_data <- data.table::fread(paste0(prioriactions_path,"/dist_features.dat"),
                                        data.table = FALSE)
head(dist_features_data)
#>   pu feature amount
#> 1  1       3      1
#> 2  2       3      1
#> 3  3       3      1
#> 4  4       3      1
#> 5  5       3      1
#> 6  6       3      1

## Load in the threats data
threats_data <- data.table::fread(paste0(prioriactions_path,"/threats.dat"),
                                  data.table = FALSE)
head(threats_data)
#>   id    name blm_actions
#> 1  1 threat1           0
#> 2  2 threat2           0

## Load in the threats distribution data
dist_threats_data <- data.table::fread(paste0(prioriactions_path,"/dist_threats.dat"),
                                       data.table = FALSE)
head(dist_threats_data)
#>   pu threat amount action_cost status
#> 1  8      2      1           2      0
#> 2  9      2      1           2      0
#> 3 10      2      1           2      0
#> 4 11      1      1           3      0
#> 5 11      2      1           4      0
#> 6 12      1      1           3      0

## Load in the sensitivity data
sensitivity_data <- data.table::fread(paste0(prioriactions_path,"/sensitivity.dat"),
                                      data.table = FALSE)
head(sensitivity_data)
#>   feature threat
#> 1       1      1
#> 2       2      1
#> 3       3      1
#> 4       4      1
#> 5       1      2
#> 6       2      2

## Load in the boundary data
boundary_data <- data.table::fread(paste0(prioriactions_path,"/boundary.dat"),
                                   data.table = FALSE)
head(boundary_data)
#>   id1 id2 boundary
#> 1   1   1        0
#> 2   2   1        1
#> 3   3   1        2
#> 4   4   1        3
#> 5   5   1        4
#> 6   6   1        5

## Create data instance
problem_data <- inputData(
  pu = sim_pu_data, features = sim_features_data, dist_features = sim_dist_features_data,
  threats = sim_threats_data, dist_threats = sim_dist_threats_data,
  sensitivity = sim_sensitivity_data, boundary = sim_boundary_data
)

## Summary
print(problem_data)
#> Data
#>   planning units: data.frame (100 units)
#>   monitoring costs:     min: 1, max: 10
#>   features:       feature1, feature2, feature3, feature4 (4 features)
#>   threats:        threat1, threat2 (2 threats)
#>   action costs:   min: 1, max: 10

Arguments

Value

References

See also

Examples