prioritizr (version 3.0.4)

problem: Conservation planning problem

Description

Create a systematic conservation planning problem. This function is used to specify the basic data used in a spatial prioritization problem: the spatial distribution of the planning units and their costs, as well as the features (e.g. species, ecosystems) that need to be conserved. After constructing this ConservationProblem-class object, it can be customized to meet specific goals using objectives, targets, constraints, and penalties.

Usage

# S4 method for Raster,Raster
problem(x, features, run_checks = TRUE, ...)
# S4 method for Spatial,Raster
problem(x, features, cost_column, run_checks = TRUE, ...)
# S4 method for data.frame,data.frame
problem(x, features, rij, ...)
# S4 method for numeric,data.frame
problem(x, features, rij_matrix, ...)
# S4 method for data.frame,character
problem(x, features, cost_column, ...)
# S4 method for Spatial,character
problem(x, features, cost_column, ...)

Arguments

x

Raster-class, SpatialPolygonsDataFrame-class, SpatialLinesDataFrame-class, or data.frame object, or numeric vector, specifying the planning units to use in the reserve design exercise and their corresponding cost. It may be desirable to exclude some planning units from the analysis, for example those outside the study area. To exclude planning units, set the cost for those raster cells to NA, or use the add_locked_out_constraint.

features

The correct argument for features depends on the input to x.

Raster-class, Spatial-class

Raster-class object showing the distribution of conservation features. Missing values (i.e. NA values) can be used to indicate the absence of a feature in a particular cell instead of explicitly setting these cells to zero.

Spatial, data.frame

character vector with column names that correspond to the abundance or occurrence of different features in each planning unit.

Spatial, data.frame or numeric

data.frame object containing information on the features. The argument to feature_data must follow the conventions used by Marxan. Each row corresponds to a different feature. It must also contain the following columns:

"id"

integer unique identifier for each feature These identifiers are used in the argument to rij.

"name"

character name for each feature.

"prop"

numeric relative target for each feature (optional).

"amount"

numeric absolute target for each feature (optional).

cost_column

character name or integer indicating the column with the cost data. This argument must be supplied when the argument to x is a link{Spatial} or data.frame object.

rij

data.frame containing information on the amount of each feature in each planning unit. This argument is only used if x is a data.frame. Similar to features, the argument to rij must follow the conventions used by Marxan. It must contain the following columns:

"pu"

integer planning unit identifier.

"species"

integer feature identifier.

"amount"

numeric amount of the feature in the planning unit.

rij_matrix

matrix or dgCMatrix-class object specifying the amount of each feature (rows) within each planning unit (columns). Only used when x is a numeric vector of costs.

run_checks

logical flag indicating whether checks should be run to ensure the integrity of the input data. These checks are run by default; however, for large data sets they may substantially increase run time. If it is taking a prohibitively long time to create the prioritization problem, it is suggested to try setting run_checks to FALSE.

...

not used.

Value

A ConservationProblem-class object containing the basic data used to build a prioritization problem.

Details

The basic prioritizr work flow starts with formulating the problem, then adding objectives and targets, as well as constraints and penalties as needed. Alternative decision formats can be specified using the decisions functions, otherwise the package will default to binary selection of planning units. Lastly, the type of solving algorithm must be specified (see solvers). Once formulated, the problem is solved using the solve() function, which will return a RasterLayer-class, Spatial-class, or a numeric vector containing the solution depending on the ConservationProblem-class

A reserve design exercise starts by dividing the study region into planning units (typically square or hexagonal cells) and, for each planning unit, assigning values that quantify socioeconomic cost and conservation benefit for a set of conservation features. The cost can be the acquisition cost of the land, the cost of management, the opportunity cost of foregone commercial activities (e.g. from logging or agriculture), or simply the area. The conservation features are typically species (e.g. Clouded Leopard) or habitats (e.g. mangroves or cloud forest). The benefit that each feature derives from a planning unit can take a variety of forms, but is typically either occupancy (i.e. presence or absence) or area of occurrence within each planning unit. Finally, in some types of reserve design models, for each conservation feature, representation targets must be set, such as 20 extent of cloud forest or 10,000km^2 of Clouded Leopard habitat (see targets).

