NeutralLandscapes.jl
A pure Julia port of https://github.com/tretherington/nlmpy
Landscape models
NeutralLandscapes.NeutralLandscapeMaker Type
NeutralLandscapeMakerAbstract supertype that all algorithms are descended from. A new algorithm must minimally implement a _landscape! method for this type.
NeutralLandscapes.DiamondSquare Type
DiamondSquare <: NeutralLandscapeMaker
DiamondSquare(; H = 0.5)
DiamondSquare(H)This type generates a neutral landscape using the diamond-squares algorithm, which produces fractals with variable spatial autocorrelation.
https://en.wikipedia.org/wiki/Diamond-square_algorithm
The algorithm is named diamond-square because it is an iterative procedure of "diamond" and "square" steps.
The degree of spatial autocorrelation is controlled by a parameter H, which varies from 0.0 (low autocorrelation) to 1.0 (high autocorrelation) –- note this is non-inclusive and H = 0 and H = 1 will not behave as expected. The result of the diamond-square algorithm is a fractal with dimension D = 2 + H.
A similar algorithm, midpoint-displacement, functions almost identically, except that in DiamondSquare, the square step interpolates edge midpoints from the nearest two corners and the square's center, where as midpoint-displacement only interpolates from the nearest corners (see MidpointDisplacement).
NeutralLandscapes.DiscreteVoronoi Type
DiscreteVoronoi <: NeutralLandscapeMaker
DiscreteVoronoi(; n=3)
DiscreteVoronoi(n)This type provides a rasterization of a Voronoi-like diagram. Assigns a value to each patch using a 1-NN algorithmm with n initial clusters. It is a NearestNeighborElement algorithmm with k neighbors set to 1. The default is to use three clusters.
NeutralLandscapes.DistanceGradient Type
DistanceGradient <: NeutralLandscapeMaker
DistanceGradient(; sources=[1])
DistanceGradient(sources)The sources field is a Vector{Integer} of linear indices of the matrix, from which the distance must be calculated.
NeutralLandscapes.EdgeGradient Type
EdgeGradient <: NeutralLandscapeMaker
EdgeGradient(; direction=360rand())
EdgeGradient(direction)This type is used to generate an edge gradient landscape, where values change as a bilinear function of the x and y coordinates. The direction is expressed as a floating point value, which will be in [0,360]. The inner constructor takes the mod of the value passed and 360, so that a value that is out of the correct interval will be corrected.
NeutralLandscapes.MidpointDisplacement Type
MidpointDisplacement <: NeutralLandscapeMaker
MidpointDisplacement(; H = 0.5)Creates a midpoint-displacement algorithm object MidpointDisplacement. The degree of spatial autocorrelation is controlled by a parameter H, which varies from 0.0 (low autocorrelation) to 1.0 (high autocorrelation) –- note this is non-inclusive and H = 0 and H = 1 will not behave as expected.
A similar algorithm, diamond-square, functions almost identically, except that in diamond-square, the square step interpolates edge midpoints from the nearest two corners and the square's center, where as MidpointDisplacement only interpolates from the nearest corners (see DiamondSquare).
NeutralLandscapes.NearestNeighborCluster Type
NearestNeighborCluster <: NeutralLandscapeMaker
NearestNeighborCluster(; p=0.5, n=:rook)
NearestNeighborCluster(p, [n=:rook])Create a random cluster nearest-neighbour neutral landscape model with values ranging 0-1. p sets the density of original clusters, and n sets the neighborhood for clustering (see ?label for neighborhood options)
NeutralLandscapes.NearestNeighborElement Type
NearestNeighborElement <: NeutralLandscapeMaker
NearestNeighborElement(; n=3, k=1)
NearestNeighborElement(n, [k=1])Assigns a value to each patch using a k-NN algorithmm with n initial clusters and k neighbors. The default is to use three cluster and a single neighbor.
NeutralLandscapes.NoGradient Type
NoGradient <: NeutralLandscapeMaker
NoGradient()This type is used to generate a random landscape with no gradients
NeutralLandscapes.PerlinNoise Type
PerlinNoise <: NeutralLandscapeMaker
PerlinNoise(; kw...)
PerlinNoise(periods, [octaves=1, lacunarity=2, persistance=0.5, valley=:u])Create a Perlin noise neutral landscape model with values ranging 0-1.
Keywords
periods::Tuple{Int,Int}=(1,1): the number of periods of Perlin noise across row and column dimensions for the first octave.octaves::Int=1: the number of octaves that will form the Perlin noise.lacunarity::Int=2: the rate at which the frequency of periods increases for each octive.persistance::Float64=0.5: the rate at which the amplitude of periods decreases for each octive.valley::Symbol=:u: the kind of valley bottom that will be mimicked::uproduces u-shaped valleys,:vproduces v-shaped valleys, and:-` produces flat bottomed valleys.
Note: This is a memory-intensive algorithm with some settings. Be careful using larger prime numbers for period when also using a large array size, high lacuarity and/or many octaves. Memory use scales with the lowest common multiple of periods.
NeutralLandscapes.PlanarGradient Type
PlanarGradient <: NeutralLandscapeMaker
PlanarGradient(; direction=360rand())
PlanarGradient(direction)This type is used to generate a planar gradient landscape, where values change as a bilinear function of the x and y coordinates. The direction is expressed as a floating point value, which will be in [0,360]. The inner constructor takes the mod of the value passed and 360, so that a value that is out of the correct interval will be corrected.
NeutralLandscapes.RectangularCluster Type
RectangularCluster <: NeutralLandscapeMaker
RectangularCluster(; minimum=2, maximum=4)
RectangularCluster(minimum, [maximum=4])Fills the landscape with rectangles containing a random value. The size of each rectangle/patch is between minimum and maximum (the two can be equal for a fixed size rectangle).
NeutralLandscapes.WaveSurface Type
WaveSurface <: NeutralLandscapeMaker
WaveSurface(; direction=360rand(), periods=1)
WaveSurface(direction, [periods=1])Creates a sinusoidal landscape with a direction and a number of periods. If neither are specified, there will be a single period of random direction.
Landscape generating function
Base.rand Function
rand(alg, dims::Tuple{Vararg{Int64,2}}; mask=nothing) where {T <: Integer}Creates a landscape of size dims (a tuple of two integers) following the model defined by alg. The mask argument accepts a matrix of boolean values, and is passed to mask! if it is not nothing.
Random.rand! Function
rand!(mat, alg) where {IT <: Integer}Fill the matrix mat with a landscape created following the model defined by alg. The mask argument accepts a matrix of boolean values, and is passed to mask! if it is not nothing.
Temporal Change
NeutralLandscapes.NeutralLandscapeUpdater Type
NeutralLandscapeUpdaterNeutralLandscapeUpdater is an abstract type for methods for updating a landscape matrix
NeutralLandscapes.TemporallyVariableUpdater Type
TemporallyVariableUpdater{D,S} <: NeutralLandscapeUpdaterA NeutralLandscapeUpdater that has a prescribed level of temporal variation (variability) and rate of change (rate), but no spatial correlation in where change is distributed.
NeutralLandscapes.SpatiallyAutocorrelatedUpdater Type
SpatiallyAutocorrelatedUpdater{SU,R,V}A NeutralLandscapeUpdater that has a prescribed level of spatial variation (variability) and rate of change (rate), and where the spatial distribution of this change is proportional to a neutral landscape generated with spatialupdater at every time step.
TODO: make it possible to fix a given spatial updater at each timestep.
NeutralLandscapes.SpatiotemporallyAutocorrelatedUpdater Type
SpatiotemporallyAutocorrelatedUpdater{SU,R,V}A NeutralLandscapeUpdater that has a prescribed level of spatial and temporal variation (variability) and rate of change (rate), and where the spatial distribution of this change is proportional to a neutral landscape generated with spatialupdater at every time step.
TODO: perhaps spatial and temporal should each have their own variability param
NeutralLandscapes.update Function
update(updater::T, mat)Returns one-timestep applied to mat based on the NeutralLandscapeUpdater provided (updater).
update(updater::T, mat, n::I)Returns a sequence of length n where the original neutral landscape mat is updated by the NeutralLandscapeUpdater update for n timesteps.
NeutralLandscapes.update! Function
update!(updater::T, mat)Updates a landscape mat in-place by directly mutating mat.
NeutralLandscapes.normalize Function
normalize(mats::Vector{M})Normalizes a vector of neutral landscapes mats such that all values between 0 and 1. Note that this does not preserve the rate parameter for a given NeutralLandscapeUpdater, and instead rescales it proportional to the difference between the total maximum and total minimum across all mats.
NeutralLandscapes.rate Function
spatialupdater(up::NeutralLandscapeUpdater)All NeutralLandscapeUpdaters have a field rate which defines the expected (or mean) change across all cells per timestep.
NeutralLandscapes.variability Function
variability(up::NeutralLandscapeUpdater)Returns the variability of a given NeutralLandscapeUpdater. The variability of an updater is how much temporal variation there will be in a generated time-series of landscapes.
NeutralLandscapes.spatialupdater Function
spatialupdater(up::NeutralLandscapeUpdater)All NeutralLandscapeUpdater's have a spatialupdater field which is either a NeutralLandscapeMaker, or Missing (in the case of temporally correlated updaters).
NeutralLandscapes._update Function
_update(tvu::TemporallyVariableUpdater, mat)Updates mat using temporally autocorrelated change, using the direction and rate parameters from tvu.
TODO: this doesn't have to be a Normal distribution, could be arbitrary distribution that is continuous and can have mean 0 (or that can be transformed to have mean 0)
_update(sau::SpatiallyAutocorrelatedUpdater, mat; transform=ZScoreTransform)Updates mat using spatially autocorrelated change, using the direction, rate, and spatial updater parameters from sau.
TODO: doesn't necessarily have to be a ZScoreTransform, could be arbitrary argument
_update(stau::SpatiotemporallyAutocorrelatedUpdater, mat)Updates mat using temporally autocorrelated change, using the direction, rate, and spatialupdater parameters from stau.
TODO: doesn't necessarily have to be a Normal distribution or ZScoreTransform, could be arbitrary argument
Other functions
NeutralLandscapes.classify Function
classify(array, weights[, mask])Classify an array into proportions based upon a list of class weights.
NeutralLandscapes.classify! Function
classify!(array, weights[, mask])Classify an array in-place into proportions based upon a list of class weights.
NeutralLandscapes.blend Function
blend(arrays[, scaling])Blend arrays weighted by scaling factors.
blend(clusterarray, arrays[, scaling])Blend a primary cluster NLM with other arrays in which the mean value per cluster is weighted by scaling factors.
NeutralLandscapes.label Function
label(mat[, neighborhood = :rook])Assign an arbitrary label to all clusters of contiguous matrix elements with the same value. Returns a matrix of values and the total number of final clusters. The neighborhood structure can be :rook :queen :diagonal 0 1 0 1 1 1 0 1 1 1 x 1 1 x 1 1 x 1 0 1 0 1 1 1 1 1 0 :rook is the default
NeutralLandscapes.mask! Function
mask!(array::AbstractArray{<:AbstractFloat}, maskarray::AbstractArray{<:AbstractBool})Modifies array so that the positions at which maskarray is false are replaced by NaN.