Dispersal.jl

Dispersal.DispersalModule

Dispersal.jl

CI codecov.io

Dispersal.jl is a collection of rules for organism growth and dispersal that can be used for modelling a wide range of ecological problems, and easily extended and combined with custom rules and other packages. Dispersal.jl extends DynamicGrids.jl, a high-performance grid-based modelling framework with clean syntax.

Spotted wing drosophola dispersal

A simulation of the spotted-wing drosophola invasion of the continental United States as detailed in Maino, Schouten, and Umina (2021)

Growth rates, dispersal kernels, Allee effects, and randomised jump and human assisted dispersal rules are provided. These components can be combined into complex dispersal models. Custom rules can easily added and combined with the provided set. See the documentation for examples and the lists of included rules.

DynamicGridsInteract provides an interactive interface for atom and jupyter notbooks (InteractOuput), desktop (ElectronOutput) and online web applications (ServerOuput), where complete models, including your custom rules, can be manipulated during live simulations.

DynamicGridsGtk provides GtkOutput for a simple graphical viewer.

GrowthMaps.jl can efficiently generate summarised raster data for vital rates (e.g. intrinsic growth rates) based on higher resolution and shorter interval environmental data.

source

Growth rules

Dispersal.ExponentialGrowthType
ExponentialGrowth <: CellRule

ExponentialGrowth(; rate, timestep, [nsteps_type])
ExponentialGrowth{R}(; rate, timestep, [nsteps_type])
ExponentialGrowth{R,W}(; rate, timestep, [nsteps_type])

Exponential growth of population size N based on an intrinsic growth rate $r$, using the exact solution between timesteps $t$ and $t-1$:

\[N_t = N_{t-1}e^{r t}\]

Keywords

  • rate: Intrinsic growth rate. May be a Number, an Aux array or another Grid.
  • timestep: Time step for the growth rate calculation, in a type compatible with the simulation tspan.
  • nsteps_type: Specify the floating point type to use when nsteps is generated from the timestep, if it is required for type-stability or performance. The default is Float64.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source
Dispersal.LogisticGrowthType
LogisticGrowth <: GrowthRule

LogisticGrowth(; rate, carrycap, timestep, [nsteps_type])
LogisticGrowth{R}(; rate, carrycap, timestep, [nsteps_type])
LogisticGrowth{R,W}(; rate, carrycap, timestep, [nsteps_type])

Logistic growth rate of population size $N$ based on an intrinsic growth rate $r$ and carry capacity $K$, using the exact solution between timesteps $t+1$ and $t$:

\[N_{t+1} = (N_t K) / (N_t + (K - N_t) e^{-rt})\]

Saturation only applies with positive growth.

Keywords

These may be a Number, an Aux array or another Grid:

  • rate: Intrinsic growth rate.
  • carrycap: Carrying capacity.
  • timestep: Time step for the growth rate, in a type compatible with the simulation tspan.
  • nsteps_type: Specify the floating point type to use when nsteps is generated from the timestep, if it is required for type-stability or performance. The default is Float64.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source
Dispersal.ThresholdGrowthType
ThresholdGrowth <: CellRule

ThresholdGrowth(; rate, threshold)
ThresholdGrowth{R}(; rate, threshold)
ThresholdGrowth{R,W}(; rate, threshold)

Simple threshold mask. Values below a certain threshold are replaced with zero.

Keywords

These may be a Number, an Aux array or another Grid.

  • rate: Intrinsic growth rate.
  • threshold: Minimum viability threshold below which population falls to zero.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source

Mortality

Dispersal.MortalityType
Mortality <: CellRule

Abstract super type for rules of survival effect For best performance these should be chained with other CellRule or following an NeighborhoodRule.

source
Dispersal.ExponentialMortalityType
ExponentialMortality <: Mortality

ExponentialMortality(; rate, threshold, timestep, [nsteps_type])
ExponentialMortality{R}(; rate, threshold, timestep, [nsteps_type])
ExponentialMortality{R,W}(; rate, threshold, timestep, [nsteps_type])