The goal of the reserve design exercise is then to optimize the trade-off between conservation benefit and socioeconomic cost, i.e. to get the most benefit for your limited conservation funds. In general, the goal of an optimization problem is to minimize an objective function over a set of decision variables, subject to a series of constraints. The decision variables are what we control, usually there is one binary variable for each planning unit specifying whether or not to protect that unit (but other approaches are available, see decisions). The constraints can be thought of as rules that need to be followed, for example, that the reserve must stay within a certain budget or meet the representation targets.

Integer linear programming (ILP) is the subset of optimization algorithms used in this package to solve reserve design problems. The general form of an ILP problem can be expressed in matrix notation as:

$$\mathit{Minimize} \space \mathbf{c}^{\mathbf{T}}\mathbf{x} \space \mathit{subject \space to} \space \mathbf{Ax}\geq= or\leq \mathbf{b}$$

Where x is a vector of decision variables, c and b are vectors of known coefficients, and A is the constraint matrix. The final term specifies a series of structural constraints where relational operators for the constraint can be either \(\ge, =, or \le\) the coefficients. For example, in the minimum set cover problem, c would be a vector of costs for each planning unit, b a vector of targets for each conservation feature, the relational operator would be \(\ge\) for all features, and A would be the representation matrix with \(A_{ij}=r_{ij}\), the representation level of feature i in planning unit j.

See Also

constraints, decisions, objectives penalties, portfolios, problem, solvers, targets.

Examples

# NOT RUN {
# create problem using raster planning unit data
p1 <- problem(sim_pu_raster, sim_features) %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# create problem using polygon planning unit data
p2 <- problem(sim_pu_polygons, sim_features, "cost") %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# create problem using line planning unit data
p3 <- problem(sim_pu_lines, sim_features, "cost") %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# create problem using point planning unit data
p4 <- problem(sim_pu_points, sim_features, "cost") %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# add columns to polygon planning unit data representing the abundance
# of species inside them
sim_pu_polygons$spp_1 <- rpois(length(sim_pu_polygons), 5)
sim_pu_polygons$spp_2 <- rpois(length(sim_pu_polygons), 8)
sim_pu_polygons$spp_3 <- rpois(length(sim_pu_polygons), 2)

# create problem using pre-processed data when feature abundances are
# stored in the columns of an attribute table for a spatial vector data set
p5 <- problem(sim_pu_polygons, features = c("spp_1", "spp_2", "spp_3"),
              "cost") %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# alternatively one can supply pre-processed aspatial data
costs <- sim_pu_polygons$cost
features <- data.frame(id = seq_len(nlayers(sim_features)),
                       name = names(sim_features))
rij_mat <- rij_matrix(sim_pu_polygons, sim_features)
p6 <- problem(costs, features, rij_matrix = rij_mat) %>%
      add_min_set_objective() %>%
      add_relative_targets(0.2) %>%
      add_binary_decisions()

# }
# NOT RUN {
# solve problems
s1 <- solve(p1)
s2 <- solve(p2)
s3 <- solve(p3)
s4 <- solve(p4)
s5 <- solve(p5)
s6 <- solve(p6)

# plot solutions for problems associated with spatial data
par(mfrow = c(3, 2), mar = c(0, 0, 4.1, 0))
plot(s1, main = "raster data", axes = FALSE, box = FALSE)

plot(s2, main = "polygon data")
plot(s2[s2$solution_1 == 1, ], col = "darkgreen", add = TRUE)

plot(s3, main = "line data")
lines(s3[s3$solution_1 == 1, ], col = "darkgreen", lwd = 2)

plot(s4, main = "point data", pch = 19)
points(s4[s4$solution_1 == 1, ], col = "darkgreen", cex = 2, pch = 19)

plot(s5, main = "preprocessed data", pch = 19)
plot(s5[s5$solution_1 == 1, ], col = "darkgreen", add = TRUE)

# show solutions for problems associated with aspatial data
str(s6)
# }
# NOT RUN {
# }