# 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

 `1` ```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.

## 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.

`MakeGridFromCoords` `MCIntegration`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77``` ```# 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 ```