mobsim (version 0.1.0)

sim_thomas_coords: Simulate clumped spatial coordinates

Description

Add clumped (aggregated) positions to a species abundance distribution. Clumping is simulated using a Thomas cluster process, also known as Poisson cluster process (Morlon et al. 2008, Wiegand & Moloney 2014)

Usage

sim_thomas_coords(abund_vec, sigma = 0.02, mother_points = NA,
  cluster_points = NA, xrange = c(0, 1), yrange = c(0, 1))

Arguments

abund_vec

Species abundance vector (integer)

sigma

Mean displacement (along each coordinate axes) of a point from its mother point (= cluster centre). Sigma correlates with cluster extent. When length(sigma) == length(abund_vec), each species receives a specific cluster extent. Otherwise, the first value of sigma is recycled and all species share the same cluster extent. When sigma of any species is more than twice as large as the largest plot dimension, a random Poisson distribution is simulated, which is more efficient than a Thomas cluster process. The parameter sigma corresponds to the scale parameter of the function rThomas in the package spatstat.

mother_points

Number of mother points (= cluster centres). If this is a single value, all species have the same number of clusters. For example mother_points = 1 can be used to simulate only one cluster per species, which then represents the complete species range. If mother_points is a vector of the same length as abund_vec, each species has a specific number of clusters. If no value is provided, the number of clusters is determined from the abundance and the number of points per cluster (cluster_points).

cluster_points

Mean number of points per cluster. If this is a single value, species have the same average number of points per cluster. If this is a vector of the same length as abund_vec, each species has a specific mean number of points per cluster. If no value is provided, the number of points per cluster is determined from the abundance and from mother_points. The parameter cluster_points corresponds to the mu parameter of spatstat::rThomas.

xrange

Extent of the community in x-direction (numeric vector of length 2)

yrange

Extent of the community in y-direction (numeric vector of length 2)

Value

A community object as defined by community.

Details

To generate a Thomas cluster process of a single species this function uses a C++ re-implementation of the function rThomas in the package spatstat.

There is an inherent link between the parameters abund_vec, mother_points, and cluster_points. For every species the abundance has to be equal to the number of clusters (mother_points) times the number of points per cluster (cluster_points).

$$abundance = mother_points * cluster_points$$

Accordingly, if one of the parameters is provided, the other one is directly calculated from the abundance. Values for mother_points override values for cluster_points. If none of the parameters is specified, it is assumed that for every species there is a similar number of clusters and of points per cluster.

$$mother_points = cluster_points = \sqrt(abundance),$$

In this case rare species have few clusters with few points per cluster, while abundant species have many clusters with many points per cluster.

References

Morlon et al. 2008. A general framework for the distance-decay of similarity in ecological communities. Ecology Letters 11, 904-917.

Wiegand and Moloney 2014. Handbook of Spatial Point-Pattern Analysis in Ecology. CRC Press

See Also

rThomas

Examples

# NOT RUN {
abund <- c(10,20,50,100)
sim1 <- sim_thomas_coords(abund, sigma = 0.02)
plot(sim1)

# Simulate species "ranges"
sim2 <- sim_thomas_coords(abund, sigma = 0.02, mother_points = 1)
plot(sim2)

# Equal numbers of points per cluster
sim3 <- sim_thomas_coords(abund, sigma = 0.02, cluster_points = 5)
plot(sim3)

# With large sigma the distribution will be essentially random (see Details)
sim4 <- sim_thomas_coords(abund, sigma = 10)
plot(sim4)

# }