make.DemandPoints: Generate demand points for RAP

Description

This function generates demand points to characterize a distribution of points.

Usage

make.DemandPoints(
  points,
  n = 100L,
  quantile = 0.5,
  kernel.method = c("ks", "hypervolume")[1],
  ...
)

Value

A new DemandPoints() object.

Arguments

points: base::matrix() object containing points.
n: integer number of demand points to use for each attribute space for each species. Defaults to 100L.
quantile: numeric quantile to generate demand points within. If 0 then demand points are generated across the full range of values the points intersect. Defaults to 0.5.
kernel.method: character name of kernel method to use to generate demand points. Defaults to 'ks'.
...: arguments passed to kernel density estimating functions

Details

Broadly speaking, demand points are generated by fitting a kernal to the input points. A shape is then fit to the extent of the kernal, and then points are randomly generated inside the shape. The demand points are generated as random points inside the shape. The weights for each demand point are calculated the estimated density of input points at the demand point. By supplying 'ks' as an argument to method in kernel.method, the shape is defined using a minimum convex polygon adehabitatHR::mcp() and ks::kde() is used to fit the kernel. Note this can only be used when the data is low-dimensional (d < 3). By supplying "hypervolume" as an argument to method, the hypervolume::hypervolume() function is used to create the demand points. This method can be used for hyper-dimensional data (\(d << 3\)).

Examples

Run this code

if (FALSE) {
# set random number generator seed
set.seed(500)

# load data
cs_spp <- terra::rast(
  system.file("extdata", "cs_spp.tif", package = "raptr")
)
cs_space <- terra::rast(
  system.file("extdata", "cs_space.tif", package = "raptr")
)

# generate species points
species.points <- randomPoints(cs_spp[[1]], n = 100, prob = TRUE)
env.points <- as.matrix(terra::extract(cs_space, species.points))

# generate demand points for a 1d space using ks
dps1 <- make.DemandPoints(points = env.points[, 1], kernel.method = "ks")

# print object
print(dps1)

# generate demand points for a 2d space using hypervolume
dps2 <- make.DemandPoints(
  points = env.points,
  kernel.method = "hypervolume",
  samples.per.point = 50,
  verbose = FALSE
)

# print object
print(dps2)
}