Calculate 2D dispersal kernel.

Use a probability function to create a 2D dispersal kernel matrix.

Usage

calculate_dispersal_kernel(max_dispersal_dist, kfun, normalize = TRUE, ...)

Arguments

max_dispersal_dist

<numeric> maximum dispersal distance in grid cells. The size (rows and columns) of the created dispersal kernel matrix will be 2 * max_dispersal_dist + 1.

kfun

<function> the probability function that is used to calculate the values for each cell of the dispersal kernel. Can be user-defined, in which case it needs to vectorized and accept (at least) the parameter "x" representing the distance from the source as its input and return a vector of the same size as max_dispersal_dist.

normalize

<boolean> whether to normalize the kernel (sum(kernel) == 1)).

...

additional parameters to be passed to the kernel function.

Value

Dispersal kernel with probabilities.

Details

This function first creates an matrix of size 2 * max_dispersal_dist + 1, where each cell contains the distance from the center of the cell to the center of the matrix. After that, the kernel function (kfun) is called with this matrix as input and expected to return a vector with the calculated probabilities for each cell. Lastly, the kernel is optionally normalized.

Examples

# a very simple uniform kernel
uniform_kernel <- calculate_dispersal_kernel(
    max_dispersal_dist = 2,
    kfun = function(x) {
        rep(1, length(x))
    },
    normalize = FALSE
)
# same as
stopifnot(
    uniform_kernel == matrix(1, nrow = 5, ncol = 5)
)

# How does the input matrix look like,
# that is used as input for `kfun`?
calculate_dispersal_kernel(
    max_dispersal_dist = 2,
    kfun = function(x) {
        return(x)
    },
    normalize = FALSE
)
#>          [,1]     [,2] [,3]     [,4]     [,5]
#> [1,] 2.828427 2.236068    2 2.236068 2.828427
#> [2,] 2.236068 1.414214    1 1.414214 2.236068
#> [3,] 2.000000 1.000000    0 1.000000 2.000000
#> [4,] 2.236068 1.414214    1 1.414214 2.236068
#> [5,] 2.828427 2.236068    2 2.236068 2.828427

# now a negative exponential kernel.
# note that `mean_dispersal_dist` is a parameter of
# the `negative_exponential_function`
# and is passed to `kfun` via the `...`.
calculate_dispersal_kernel(
    max_dispersal_dist = 2,
    kfun = negative_exponential_function,
    mean_dispersal_dist = 1
)
#>             [,1]        [,2]        [,3]        [,4]        [,5]
#> [1,] 0.001785687 0.005838778 0.009361987 0.005838778 0.001785687
#> [2,] 0.005838778 0.030211734 0.069176245 0.030211734 0.005838778
#> [3,] 0.009361987 0.069176245 0.511147159 0.069176245 0.009361987
#> [4,] 0.005838778 0.030211734 0.069176245 0.030211734 0.005838778
#> [5,] 0.001785687 0.005838778 0.009361987 0.005838778 0.001785687