NeutralLandscapes.jl

NeutralLandscapeMaker

Abstract supertype that all algorithms are descended from. A new algorithm must minimally implement a _landscape! method for this 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).

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.

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.

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.

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

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)

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.

NoGradient <: NeutralLandscapeMaker

NoGradient()

This type is used to generate a random landscape with no gradients

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.

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.

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

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.

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.

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.

NeutralLandscapeUpdater

NeutralLandscapeUpdater is an abstract type for methods for updating a landscape matrix

TemporallyVariableUpdater{D,S} <: NeutralLandscapeUpdater

A NeutralLandscapeUpdater that has a prescribed level of temporal variation (variability) and rate of change (rate), but no spatial correlation in where change is distributed.

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.

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

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.

update!(updater::T, mat)

Updates a landscape mat in-place by directly mutating mat.

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.

spatialupdater(up::NeutralLandscapeUpdater)

All NeutralLandscapeUpdaters have a field rate which defines the expected (or mean) change across all cells per timestep.

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.

spatialupdater(up::NeutralLandscapeUpdater)

All NeutralLandscapeUpdater's have a spatialupdater field which is either a NeutralLandscapeMaker, or Missing (in the case of temporally correlated updaters).

_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

classify(array, weights[, mask])

Classify an array into proportions based upon a list of class weights.

classify!(array, weights[, mask])

Classify an array in-place into proportions based upon a list of class weights.

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.

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

mask!(array::AbstractArray{<:AbstractFloat}, maskarray::AbstractArray{<:AbstractBool})

Modifies array so that the positions at which maskarray is false are replaced by NaN.