# Calculate Lattice-Based Dispersal Probabilities

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

`x2` |
A vector of upper boundary coordinates on the |

`y1` |
A vector of lower boundary coordinates on the |

`y2` |
A vector of upper boundary coordinates on the |

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

`approx.method` |
A single string to set the approximation method to use. |

`boundary` |
A single string to set the boundary condition to use. This can be set to either |

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

`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 <joechip90@googlemail.com>

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

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

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker. Vote for new features on Trello.