This function creates an object that contains all the data,
parameters and settings for building an (integrated) species distribution
model. Key functions to add data are add_biodiversity_poipo
and the like,
add_predictors
, add_latent_spatial
, engine_glmnet
or similar,
add_priors
and add_offset
. It creates a prototype
BiodiversityDistribution
object with its own functions. After setting
input data and parameters, model predictions can then be created via the
train function and predictions be created.
Additionally, it is possible to specify a "limit"
to any predictions
conducted on the background. This can be for instance a buffered layer by a
certain dispersal distance (Cooper and Soberon, 2018) or a categorical layer
representing biomes or soil conditions. Another option is to create a
constraint by constructing a minimum convex polygon (MCP) using the supplied
biodiversity data. This option can be enabled by setting
"limits_method"
to "mcp"
. It is also possible to provide a
small buffer to constructed MCP that way. See the frequently asked question
(FAQ) section on the homepage for more information.
See Details for a description of the internal functions available to modify or summarize data within the created object.
Note that any model requires at minimum a single added biodiversity dataset as well as a specified engine.
Usage
distribution(
background,
limits = NULL,
limits_method = "none",
mcp_buffer = 0,
limits_clip = FALSE
)
# S4 method for class 'SpatRaster'
distribution(
background,
limits = NULL,
limits_method = "none",
mcp_buffer = 0,
limits_clip = FALSE
)
# S4 method for class 'sf'
distribution(
background,
limits = NULL,
limits_method = "none",
mcp_buffer = 0,
limits_clip = FALSE
)
Arguments
- background
Specification of the modelling background. Must be a
SpatRaster
orsf
object.- limits
A
SpatRaster
,sf
orstars
object that limits the prediction surface when intersected with input data (Default:NULL
). In case of astars
object the first factorized time entry is taken.- limits_method
A
character
of the method used for hard limiting a projection. Available options are"none"
(Default),"zones"
or"mcp"
. See alsoadd_limits_extrapolation()
.- mcp_buffer
A
numeric
distance to buffer the mcp (Default0
). Only used if"mcp"
is used.- limits_clip
logical
Should the limits clip all predictors before fitting a model (TRUE
) or just the prediction (FALSE
, default).
Value
BiodiversityDistribution
object containing data for building
a biodiversity distribution modelling problem.
Details
This function creates a BiodiversityDistribution
object
that in itself contains other functions and stores parameters and
(pre-)processed data. A full list of functions available can be queried via
"names(object)"
. Some of the functions are not intended to be
manipulated directly, but rather through convenience functions (e.g.
"object$set_predictors()"
). Similarly other objects are stored in the
BiodiversityDistribution
object that have their own functions as
well and can be queried (e.g. "names(object)"
). For a list of
functions see the reference documentation. By default, if some datasets are
not set, then a "Waiver"
object is returned instead.
The following objects can be stored:
object$biodiversity
ABiodiversityDatasetCollection
object with the added biodiversity data.object$engine
An"engine"
object (e.g.engine_inlabru()
) with function depended on the added engine.object$predictors
APredictorDataset
object with all set predictions.object$priors
APriorList
object with all specified priors.object$log
ALog
object that captures.
Useful high-level functions to address those objects are for instance:
object$show()
A generic summary of theBiodiversityDistribution
object contents. Can also be called via print.object$get_biodiversity_equations()
Lists the equations used for each biodiversity dataset with given id. Defaults to all predictors.object$get_biodiversity_types()
Lists the type of each specified biodiversity dataset with given id.object$get_extent()
Outputs the terra::ext of the modelling region.object$show_background_info()
Returns alist
with the terra::ext and the terra::crs.object$get_extent_dimensions()
Outputs the terra::ext dimension by calling the"extent_dimensions()"
function.object$get_predictor_names()
Returns a character vector with the names of all added predictors.object$get_prior_variables()
Returns a description ofpriors
added.
There are other functions as well but those are better accessed through their respective wrapper functions.
References
Fletcher, R.J., Hefley, T.J., Robertson, E.P., Zuckerberg, B., McCleery, R.A., Dorazio, R.M., (2019) A practical guide for combining data to model species distributions. Ecology 100, e02710. https://doi.org/10.1002/ecy.2710
Cooper, Jacob C., and Jorge Soberón. "Creating individual accessible area hypotheses improves stacked species distribution model performance." Global Ecology and Biogeography 27, no. 1 (2018): 156-165.
See also
BiodiversityDistribution
and other classes.
Examples
# Load background raster
background <- terra::rast(system.file("extdata/europegrid_50km.tif",package = "ibis.iSDM"))
# Define model
x <- distribution(background)
#> [Setup] 2024-10-08 19:46:43.018939 | Creating distribution object...
x
#> <Biodiversity distribution model>
#> Background extent:
#> xmin: -16.064, xmax: 36.322,
#> ymin: 34.95, ymax: 71.535
#> projection: +proj=longlat +datum=WGS84 +no_defs
#> ---------
#> Biodiversity data:
#> None
#> ---------
#> predictors: None
#> priors: <Default>
#> latent: None
#> log: <Console>
#> engine: <NONE>