This function has additional options compared to the more
generic `add_offset()`

, allowing customized options specifically for
expert-based ranges as offsets or spatialized polygon information on species
occurrences. If even more control is needed, the user is informed of the
`"bossMaps"`

package Merow et al. (2017). Some functionalities of that
package emulated through the `"distance_function"`

set to `"log"`

.
This tries to fit a 5-parameter logistic function to estimate the distance
from the range (Merow et al. 2017).

## Usage

```
add_offset_range(
x,
layer,
distance_max = Inf,
family = "poisson",
presence_prop = 0.9,
distance_clip = FALSE,
distance_function = "negexp",
field_occurrence = "observed",
fraction = NULL,
point = FALSE,
add = TRUE
)
# S4 method for BiodiversityDistribution,SpatRaster
add_offset_range(x, layer, fraction = NULL, add = TRUE)
# S4 method for BiodiversityDistribution,sf
add_offset_range(
x,
layer,
distance_max = Inf,
family = "poisson",
presence_prop = 0.9,
distance_clip = FALSE,
distance_function = "negexp",
field_occurrence = "observed",
fraction = NULL,
point = FALSE,
add = TRUE
)
```

## Arguments

- x
`distribution()`

(i.e.`BiodiversityDistribution`

) object.- layer
A

`sf`

or`SpatRaster`

object with the range for the target feature.- distance_max
A

`numeric`

threshold on the maximum distance beyond the range that should be considered to have a high likelihood of containing species occurrences (Default:`Inf`

`"m"`

). Can be set to`NULL`

or`0`

to indicate that no distance should be calculated.- family
A

`character`

denoting the type of model to which this offset is to be added. By default it assumes a`'poisson'`

distributed model and as a result the output created by this function will be log-transformed. If however a`'binomial'`

distribution is chosen, than the output will be``logit``

transformed. For integrated models leave at default.- presence_prop
`numeric`

giving the proportion of all records expected to be inside the range. By default this is set to`0.9`

indicating that 10% of all records are likely outside the range.- distance_clip
`logical`

as to whether distance should be clipped after the maximum distance (Default:`FALSE`

).- distance_function
A

`character`

specifying the distance function to be used. Available are linear (`"linear"`

), negative exponential kernels (`"negexp"`

, default) and a five parameters logistic curve (code"logcurve") as proposed by Merow et al. 2017.- field_occurrence
A

`numeric`

or`character`

location of biodiversity point records.- 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`

).- point
An optional

`sf`

layer with points or`logical`

argument. In the case of the latter the point data is ignored (Default:`FALSE`

).- add
`logical`

specifying whether new offset is to be added. Setting this parameter to`FALSE`

replaces the current offsets with the new one (Default:`TRUE`

).

## Value

Adds a range offset to a `distribution`

object.

## Details

The output created by this function creates a `SpatRaster`

to be
added to a provided distribution object. Offsets in regression models are
likelihood specific as they are added directly to the overall estimate of
``y^hat``

.

Note that all offsets created by this function are by default log-transformed
before export. Background values (e.g. beyond `"distance_max"`

) are set
to a very small constant (`1e-10`

).

## References

Merow, C., Wilson, A.M., Jetz, W., 2017. Integrating occurrence data and expert maps for improved species range predictions. Glob. Ecol. Biogeogr. 26, 243–258. https://doi.org/10.1111/geb.12539

Merow, C., Allen, J.M., Aiello-Lammens, M., Silander, J.A., 2016. Improving niche and range estimates with Maxent and point process models by integrating spatially explicit information. Glob. Ecol. Biogeogr. 25, 1022–1036. https://doi.org/10.1111/geb.12453

## See also

`"bossMaps"`

Other offset:
`add_offset()`

,
`add_offset_bias()`

,
`add_offset_elevation()`

,
`rm_offset()`

## Examples

```
if (FALSE) {
# Train a presence-only model with a simple offset
fit <- distribution(background) |>
add_biodiversity_poipo(virtual_points, field_occurrence = "Observed") |>
add_predictors(predictors) |>
add_offset_range(virtual_range, distance_max = 5,distance_function = "logcurve",
distance_clip = TRUE ) |>
engine_glm() |>
train()
}
```