Exponential mortality based on exposure threshold and mortality rate parameter, using exact solution.

Exponential mortality based on exposure grid $X$, an exposure threshold parameter $z$ and a mortality rate $r$ using exact solution between time $t$ and `$t+1$:

\[N_{t+1} = N_{t}e^{-r t(X-z)}\]

Keywords

  • rate: Mortality rate.
  • threshold: Exposure threshold under which there is no effect.
  • timestep: Time step for the growth rate, in a type compatible with the simulation tspan.
  • nsteps_type: Specify the floating point type to use when nsteps is generated from the timestep, if it is required for type-stability or performance. The default is Float64.

rate and threshold can be a Number, an Aux array or another Grid`.

Pass grid Symbols to R or both R and W type parameters to use to specific grids. R is a 2 Grids NamedTuple like Tuple{:population,:exposure} and W return only the first grid :population.

source
Dispersal.LoglogisticMortalityType
LoglogisticMortality <: Mortality

LoglogisticMortality(; median, hillcoefficient, timestep, [nsteps_type])
LoglogisticMortality{R}(; median, hillcoefficient, timestep, [nsteps_type])
LoglogisticMortality{R,W}(; median, hillcoefficient, timestep, [nsteps_type])

Loglogistic mortality based on median, $α$ and hill coefficient $β$.

Cumulative function of loglogistic:

\[F(x; α, β) = x^β/(α^β + x^β)\]

where $α>0$ is the scale and $β>0$ is the shape.

Keywords

  • median: Median of the loglogistic function
  • hillcoefficient: Hill's coefficient, a measure of ultrasensitivity (i.e. how steep is the response curve). May be a Number, an Aux array or another Grid.
  • timestep: Time step for the mortality rate, in a type compatible with the simulation tspan.

Pass grid Symbols to R or both R and W type parameters to use to specific grids. R is a 2 Grids NamedTuple like Tuple{:population,:exposure} and W return only the first grid :population.

source

Allee effects

Dispersal.AlleeExtinctionType
AlleeExtinction <: CellRule

AlleeExtinction(minfounders)
AlleeExtinction{R}(; minfounders=5.0)
AlleeExtinction{R,W}(minfounders)

Causes extinction in a cell when a population is below a minimum number of individuals.

  • minfounders: minimum founding individuals required for a viable population. Must be a type that can be compared to the grid values using isless.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source

Local dispersal rules

Dispersal.InwardsDispersalType
InwardsPopulationDispersal <: NeighborhoodRule

InwardsPopulationDispersal(; kw...)
InwardsPopulationDispersal{R}(; kw...)
InwardsPopulationDispersal{R,W}(; kw...)

Implements deterministic dispersal from populations in neighboring cells to the current cell.

The result should be identical to those obtained substituting InwardsDispersal for OutwardsDispersal but will perform better when populations are spread across the grid.

Keywords

  • neighborhood: Any DynamicGrids.jl Neighborhood, or an already constructed DispersalKernel. Using this keyword means radius is ignored, and for a DispersalKernel, all other keywords are ignored.
  • neighborhood: Neighborhood object specifying the range from the origin of the discretised dispersal kernal. Defaults to Window(radius).
  • formulation: kernel formulation object holding the exact form of the kernal. Default ExponentialKernel.
  • cellsize: the cell size of the discretised kernal (i.e. simulation grid size). Default is 1.0.
  • distancemethod: DistanceMethod object for calculating distance between cells. The default is CentroidToCentroid.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source
Dispersal.OutwardsDispersalType
OutwardsPopulationDispersal <: SetNeighborhoodRule

OutwardsPopulationDispersal(; kw...)
OutwardsPopulationDispersal{R}(; kw...)
OutwardsPopulationDispersal{R,W}(; kw...)

Implements deterministic dispersal from the current cell to populations in neighboring cells.

This will make sense ecologically where cell populations are large, otherwise a randomised kernel may be more suitable.

The result should be identical to those obtained substituting OutwardsDispersal for InwardsDispersal but may be more efficient when a small number of cells are occupied. Conversely, it will become less efficient when a large proportion of the grid is occupied.

