LatticeTransitionProbs: Calculate Lattice-Based Dispersal Probabilities

In ecomodtools: Ecological Modelling Toolbox

Description

A function to approximate continuous dispersal on a lattice. A matrix of lattice transition probabilities can be calculated using any of four approximation methods and using any of three commonly applied boundary conditions. This function uses the analytically derived results for some regularly used dispersal kernels, or, otherwise performs Monte Carlo integration to derive the transition probabilities for any arbitrary dispersel kernel.

Usage

LatticeTransitionProbs(x1, x2, y1, y2, func, approx.method = "AA", boundary = "absorbing", max.prob = .Machine$double.eps^0.25, initial.step = 10000, step.size = 10000, max.rel.var = .Machine$double.eps^0.25, max.runs = 1000000, params = NULL, ...)

Arguments

x1	A vector of lower boundary coordinates on the x-axis for each cell for which the transition probabilities are required
x2	A vector of upper boundary coordinates on the x-axis for each cell for which the transition probabilities are required
y1	A vector of lower boundary coordinates on the y-axis for each cell for which the transition probabilities are required
y2	A vector of upper boundary coordinates on the y-axis for each cell for which the transition probabilities are required
func	A two-dimensional dispersal kernel function describing the probability of moving from one set of Cartesian coordinates to another set of Cartesian coordinates. The dispersal kernel parameter list must contain the items from, to, and params. The from parameter is a two element vector with the fist element containing the x-coordinate of the starting location and the second element containing the y-coordinate of the starting location. Similarly, the vector to parameter contains the x and y coordinates of the destination location. params is an object used to pass further information to the dispersal kernel. params can be any R object type but needs to be present in the parameter list even if it is not used. The dispersal kernel must return a single probability parameter. Alternatively, func can be set to the value "gaussian", in which case the analytical results for Gaussian dispersal are used instead.
approx.method	A single string to set the approximation method to use. "CC" will perform centroid-to-centroid dispersal, "CA" will perform centroid-to-area dispersal, "AC" will perform area-to-centroid dispersal, and, finally, "AA" performs area-to-area dispersal.
boundary	A single string to set the boundary condition to use. This can be set to either "restricting", "absorbing", or "periodic" to implement restricting, absorbing, or periodic boundary conditions respectively.
max.prob	A value to set the stopping condition when evaluating the infinite series under periodic boundary conditions.
initial.step	Parameter used in Monte Carlo integration. An integer containing the initial number of integrand evaluations to perform before testing the series for a stopping condition. This value must be larger than one.
step.size	Parameter used in Monte Carlo integration. An integer containing the number of integrand evaluations to perform in every testing step. After the initial number of evaluations are made (set using the initial.step parameter) a test is made for the algorithm stopping condition every step.size iterations. This value must be larger than one.
max.rel.var	Parameter used in Monte Carlo integration. The maximum relative variance allowed for the integral estimate before the stopping condition is met. This value must be larger than zero.
max.runs	Parameter used in Monte Carlo integration. The maximum number of integrand evaluations to perform before the algorithm is stopped. This value must be larger than one.
params	Extra parameters to pass to the dispersal kernel function.
...	Further parameters to pass to the dispersal kernel function.

Details

The func parameter must return the two dimensional probability density for any given set of source and destination coordinates. This is sometimes confused with other forms of dispersal description. To avoid this confusion, we designate the input function corresponding to g(r) as defined in chapter 5 of Cousens et al. (2008).

If "gaussian" is selected as the input function then analytical results are used to generate the transition matrix rather than Monte Carlo integration and the initial.step, step.size, max.rel.var, and max.runs parameters are not used. For Gaussian dispersal we use the parameterisation described in Clark et al. (1999) with a parameter, alpha, set using the params parameter.

The max.prob parameter is only used if boundary is set to "periodic". This value determines the stopping condition for evaluating an infinite series when calculating periodic boundary correction. Values closer to zero will result in a better approximation but increase the running time of the algorithm.

Value

A matrix of transition probabilities for each cell in the lattice, calculated using the set approximation method and boundary conditions. The final and row and column of the transition matrix represent an extra absorbing state, with the final row containing the probabilities of dispersing to any area not contained by the set of cells. Travel from the absorbing state is disallowed and so all the elements of the final column are zero except for a value of 1 at the bottom left corner of the transition matrix.

Note

This function requires optimisation. For large lattices and the employment of periodic boundary conditions this function can take considerable time to run, even on fast systems. Run times can often exceed 24 hours.

Author(s)

Joseph Chipperfield <[e-mail]>

References

Clark, J. S., Silman, M., Kern, R., Macklin, E. and HilleRisLambers, J. (1999) Seed dispersal near and far: patterns across temperate and tropical forests. Ecology, 80, 1475-1494.

Cousens, R., Dytham, C. and Law, R. (2008) Dispersal in Plants: A Population Perspective, Oxford University Press.

See Also

MakeGridFromCoords MCIntegration

Examples

# 2D Gaussian dispersal function defined according to Clark et al. (1999)
# Used in the Monte Carlo integration
genexp.disp <- function(from, to, params)
{
	r.sq <- (from[1] - to[1])^2 + (from[2] - to[2])^2
	(1.0 / (pi * params[1]^2)) * exp(-(r.sq / params[1]^2))
}

# Monte Carlo integration settings
max.prob <- .Machine$double.eps^0.25
initial.step <- 10000
step.size <- 10000
max.runs <- 1000000
max.rel.var <- .Machine$double.eps^0.25

# Boundary condition
boundary <- "restricting"

# Alpha parameter setting
params <- c(1.0)

# Make a small grid (3 x 3) for testing purposes
x.coords <- seq(0.0, 3.0, 1.0)
y.coords <- seq(0.0, 3.0, 1.0)
test.grid <- MakeGridFromCoords(x.coords, y.coords)

# Calculate the transition matrices for each different approximation method

# Centroid-to-centroid transition matrix using Monte Carlo integration
CC.mc <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = genexp.disp, approx.method = "CC", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)
# Centroid-to-centroid transition matrix using analytic results
CC.an <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = "gaussian", approx.method = "CC", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)

# Centroid-to-area transition matrix using Monte Carlo integration
CA.mc <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = genexp.disp, approx.method = "CA", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)
# Centroid-to-area transition matrix using analytic results
CA.an <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = "gaussian", approx.method = "CA", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)

# Area-to-centroid transition matrix using Monte Carlo integration
AC.mc <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = genexp.disp, approx.method = "AC", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)
# Area-to-centroid transition matrix using analytic results
AC.an <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = "gaussian", approx.method = "AC", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)

# Area-to-area transition matrix using Monte Carlo integration
AA.mc <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = genexp.disp, approx.method = "AA", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)
# Area-to-area transition matrix using analytic results
AA.an <- LatticeTransitionProbs(
	x1 = test.grid$x1, x2 = test.grid$x2, y1 = test.grid$y1, y2 = test.grid$y2,
	func = "gaussian", approx.method = "AA", boundary = boundary, max.prob = max.prob,
	initial.step = initial.step, step.size = step.size, max.rel.var = max.rel.var, max.runs = max.runs, params = params)

# Calculate the differences between the analytic and Monte Carlo results
diff.CC <- CC.mc - CC.an
diff.CA <- CA.mc - CA.an
diff.AC <- AC.mc - AC.an
diff.AA <- AA.mc - AA.an

ecomodtools documentation built on May 2, 2019, 4:58 p.m.