prioriactions (version 0.5.0)

inputData: Creates the multi-action planning problem

Description

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.)

Usage

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
)

Value

An object of class data.

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.

References

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

See Also

For more information on the correct format for Marxan input data, see the official Marxan website and Ball et al. (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)

## Load in feature data
features_data <- data.table::fread(paste0(prioriactions_path,"/features.dat"),
                                   data.table = FALSE)
head(features_data)

## 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)

## Load in the threats data
threats_data <- data.table::fread(paste0(prioriactions_path,"/threats.dat"),
                                  data.table = FALSE)
head(threats_data)

## 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)

## Load in the sensitivity data
sensitivity_data <- data.table::fread(paste0(prioriactions_path,"/sensitivity.dat"),
                                      data.table = FALSE)
head(sensitivity_data)

## Load in the boundary data
boundary_data <- data.table::fread(paste0(prioriactions_path,"/boundary.dat"),
                                   data.table = FALSE)
head(boundary_data)

## 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)