Keywords

  • neighborhood: Any DynamicGrids.jl Neighborhood, or an already constructed DispersalKernel. Using this keyword means radius is ignored, and for a DispersalKernel, all other keywords are ignored.
  • neighborhood: Neighborhood object specifying the range from the origin of the discretised dispersal kernal. Defaults to Window(radius).
  • formulation: kernel formulation object holding the exact form of the kernal. Default ExponentialKernel.
  • cellsize: the cell size of the discretised kernal (i.e. simulation grid size). Default is 1.0.
  • distancemethod: DistanceMethod object for calculating distance between cells. The default is CentroidToCentroid.

Pass grid name Symbols to R and W type parameters to use specific grids.

source

Dispersal kernels

Kernels extend DynamicGrids.Neighborhood, and use neighbors() methods.

Dispersal.DispersalKernelType
DispersalKernel <: AbstractKernelNeighborhood

DispersalKernel(; kw...)

Dispersal kernel for taking the dot product of the neighborhood and a matching kernel of weights. May hold any Neighborhood object: the kernel will be built to match the shape, using the folumation, cellsize and distancemethod.

Keyword Arguments

  • neighborhood: Any DynamicGrids.jl Neighborhood, or an already constructed DispersalKernel. Using this keyword means radius is ignored, and for a DispersalKernel, all other keywords are ignored.
  • neighborhood: Neighborhood object specifying the range from the origin of the discretised dispersal kernal. Defaults to Window(radius).
  • formulation: kernel formulation object holding the exact form of the kernal. Default ExponentialKernel.
  • cellsize: the cell size of the discretised kernal (i.e. simulation grid size). Default is 1.0.
  • distancemethod: DistanceMethod object for calculating distance between cells. The default is CentroidToCentroid.
source
Dispersal.KernelFormulationType
abstract type KernelFormulation
KernelFormulation

Abstract supertype for functors that calculate the probability density based on distance.

Concrete implementations must define functor methods with the form:

(k::SomeKernel)(distance) = # do something with `distance` and `k`"

Using an anonymous function would not allow rebuildable model parameters.

source
Dispersal.ExponentialKernelType
ExponentialKernel <: KernelFormulation

ExponentialKernel(λ)

Probability density function of distance $d$.

\[y = e^{-d/λ}\]

where λ is a shape parameter.

source
Dispersal.GeometricKernelType
GeometricKernel <: KernelFormulation

GeometricKernel(α)

Probability density function of distance $d$.

The Geometric kernel has a power-law decrease.

\[y = (1+d)^α (α+1)(α+2) / (2 π)\]

where α is a shape parameter.

source
Dispersal.GaussianKernelType
GaussianKernel <: KernelFormulation

GaussianKernel(α)

Probability density function of distance $d$.

\[y = 1/ (π α^2) e^{-d^2/α^2} \]

where α is a positive parameter.

source
Dispersal.WeibullKernelType
WeibullKernel <: KernelFormulation

WeibullKernel(α,β)

Probability density function of distance $d$.

\[y =β /(2 π α^2) d^{β-2} e^{ -d^β/α^β} \]

where α and β are positive parameters.

source

Distance methods

Dispersal kernels can be calculated in a number of ways, giving different properties and dispersal rates due to interactions between the cell size and the dispersal distance.

Dispersal.DistanceMethodType
abstract type DistanceMethod
DistanceMethod

Abstract supertype for methods of calculating distances and discretised dispersal probabilities between cells in a grid. between cells in a grid.

Distance calculation methods include:

Which are adapted from: "On the approximation of continuous dispersal kernels in discrete-space models, Joseph D. Chipperfield et al 2011"

The CentroidToArea method has not been implemented.

source
Dispersal.CentroidToCentroidType
struct CentroidToCentroid <: DistanceMethod
CentroidToCentroid <: DistanceMethod

CentroidToCentroid()

Calculates the discrete probability of dispersal between source and destination cell centroids. This is the naive method, but it will not handle low grid resolution well due to severe truncation.

