This function adds a constrain to a
`BiodiversityScenario`

object to constrain (future) projections.
These constrains can for instance be constraints on a possible dispersal
distance, connectivity between identified patches or limitations on species
adaptability.
**Most constrains require pre-calculated thresholds to present in the BiodiversityScenario object!**

## Arguments

- mod
A

`BiodiversityScenario`

object with specified predictors.- method
A

`character`

indicating the type of constraints to be added to the scenario. See details for more information.- ...
passed on parameters. See also the specific methods for adding constraints.

- value
For many dispersal

`"constrain"`

this is set as`numeric`

value specifying a fixed constrain or constant in units`"m"`

(Default:`NULL`

). For kissmig the value needs to give the number of iteration steps (or within year migration steps). For adaptability constraints this parameter specifies the extent (in units of standard deviation) to which extrapolations should be performed.- type
A

`character`

indicating the type used in the method. See for instance``kissmig``

.- layer
A

`SpatRaster`

object that can be used for boundary constraints (Default:`NULL`

).- pext
`numeric`

indicator for``kissmig``

of the probability a colonized cell becomes uncolonised, i.e., the species gets locally extinct (Default:`0.1`

).- pcor
`numeric`

probability that corner cells are considered in the 3x3 neighbourhood (Default:`0.2`

).

## Value

Adds constraints data to a `BiodiversityScenario`

object.

## Details

Constraints can be added to scenario objects to increase or decrease
the suitability of a given area for the target feature. This function acts
as a wrapper to add these constraints. Currently supported are the
following options:
**Dispersal**:

`sdd_fixed`

- Applies a fixed uniform dispersal distance per modelling timestep.`sdd_nexpkernel`

- Applies a dispersal distance using a negative exponential kernel from its origin.`kissmig`

- Applies the kissmig stochastic dispersal model. Requires``kissmig``

package. Applied at each modelling time step.`migclim`

- Applies the dispersal algorithm MigClim to the modelled objects. Requires`"MigClim"`

package.A comprehensive overview of the benefits of including dispersal constrains in species distribution models can be found in Bateman et al. (2013).

**Connectivity**:

`hardbarrier`

- Defines a hard barrier to any dispersal events. By definition this sets all values larger than`0`

in the barrier layer to`0`

in the projection. Barrier has to be provided through the`"resistance"`

parameter.`resistance`

- Allows the provision of a static or dynamic layer that is multiplied with the projection at each time step. Can for example be used to reduce the suitability of any given area (using pressures not included in the model). The respective layer(s) have to be provided through the`"resistance"`

parameter. Provided layers are incorporated as`abs(resistance - 1)`

and multiplied with the prediction.

**Adaptability**:

`nichelimit`

- Specifies a limit on the environmental niche to only allow a modest amount of extrapolation beyond the known occurrences. This can be particular useful to limit the influence of increasing marginal responses and avoid biologically unrealistic projections.

**Boundary**:

`boundary`

- Applies a hard boundary constraint on the projection, thus disallowing an expansion of a range outside the provide layer. Similar as specifying projection limits (see`distribution`

), but can be used to specifically constrain a projection within a certain area (e.g. a species range or an island).

## References

Bateman, B. L., Murphy, H. T., Reside, A. E., Mokany, K., & VanDerWal, J. (2013). Appropriateness of full‐, partial‐and no‐dispersal scenarios in climate change impact modelling. Diversity and Distributions, 19(10), 1224-1234.

Nobis MP and Normand S (2014) KISSMig - a simple model for R to account for limited migration in analyses of species distributions. Ecography 37: 1282-1287.

Mendes, P., Velazco, S. J. E., de Andrade, A. F. A., & Júnior, P. D. M. (2020). Dealing with overprediction in species distribution models: How adding distance constraints can improve model accuracy. Ecological Modelling, 431, 109180.

## Examples

```
if (FALSE) {
# Assumes that a trained 'model' object exists
mod <- scenario(model) |>
add_predictors(env = predictors, transform = 'scale', derivates = "none") |>
add_constraint_dispersal(method = "kissmig", value = 2, pext = 0.1) |>
project()
}
```