add_corridor_constraints: Add corridor constraints
In prioritizr/prioritizrutils: Utilities for prioritizr

Description Usage Arguments Details Value See Also Examples

It is important to maintain connectivity throughout a reserve network. However, some areas are more difficult for species to traverse then other areas. As a consequence, even though a reserve may protect a contiguous section of land, some species may not be able to disperse throughout the network if some of the land is a high barrier to dispersal. This function adds constraints to ensure that all planning units used to represent features in the conservation problem are connected by planning units that have high connectivity.

1	add_corridor_constraints(x, connectivities, thresholds, ...)

`x`	`ConservationProblem-class` object.
`connectivities`	`object` used to calculate the the connectivity between planning units. See the Details section for more information.
`thresholds`	`numeric` value representing the minimum connectivity required between planning units for them to be considered connected for a given feature. Threshold values are expressed as a proportion of the total range of connectivity observed among all planning units for each feature. If a higher threshold is used, then planning units with lower conductances, and in turn, lower connectivity will not be considered to have strong enough connecitivity to form corridors to link planning units. If `thresholds` is a single number then it is used as the threshold for each feature. Otherwise, if `threshold` is a `vector` then it specifies the threshold for each feature.
`...`	additional arguments passed to `fast_extract` if the planning units in argument to `x` inherit from a `RasterStack-class` object.

This function adds constraints to a conservation planning probem to ensure that all planning units used to represent a given feature are connected to each other. To acheive this, each planning unit is associated with condunctance values that describe the ease at which individuals from each feature can disperse through it. Higher conductance values indicate that individuals can move planning units with greater ease. The connectivity between two planning units is calculated as the average conductance of the two planning units. After the connectivity values have been calculated, the threshold is applied to determine which planning units are "connected enough" to be used for linking planning units occupied by conspecifics. Adding these constraints to a problem will dramatically increase the amount of time required to solve it.

The argument to y can be used to specify the the connectivity between different planning units in several different ways:

character vector: If the planning units in argument to x inherit from a Spatial-class object then the argument to codey can refer to the names of the columns in the attribute table that contain the conductance values for each planning unit for each feature. It is assumed that the order of the column names in argument to y matches the order of the features in the argument to x.
RasterStack-class object: Each band corresponds to each feature in the argument to x. The cells in each band denote the conductance of an area. For a given feature, the condunctance of each planning unit is calculated by overlaying the planning units in argument to codex with the raster data in argument to conductance. Note that if the planning units in argument to x inherit from a Raster-class object, then the argument to codeconductance must have the same spatial properties as the planning units (ie. coordinate system, extent, resolution).
list of dsCMatrix-class matrices: Each element in the list corresponds to a different feature. Each row and column refers to a different planning unit, and the cell values denote the connectivity between the two planning units. Note that the connectivity between planning units is assumed to be symmetric.

ConservationProblem-class object.

constraints, penalties.

# load data
data(sim_pu_raster, sim_features)

# create a basic problem
p1 <- problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1)

# create problem with added corridor constraints to ensure that
# planning units used to represent features are connected by
# planning units with habitat that is suitable for that feature
p2 <- p1 %>% add_corridor_constraints(sim_features, 0.5)


# solve problems
s <- stack(solve(p1), solve(p2))

# plot solutions
plot(s, main = c("basic solution", "solution with corridors"))