Add penalties to a conservation planning problem to account for symmetric connectivity between planning units. Symmetric connectivity data describe connectivity information that is not directional. For example, symmetric connectivity data could describe which planning units are adjacent to each other (see adjacency_matrix()), or which planning units are within threshold distance of each other (see proximity_matrix()).

## Usage

# S4 method for ConservationProblem,ANY,ANY,matrix

# S4 method for ConservationProblem,ANY,ANY,Matrix

# S4 method for ConservationProblem,ANY,ANY,data.frame

# S4 method for ConservationProblem,ANY,ANY,dgCMatrix

# S4 method for ConservationProblem,ANY,ANY,array
add_connectivity_penalties(x, penalty, zones, data)

## Arguments

x

problem() object.

penalty

numeric penalty that is used to scale the importance of selecting planning units with strong connectivity between them compared to the main problem objective (e.g., solution cost when the argument to x has a minimum set objective set using add_min_set_objective()). Higher penalty values can be used to obtain solutions with a high degree of connectivity, and smaller penalty values can be used to obtain solutions with a small degree of connectivity. Note that negative penalty values can be used to obtain solutions that have very little connectivity.

zones

matrix or Matrix object describing the level of connectivity between different zones. Each row and column corresponds to a different zone in the argument to x, and cell values indicate the level of connectivity between each combination of zones. Cell values along the diagonal of the matrix represent the level of connectivity between planning units allocated to the same zone. Cell values must lay between 1 and -1, where negative values favor solutions with weak connectivity. The default argument to zones is an identity matrix (i.e., a matrix with ones along the matrix diagonal and zeros elsewhere), so that planning units are only considered to be connected when they are allocated to the same zone. This argument is required when working with multiple zones and the argument to data is a matrix or Matrix object. If the argument to data is an array or data.frame with data for multiple zones (e.g., using the "zone1" and "zone2" column names), this argument must explicitly be set to NULL otherwise an error will be thrown.

data

matrix, Matrix, data.frame, or array object containing connectivity data. The connectivity values correspond to the strength of connectivity between different planning units. Thus connections between planning units that are associated with higher values are more favorable in the solution. See the Data format section for more information.

## Value

An updated problem() object with the penalties added to it.

## Details

This function adds penalties to conservation planning problem to penalize solutions that have low connectivity. Specifically, it favors pair-wise connections between planning units that have high connectivity values (based on Önal and Briers 2002).

## Data format

The argument to data can be specified using several different formats.

data as a matrix/Matrix object

where rows and columns represent different planning units and the value of each cell represents the strength of connectivity between two different planning units. Cells that occur along the matrix diagonal are treated as weights which indicate that planning units are more desirable in the solution. The argument to zones can be used to control the strength of connectivity between planning units in different zones. The default argument for zones is to treat planning units allocated to different zones as having zero connectivity.

data as a data.frame object

containing columns that are named "id1", "id2", and "boundary". Here, each row denotes the connectivity between a pair of planning units (per values in the "id1" and "id2" columns) following the Marxan format. If the argument to x contains multiple zones, then the "zone1" and "zone2" columns can optionally be provided to manually specify the connectivity values between planning units when they are allocated to specific zones. If the "zone1" and "zone2" columns are present, then the argument to zones must be NULL.

data as an array object

containing four-dimensions where cell values indicate the strength of connectivity between planning units when they are assigned to specific management zones. The first two dimensions (i.e., rows and columns) indicate the strength of connectivity between different planning units and the second two dimensions indicate the different management zones. Thus the data[1, 2, 3, 4] indicates the strength of connectivity between planning unit 1 and planning unit 2 when planning unit 1 is assigned to zone 3 and planning unit 2 is assigned to zone 4.

## Mathematical formulation

The connectivity penalties are implemented using the following equations. Let $$I$$ represent the set of planning units (indexed by $$i$$ or $$j$$), $$Z$$ represent the set of management zones (indexed by $$z$$ or $$y$$), and $$X_{iz}$$ represent the decision variable for planning unit $$i$$ for in zone $$z$$ (e.g., with binary values one indicating if planning unit is allocated or not). Also, let $$p$$ represent the argument to penalty, $$D$$ represent the argument to data, and $$W$$ represent the argument to zones.

If the argument to data is supplied as a matrix or Matrix object, then the penalties are calculated as:

$$\sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz} \times X_{jy} \times D_{ij} \times W_{zy})$$

Otherwise, if the argument to data is supplied as a data.frame or array object, then the penalties are calculated as:

$$\sum_{i}^{I} \sum_{j}^{I} \sum_{z}^{Z} \sum_{y}^{Z} (-p \times X_{iz} \times X_{jy} \times D_{ijzy})$$

Note that when the problem objective is to maximize some measure of benefit and not minimize some measure of cost, the term $$-p$$ is replaced with $$p$$.

In previous versions, this function aimed to handle both symmetric and asymmetric connectivity data. This meant that the mathematical formulation used to account for asymmetric connectivity was different to that implemented by the Marxan software (see Beger et al. for details). To ensure that asymmetric connectivity is handled in a similar manner to the Marxan software, the add_asym_connectivity_penalties() function should now be used for asymmetric connectivity data.