# Add a range of a species as predictor to a distribution object

Source:`R/add_predictors.R`

`add_predictor_range.Rd`

This function allows to add a species range which is usually
drawn by experts in a separate process as spatial explicit prior. Both `sf`

and `SpatRaster`

-objects are supported as input.

Users are advised to look at the `"bossMaps"`

R-package presented as
part of Merow et al. (2017), which allows flexible calculation of non-linear
distance transforms from the boundary of the range. Outputs of this package
could be added directly to this function.
**Note that this function adds the range as predictor and not as offset. For this purpose a separate function add_offset_range() exists.**

Additional options allow to include the range either as `"binary"`

or as
`"distance"`

transformed predictor. The difference being that the range
is either directly included as presence-only predictor or alternatively with
a linear distance transform from the range boundary. The parameter
`"distance_max"`

can be specified to constrain this distance transform.

## Usage

```
add_predictor_range(
x,
layer,
method = "distance",
distance_max = NULL,
fraction = NULL,
priors = NULL
)
# S4 method for BiodiversityDistribution,SpatRaster
add_predictor_range(
x,
layer,
method = "precomputed_range",
fraction = NULL,
priors = NULL
)
# S4 method for BiodiversityDistribution,sf
add_predictor_range(
x,
layer,
method = "distance",
distance_max = Inf,
fraction = NULL,
priors = NULL
)
```

## Arguments

- x
`distribution()`

(i.e.`BiodiversityDistribution`

) object.- layer
A

`sf`

or`SpatRaster`

object with the range for the target feature.- method
`character`

describing how the range should be included (`"binary"`

|`"distance"`

).- distance_max
Numeric threshold on the maximum distance (Default:

`NULL`

).- fraction
An optional

`SpatRaster`

object that is multiplied with digitized raster layer. Can be used to for example to remove or reduce the expected value (Default:`NULL`

).- priors
A

`PriorList`

object. Default is set to NULL which uses default prior assumptions.

## References

Merow, C., Wilson, A. M., & Jetz, W. (2017). Integrating occurrence data and expert maps for improved species range predictions. Global Ecology and Biogeography, 26(2), 243–258. https://doi.org/10.1111/geb.12539

## Examples

```
if (FALSE) {
distribution(background) |>
add_predictor_range(range, method = "distance", distance_max = 2)
}
```