See: "On the approximation of continuous dispersal kernels in discrete-space models, Joseph D. Chipperfield et al 2011"

source
Dispersal.AreaToCentroidType
AreaToCentroid <: DistanceMethod

AreaToCentroid(subsampling)
AreaToCentroid(; subsampling=10.0)

Calculates the discrete probability of dispersal between source cell area and destination centroid.

See: "On the approximation of continuous dispersal kernels in discrete-space models, Joseph D. Chipperfield et al 2011"

source
Dispersal.AreaToAreaType
AreaToArea <: DistanceMethod

AreaToArea(subsampling)
AreaToArea(; subsampling=10.0)

Calculates the discrete probability of dispersal between source and destination based on cell areas.

See: "On the approximation of continuous dispersal kernels in discrete-space models, Joseph D. Chipperfield et al 2011"

source

Jump dispersal

Dispersal.JumpDispersalType
JumpDispersal <: SetCellRule

JumpDispersal(; prob_threshold, spotrange)
JumpDispersal{R}(; prob_threshold, spotrange)
JumpDispersal{R,W}(; prob_threshold, spotrange)

Jump dispersal simulates a random long distance dispersal event, which occurs at a given probablity. A random cell within the spotrange is invaded by duplicating the entire population of the source cell at the destination cell.

Keyword Arguments

  • prob_threshold: probability of dispersal, between one and zero. May be a Number, an Aux array or another Grid:
  • spotrange: number of cells in range of jumps, in any direction.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source

Human driven dispersal

Dispersal.HumanDispersalType
HumanDispersal <: SetCellRule

HumanDispersal{R,W}(; kw...)

Implements human-driven dispersal patterns using population density data.

The number of long-distance migrants from an origin is set proportional to the level of human population with the coefficient dispersalperpop. The destination of long-distance migration is is calculated by using the distance $d$ between and human population $H$ at origin cell $i$ and destination cell $j$ through a simple gravity function:

\[g_{i,j} = (H_i H_j)^β/(d_{i,j})^γ\]

where $β$ (human_exponent) and $γ$ (dist_exponent) are parameters. For each grid cell, a shortlist of size nshortlisted of the destination cells with the highest gravity are selected for use in the simulation.

The time taken for precalulation will depend on the scale argument. Values above 1 will downsample the grid to improve precalulation time and runtime performance. A high scale value is good for use in a live interface.

Keywords

  • mode: Dispersal mode: Defaults to BatchGroups(), otherwise HeirarchicalGroups().
  • human_pop: An array match the grid size containing human population data.
  • cellsize: The size of the cell width, assuming they are square
  • scale: Downscaling factor to reduce memory use and improve performance, defaults to 4 which means a 1:16 ratio.
  • aggregator: a function that aggregates cells, defualting to mean.
  • human_exponent: human population exponent.
  • dist_exponent: distance exponent.
  • dispersalperpop: sets the number of dispersing individuals from the origin as a proportion of the level of human activity.
  • max_dispersers: maximum number of dispersers in a single dispersal event.
  • nshortlisted: length of the dispersal destination shortlist for each cell. Longer lists are more accurate in the tail of the distribution, but are slower to access.

Pass grid Symbols to R or both R and W type parameters to use to specific grids.

source
Dispersal.populate!Function
populate!(A::AbstractMatrix, rule::HumanDispersal, [I...])
populate!(A::AbstractMatrix, cells::AbstractArray, [scale=1])

Populate a matrix with the precalculated destinations from a HumanDispersal rule - either all of the or some subset if passed the I... indexing arguments. This is useful for plotting dispersal destinations, especially when used with GeoData.jl

source
Dispersal.populateFunction
populate(rule::HumanDispersal, [I...])

Returns an array the size of human population matrix filled with all destination locataion, or with destinations specific to the passed-in indices I.

source
populate(cells::AbstractVector, size::Tuple, [scale::Int=1])

Returns an array of size size populated from the vector of positions in cells rescaled by scale.

source