API

AbstractAbiotic{H <: AbstractHabitat, B <: AbstractBudget} <: AbstractPartition

Abstract supertype for all abiotic environment types and a subtype of AbstractPartition

AbstractBudget

Abstract supertype for all budget types

AbstractEcosystem{Part <: AbstractAbiotic, SL <: SpeciesList,
    TR <: AbstractTraitRelationship} <: AbstractMetacommunity{Float64,
        Matrix{Int64}, Matrix{Float64}, SL, Part}

Abstract supertype for all ecosystem types and a subtype of AbstractMetacommunity.

AbstractHabitat

Abstract supertype for all habitat types

AbstractMovement

Abstract supertype of movements

AbstractParams

Abstract supertype for all simulation parameter types

Abstract1Requirement{Energy}

Abstract supertype for all species energy requirement types, parameterised by the type(s) of energy required Energy.

AbstractScenario

Abstract supertype for all whole ecosystem change scenarios

AbstractTraitRelationship{TR}

The abstract supertype of relationships between a trait and its environment, parameterised on any TR.

AbstractTraits{T}

Abstract supertype for all trait types, parameterised by traits of any type T.

AlwaysMovement{K <: AbstractKernel, B <: BoundaryCondition} <: AbstractMovement

Movement can happen to any individual ("animal-like").

AlwaysMovement{K <: AbstractKernel, B <: BoundaryCondition} <: AbstractMovement

Movement can happen to any individual ("animal-like").

BirthOnlyMovement{K <: AbstractKernel, B <: BoundaryCondition} <: AbstractMovement

Movement can only happen to individuals that have just been born ("plant-like").

BirthOnlyMovement{K <: AbstractKernel, B <: BoundaryCondition} <: AbstractMovement

Movement can only happen to individuals that have just been born ("plant-like").

BoundaryCondition

An abstract type for what should happen at the boundaries of an ecosystem.

Cache

Cache houses an integer array of moves made by all species in a timestep for the update! function, netmigration.

CachedEcosystem{Part <: AbstractAbiotic, SL <: SpeciesList,
    TR <: AbstractTraitRelationship} <: AbstractEcosystem{Part, SL, TR}

CachedEcosystem houses the same information as Ecosystem (see ?Ecosystem), but holds the time period abundances as a CachedGridLandscape, so that they may be present or missing.

CachedEcosystem(eco::Ecosystem, outputfile::String, times::StepRangeLen;
                saveinterval::Unitful.Time = step(times))

Create a CachedEcosystem given an existing Ecosystem, eco, an output folder to which the simulations are saved, outputfile, and a range of times over which to simulate, times. The step of times is the simulation timestep; saveinterval controls how often checkpoints are written to disk (a multiple of the timestep, defaulting to every step). Because the simulation always advances by the timestep, results are independent of saveinterval.

CachedGridLandscape

Ecosystem abundances for a cached simulation. matrix is an AxisArray over time where each slot holds either a GridLandscape or missing. outputfolder is the path to the folder where JLD2 cache files are written. timestep is the simulation step (the granularity of the time axis) and saveinterval is the (possibly coarser) interval at which checkpoints are written to disk; it must be a multiple of timestep. Because the simulation always advances by timestep, the results are independent of saveinterval.

CachedGridLandscape(file::String, times::StepRangeLen;
                    saveinterval::Unitful.Time = step(times))

Construct a CachedGridLandscape backed by the folder file, initialising all timepoints in the range times to missing. The simulation timestep is the step size of times; saveinterval sets how often checkpoints are written to disk and must be a multiple of the timestep (it defaults to saving every step).

ContinuousHab{C <: Number} <: AbstractHabitat{C}

This habitat subtype houses a habitat matrix matrix of any units, a grid square size size and HabitatUpdate type change.

ContinuousTimeHab{C <: Number, M <: AbstractArray{C, 3}} <: AbstractHabitat{C}

This habitat subtype houses a habitat matrix matrix of any units, the time slice of the habitat matrix currently being operated on time, a grid square size size and HabitatUpdate type change.

ContinuousTrait{C <: Number} <: AbstractTraits{T}

Abstract trait type that holds information on a single continuous trait for each species, of any Number type C.

Cylinder <: BoundaryCondition

A cylindrical boundary where species can cross the x boundary but not the y.

DiscreteHab{D} <: AbstractHabitat{D}

Habitat subtype with a discrete matrix of element type D, a grid cell size, and a HabitatUpdate rule change applied at each timestep.

BasicTrait{T} <: AbstractTraits{T}

Basic trait type that holds information on a single trait for each species, of any type T.

DiversitySet(cache::CachedEcosystem, times::Vector{T}) where T <: Unitful.Time

Construct a DiversitySet from a CachedEcosystem, initialising it with the cache output folder and a vector of timepoints times for which diversity is to be recorded.

Ecosystem{Part <: AbstractAbiotic} <:
   AbstractEcosystem{Part, SL, TR}

Ecosystem houses information on species and their interaction with their environment. For species, it holds abundances and locations, as well as properties such as trait information, spplist, and movement types, lookup. For environments, it provides information on environmental conditions and available resources,abenv. Finally, there is a slot for the relationship between the environment and the characteristics of the species, relationship.

```julia Ecosystem{Part <: AbstractAbiotic} <: AbstractEcosystem{Part, SL, TR} ``` Ecosystem houses information on species and their interaction with their environment. For species, it holds abundances and locations, as well as properties such as trait information, `spplist`, and movement types, `lookup`. For environments, it provides information on environmental conditions and available resources,`abenv`. Finally, there is a slot for the relationship between the environment and the characteristics of the species, `relationship`.

```julia Ecosystem(spplist::SpeciesList, abenv::GridAbioticEnv, rel::AbstractTraitRelationship) ``` Create an `Ecosystem` given a species list, an abiotic environment and trait relationship. An optional population function can be added, `popfun`, which defaults to generic random filling of the ecosystem. A `seed` may be supplied to make the run reproducible: it deterministically seeds one random number generator per species (see [`makerngs`](@ref)), so results are identical regardless of the number of threads used. If no `seed` is given, one is drawn at random.

Ecosystem(spplist::SpeciesList, abenv::GridAbioticEnv,
    rel::AbstractTraitRelationship)

Create an Ecosystem given a species list, an abiotic environment and trait relationship. An optional population function can be added, popfun, which defaults to generic random filling of the ecosystem. A seed may be supplied to make the run reproducible: it deterministically seeds one random number generator per species (see makerngs), so results are identical regardless of the number of threads used. If no seed is given, one is drawn at random.

EqualPop <: AbstractParams

Parameter type that holds information on a population's birth and death rates, birth and death, specifically populations where all species have the same information. l represents the longevity of species based on their energy requirements and s is the survival of species dependent on how well their traits reflect the environment. Finally boost is used to manipulate how much of a boost the species get from being in an environment with lots of available energy.

FluctScenario <: AbstractScenario

Scenario type that fluctuates the environment periodically. fun is the fluctuation function, rate is the rate of temperature change, and startarray holds the baseline habitat values at the start of the simulation.

Gauss{TR} <: AbstractTraitRelationship{TR}

The Gaussian relationship between a continuous trait and its environment, paramaterised on any TR.

GaussTrait{C <: Number} <: ContinuousTrait{C}

Trait type that holds Gaussian mean and variance trait information for each species, of any number type C.

GaussianKernel <: AbstractKernel

GaussianMovement holds parameters for a gaussian movement kernel; a dispersal variance for a species, var, and a threshold, thresh, beyond which dispersal cannot take place.

GridAbioticEnv{H, B} <: AbstractAbiotic{H, B}

Abiotic environment type holding a habitat of type H, a boolean active matrix indicating which grid cells are accessible, a budget of type B representing available resources, and a vector of names for each subcommunity.

GridLandscape

Ecosystem abundances housed in the landscape. matrix stores abundances as a 2-dimensional array (species × grid cells) for computational efficiency, and grid is a 3-dimensional view of the same data (species × x × y). Random draws during simulation use Julia's task-local default RNG, so no generator state is stored here.

GridLandscape(sl::SavedLandscape, dimension::Tuple)

Restore a GridLandscape from a SavedLandscape, reshaping the abundance matrix to dimension. The saved RNG snapshot is restored separately at the load site (see loadfile).

HabitatCollection2{H1, H2} <: AbstractHabitat{Tuple{H1, H2}}

Composite habitat pairing two sub-habitats h1 and h2, allowing multi-variable abiotic environments (e.g. temperature and rainfall together).

HabitatCollection3{H1, H2, H3} <: AbstractHabitat{Tuple{H1, H2, H3}}

Composite habitat combining three sub-habitats h1, h2, and h3.

HabitatUpdate{F <: Function, DT}

Stores the update rule for a habitat. changefun is the function applied to the habitat matrix at each timestep, and rate is the rate of change with appropriate units.

HabitatUpdate(changefun::F, rate::DT, ::Type{D})

Construct a HabitatUpdate with a type-checked rate. Errors if rate * 1month does not have dimensions D.

LongTailKernel <: AbstractKernel

LongTailKernel holds parameters for a movement kernel; a dispersal variance for a species, var, and a threshold, thresh, beyond which dispersal cannot take place.

Lookup

Lookup houses information on x, y grid locations and the probability of occurrence at the location for the species in question p. pnew and moves are initially empty storage and written over by the movement step in update!(). pnew is the recalculated probability based on which directions are available and moves is the number of moves to that grid location in that step.

Match{TR} <: AbstractTraitRelationship{TR}

The relationship between a discrete trait and its environment, paramaterised on any TR. Current conditions are matched to a trait preference and checked for a match.

MultiScenario{S1 <: AbstractScenario, S2 <: AbstractScenario} <: AbstractScenario

Scenario type that composes two scenarios, applying sc1 and then sc2 in sequence at each timestep.

NoBoundary <: BoundaryCondition

A hard boundary where no species can cross.

NoMovement{K <: AbstractKernel, B <: BoundaryCondition} <: AbstractMovement

No movement can take place.

NoRelContinuous{TR} <: AbstractTraitRelationship{TR}

The absense of a relationship between a continuous trait and its environment, paramaterised on any TR. Returns the value 1.

NoRelDiscrete{TR} <: AbstractTraitRelationship{TR}

The absense of a relationship between a discrete trait and its environment, paramaterised on any TR. Returns the value 1.

PopGrowth <: AbstractParams

Basic parameter type that holds information on a population's birth and death rates, birth and death, as well as how these are altered by energy availability. l represents the longevity of species based on their energy requirements and s is the survival of species dependent on how well their traits reflect the environment.

RainBin{C <: Int} <: ContinuousTrait{C}

Trait type that holds binned rainfall preference information created through ClimatePref. Holds an array of counts per rainfall band (mm).

SavedLandscape(gl::GridLandscape, rngs::Vector{Random.Xoshiro})

Convert a GridLandscape to a SavedLandscape for serialisation, preserving the abundance matrix and a snapshot of the per-species RNG streams rngs so a cached run can be resumed with a reproducible random stream.

SimpleBudget <: AbstractBudget{Float64}

This budget type has a matrix of floats, representing the energy budget of each subcommunity in the abiotic environment.

SimpleRequirement <: Abstract1Requirement{Float64}

A simple energy requirement is a single float for each species.

SimpleScenario <: AbstractScenario

Scenario type that applies a uniform rate of change across the entire ecosystem at each timestep. fun is the change function called as fun(eco, timestep, rate), and rate is the magnitude of change per unit time.

SizeRequirement <: Abstract1Requirement{Float64}

A simple energy requirement is a single float for each species.

SolarBudget <: AbstractBudget{typeof(1.0*kJ)}

This budget type has a matrix of solar energy units, representing the energy budget of each subcommunity in the abiotic environment at a fixed point in time.

SolarRequirement <: Abstract1Requirement{typeof(1.0*kJ)}

A vector of solar energy requirements (kJ) for each species.

SolarTimeBudget <: AbstractBudget{typeof(1.0*kJ)}

This budget type has a matrix of solar energy units, representing the energy budget of each subcommunity in the abiotic environment along with which time dimension we are interested in.

SpeciesList{TR <: AbstractTraits, R <: AbstractRequirement,
            MO <: AbstractMovement, T <: AbstractTypes,
            P <: AbstractParams} <: AbstractTypes

Species list housing all species-specific information. names holds species names, traits encodes niche preferences, abun holds current abundances, requirement encodes energy needs, types holds the similarity structure, movement describes dispersal, params holds demographic parameters, native flags whether each species is native, and susceptible holds optional disease susceptibility values.

SpeciesList(numspecies::Int64, numtraits::Int64, pop_mass::Float64,
  mean::Float64, var::Float64, area::Unitful.Area, movement::MO,
  params::P, native::Vector{Bool}, switch::Vector{Float64})

Create a SpeciesList where body size is evolved as a continuous trait along the phylogeny via Brownian motion with mean mean and variance var. Abundances and energy requirements are derived from body size and population mass pop_mass scaled to area. Trait switching rates along the tree are controlled by switch.

SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64},
  req::R, movement::MO, params::P, native::Vector{Bool},
  switch::Vector{Float64})

Create a SpeciesList for numspecies species with numtraits discrete niche traits evolved along a random ultrametric phylogeny. switch controls the rate of trait change along branches. A PhyloBranches similarity structure is computed from the tree. Abundances are provided via abun and energy requirements via req.

```julia SpeciesList{TR <: AbstractTraits, R <: AbstractRequirement, MO <: AbstractMovement, T <: AbstractTypes, P <: AbstractParams} <: AbstractTypes ``` Species list housing all species-specific information. `names` holds species names, `traits` encodes niche preferences, `abun` holds current abundances, `requirement` encodes energy needs, `types` holds the similarity structure, `movement` describes dispersal, `params` holds demographic parameters, `native` flags whether each species is native, and `susceptible` holds optional disease susceptibility values.

```julia SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64}, req::R, movement::MO, params::P, native::Vector{Bool}, switch::Vector{Float64}) ``` Create a `SpeciesList` for `numspecies` species with `numtraits` discrete niche traits evolved along a random ultrametric phylogeny. `switch` controls the rate of trait change along branches. A `PhyloBranches` similarity structure is computed from the tree. Abundances are provided via `abun` and energy requirements via `req`.

SpeciesList(numspecies::Int64, traits::TR, abun::Vector{Int64}, req::R,
  movement::MO, params::P, native::Vector{Bool})

Create a SpeciesList from an explicitly supplied trait object traits of type AbstractTraits. Uses UniqueTypes as the similarity structure, treating all species as maximally distinct.

SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64},
  req::R, movement::MO, phy::T, params::P, native::Vector{Bool})

Create a SpeciesList with an explicitly supplied similarity structure phy of type AbstractTypes, rather than computing a PhyloBranches similarity internally. Discrete traits are still evolved along a random ultrametric tree.

TempBin{C <: Int} <: ContinuousTrait{C}

Trait type that holds binned temperature preference information created through ClimatePref. Holds an array of counts per temperature band (°C).

Torus <: BoundaryCondition

A toroidal boundary where species can cross both boundaries.

TraitCollection2{T1, T2} <: AbstractTraits{Tuple{T1, T2}}

Trait collection that holds two trait types, TR1 and TR2.

TraitCollection3{T1, T2, T3} <: AbstractTraits{Tuple{T1, T2, T3}}

Trait collection that holds three trait types, TR1, TR2 and TR3.

Trapeze{TR} <: AbstractTraitRelationship{TR}

The relationship between a continuous trait and its environment, paramaterised on any TR.

Trapezoid{T<:Real} <: ContinuousUnivariateDistribution

Trapezoidal distribution as described at https://en.wikipedia.org/wiki/Trapezoidal_distribution.

Trapeze{TR} <: AbstractTraitRelationship{TR}

The relationship between a continuous trait and its environment, paramaterised on any TR.

VolWaterBudget <: AbstractBudget{typeof(1.0*mm)}

This budget type has a matrix of water volumes, representing the energy budget of each subcommunity in the abiotic environment at a fixed point in time.

VolWaterRequirement <: Abstract1Requirement{typeof(1.0*mm)}

A vector of soil water volume requirements (m^3) for each species.

VolWaterTimeBudget <: AbstractBudget{typeof(1.0*mm)}

This budget type has a matrix of volumetric soil water units, representing the water budget of each subcommunity in the abiotic environment along with which time dimension we are interested in.

WaterBudget <: AbstractBudget{typeof(1.0*mm)}

This budget type has a matrix of rainfall energy units, representing the energy budget of each subcommunity in the abiotic environment at a fixed point in time.

WaterRequirement <: Abstract1Requirement{typeof(1.0*mm)}

A vector of water requirements (mm) for each species.

WaterTimeBudget <: AbstractBudget{typeof(1.0*mm)}

This budget type has a matrix of rainfall units, representing the water budget of each subcommunity in the abiotic environment along with which time dimension we are interested in.

additiveTR2{TR1, TR2} <: AbstractTraitRelationship{Tuple{TR1, TR2}}

Type that houses multiple AbstractTraitRelationships for two trait and habitat levels.

multiplicativeTR3{TR1, TR2, TR3} <: AbstractTraitRelationship{Tuple{TR1, TR2, TR3}}

Type that houses multiple AbstractTraitRelationships for three trait and habitat levels.

multiplicativeTR2{TR1, TR2} <: AbstractTraitRelationship{Tuple{TR1, TR2}}

Type that houses multiple AbstractTraitRelationships for two trait and habitat levels.

multiplicativeTR3{TR1, TR2, TR3} <: AbstractTraitRelationship{Tuple{TR1, TR2, TR3}}

Type that houses multiple AbstractTraitRelationships for three trait and habitat levels.

append!(div::DiversitySet, dat::DataFrame)

Append a DataFrame of diversity results dat to the data stored in a DiversitySet.

BM(T::Real, σ²::Float64, start::Float64, lab::String="")

Evolve a Real value through Brownian motion, with a starting value, start, and rate, σ².

ContinuousEvolve(val::Union{Float64, Unitful.Quantity{Float64}}, var::Union{Float64, Unitful.Quantity{Float64}}, tree::BinaryTree)

Evolve a continuous trait along a BinaryTree, tree via Brownian motion. Takes in a starting value, val and a variance, var.

DiscreteEvolve(numTraits::Int64, tree::BinaryTree)

Evolve a discrete switching trait along a BinaryTree, tree. Takes in a number of traits, numTraits to be switched between and rate to switch between traits, switch_rate with default value of 0.5.

HabitatLoss(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Destroy habitat for one timestep of the ecosystem using HabitatUpdate information.

NoChange(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Keep the habitat the same for one timestep of the model.

RainfallChange(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Change the rainfall for one timestep of the ecosystem using HabitatUpdate information.

TempChange(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Increase the temperature for one timestep of the ecosystem using HabitatUpdate information.

TempFluct(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Fluctuate the temperature for one timestep of the ecosystem using HabitatUpdate information.

abundances(cache::CachedEcosystem, tm::Unitful.Time)

Extract abundances for an ecosystem, cache, at a certain point in time, tm. If the abundances for that time are missing from the ecosystem, then the function checks on disk for the last saved version and simulates forward.

addspecies!(eco::Ecosystem, abun::Int64)

Add a new species to an existing Ecosystem with initial abundance abun, copying trait, movement, parameter, requirement, and type information from the last existing species.

arenoderecordsempty(tree::AbstractTree, nodes::Vector{String})

Check whether the node data records are empty for each node in nodes. Returns a vector of Bool values, one per node.

assign_traits!(tree::AbstractTree, start::Vector{Float64},
  σ²::Vector{Float64})

Evolve continuous functional traits through a phylogenetic tree through Brownian motion, with a starting value, start, and rate, σ².

assign_traits!(tree::AbstractTree, switch_rate::Vector{Float64},
traits::Vector{Vector{String}})

Evolve categorical functional traits through a phylogenetic tree with a specific switching rate.

bioclimAE(bc::ClimateRaster{WorldClim{BioClim}}, maxbud::Unitful.Quantity{Float64},
  area::Unitful.Area{Float64}, active::Matrix{Bool})

As bioclimAE with an explicit active matrix of grid squares, rather than inferring active cells from NaN values in the bioclim data.

bioclimAE(bc::ClimateRaster{WorldClim{BioClim}}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64})

Create a ContinuousHab, SimpleBudget type abiotic environment from a Worldclim type climate. It either creates a SimpleBudget type filled with the maximum budget value maxbud or uses a provided budget of type SolarBudget. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

bioclimAE(bc::ClimateRaster{WorldClim{BioClim}}, bud::B, active::Matrix{Bool}) where B <: AbstractBudget

As bioclimAE but accepts a pre-constructed AbstractBudget object bud rather than computing a budget from a maximum value.

budgetupdate!(eco::AbstractEcosystem, timestep::Unitful.Time)

Update the budget of an ecosystem for one timestep.

calc_lookup_moves!(bound, x::Int64, y::Int64, sp::Int64, eco::Ecosystem, abun::Int64)

Calculate the number of moves taken by a species, sp, from a specific grid square location (x, y). There is a boundary condition, bound, which determines how the species can move across space (see AbstractBoundary). The total abundance of individuals is given in abun, which may be the number of births in the timestep, or total individuals.

checkfile(file::String, idx::Int)

Check whether a JLD2 checkpoint file exists in the folder file for checkpoint index idx. Returns true if <idx>.jld2 is present.

checkfile(::String, ::Missing)

Check whether a cache file exists for a given timepoint. Always returns false when the timepoint is missing.

clearcache(cache::CachedEcosystem)

Delete all JLD2 cache files from the output folder of a CachedEcosystem. Returns a string reporting how many files were removed.

combineTR

Function that combines the output of multiple trait relationships, which varies depending on whether multiplicative, additive etc.

convert_coords(eco, i::Int64, width::Int64)
convert_coords(eco, x::Int64, y::Int64, width::Int64)

Convert coordinates from two-dimensional (x,y) format to one dimension (i), or vice versa, using the width of the grid. This function can also be applied to arrays of coordinates.

emptygridlandscape(gae::GridAbioticEnv, spplist::SpeciesList)

Create an empty GridLandscape given a GridAbioticEnv and a SpeciesList.

emptypopulate!(ml::GridLandscape, spplist::SpeciesList, abenv::AB, rel::R,
               rngs::Vector{Random.Xoshiro}) where {AB <: EcoSISTEM.AbstractAbiotic, R <: EcoSISTEM.AbstractTraitRelationship}

Placeholder population function that leaves the landscape empty and warns.

energy_adjustment(eco::Ecosystem, bud::AbstractBudget, i::Int64, sp::Int64)

Calculate how much birth and death rates should be adjusted by, according to how much energy is available, bud, in the grid square, i, and how much energy the species, sp, requires.

equalpop(params::EqualPop, numspp)

Function that takes demographic parameters from type EqualPop and converts them into type PopGrowth based on the number of species (numspp).

eraAE(era::ERA, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64},
  active::Matrix{Bool})

As eraAE with an explicit active matrix of grid squares, rather than inferring active cells from NaN values in the ERA data.

eraAE(era::ERA, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64})

Create a ContinuousHab, SimpleBudget type abiotic environment from an ERA type climate. It either creates a SimpleBudget type filled with the maximum budget value maxbud or uses a provided budget of type SolarTimeBudget. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

eraAE(era::ERA, bud::B, active::Matrix{Bool}) where B <: AbstractTimeBudget

As eraAE but accepts a pre-constructed AbstractTimeBudget object bud rather than computing a budget from a maximum value.

eraChange(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Step the ERA climate forward by one timestep.

generate_storage(eco::Ecosystem, qs::Int64, times::Int64, reps::Int64)

Allocate a float array of shape (gridSize, qs, times, reps) for recording diversity values across the ecosystem eco for qs diversity orders over multiple timesteps and replicate runs.

generate_storage(eco::Ecosystem, times::Int64, reps::Int64)

Allocate an integer array of shape (numSpecies, gridSize, times, reps) for recording species abundances across the ecosystem eco over multiple timesteps and replicate runs.

genlookups(hab::AbstractHabitat, mov::GaussianMovement)

Generate lookup tables, which hold information on the probability of moving to neighbouring squares.

geom_mean_abun(eco::Ecosystem, qs::Vector{Float64})

Calculate the geometric mean abundance for the entire ecosystem.

get_neighbours(mat::Matrix, x_coord::Vector{Int64}, y_coord::Vector{Int64},
    chess::Int64=4)

As get_neighbours but accepts vectors of coordinates and returns the combined neighbours for all positions.

get_neighbours(mat::Matrix, x_coord::Int64, y_coord::Int64, chess::Int64=4)

Get the neighbours of a grid square in a matrix in 4 or 8 directions

get_traits(tree::AbstractTree, tips::Bool=true)

Retrieve functional traits assigned to a phylogenetic tree, either just tips or all nodes.

getavailableenergy(gae::GridAbioticEnv)

Return the available energy budget from a GridAbioticEnv.

getboundary(m::AbstractMovement)

Extract the boundary condition from a movement type.

getbudget(eco::Ecosystem)

Extract budget from Ecosystem object.

getdimension(eco::Ecosystem)

Extract dimension of habitat from Ecosystem object.

getdispersaldist(eco::Ecosystem)

Extract average dispersal distance of species from Ecosystem object. Returns a vector of distances, unless a specific species is provided as a String or Integer.

getdispersaldist(eco::Ecosystem)

Extract average dispersal distance of species from Ecosystem object. Returns a vector of distances, unless a specific species is provided as a String or Integer.

getdispersalvar(eco::Ecosystem)

Extract dispersal varaince of species from Ecosystem object. Returns a vector of distances, unless a specific species is provided as a String or Integer.

getdispersalvar(eco::Ecosystem)

Extract dispersal varaince of species from Ecosystem object. Returns a vector of distances, unless a specific species is provided as a String or Integer.

getenergyusage(sppl::SpeciesList)

Return the total energy usage for the species list sppl, combining abundances with per-species energy requirements.

getgridsize(eco::Ecosystem)

Extract grid cell size of habitat from Ecosystem object.

gethabitat(hab::ContinuousTimeHab, pos::Int64)

Return the habitat value at position pos for the current time slice of a ContinuousTimeHab.

gethabitat(eco::Ecosystem)

Extract habitat from Ecosystem object.

gethabitat(hab::H, pos::Int64) where H <: AbstractHabitat

Return the habitat value at 1D grid position pos, converting to 2D coordinates internally.

gethabitat(hab::H, pos::Int64) where H <: AbstractHabitat

Return the habitat value at 1D grid position pos, converting to 2D coordinates internally.

getkernels(m::AbstractMovement)

Extract the vector of dispersal kernels from a movement type.

getlookup(eco::Ecosystem)

Extract movement lookup table of species from Ecosystem object.

getlookup(eco::Ecosystem)

Extract movement lookup table of species from Ecosystem object.

getpref(traits::DiscreteTrait, sp::Int64)

Extract the discrete niche preference value for species sp from a DiscreteTrait.

getpref(traits::GaussTrait, sp::Int64)

Extract the Gaussian habitat preference mean and variance for species sp from a GaussTrait. Returns a tuple (mean, var).

getpref(traits::LCtrait, spp::Int64)

Extract the land cover preference values for species spp from an LCtrait.

getpref(traits::RainBin, sp::Int64)

Extract the uniform distribution parameters (a, b) for species sp from a RainBin trait.

getpref(traits::TempBin, sp::Int64)

Extract the trapezoid distribution parameters (a, b, c, d) for species sp from a TempBin trait.

getpref(traits::T, field::Symbol) where T <: AbstractTraits

Extract trait preferences for all species in the ecosystem.

getrelationship(rel::R, field::Symbol) where R <: AbstractTraitRelationship

Extract the trait relationship of all species in the ecosystem.

getrng(eco::AbstractEcosystem, sp::Int64)

Return the per-species random number generator for global species index sp. Because each species has its own stream and is processed by exactly one task per timestep, random draws are both thread-safe and reproducible independent of the number of threads or MPI processes (see makerngs).

getsize(eco::Ecosystem)

Extract size of habitat from Ecosystem object.

gettimes(div::DiversitySet)

Return the timepoints in a DiversitySet for which diversity has not yet been calculated. If a previously saved Feather file of results is found, only times beyond the latest recorded time are returned.

gettraitrel(eco::Ecosystem)

Extract trait relationships.

habitatupdate!(eco::AbstractEcosystem, timestep::Unitful.Time)

Update the habitat of an ecosystem for one timestep.

lcAE(lc::ClimateRaster{<:EarthEnv{<:LandCover}}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area,
  active::Matrix{Bool})

As lcAE with an explicit active matrix of grid squares, rather than setting all cells active.

lcAE(lc::ClimateRaster{<:EarthEnv{<:LandCover}}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area)

Create a DiscreteHab, SimpleBudget type abiotic environment from a land cover ClimateRaster dataset. It creates a DiscreteHab habitat from the land cover array and a SimpleBudget type filled with the maximum budget value maxbud, scaled to the given area. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

lcAE(lc::ClimateRaster{<:EarthEnv{<:LandCover}}, bud::B, active::Matrix{Bool}) where B <: AbstractBudget

As lcAE but accepts a pre-constructed AbstractBudget object bud rather than computing a budget from a maximum value.

loadfile(cache::CachedEcosystem, file::String, idx::Int, dim::Tuple)

Load a cached GridLandscape from the folder file for checkpoint index idx, reshaping the abundance matrix to dimensions dim. The saved per-species RNG streams are restored into cache.rngs so the resumed run continues a reproducible random stream.

makerngs(seed::Integer, n::Integer)

Build a vector of n independent, deterministically-seeded random number generators, one per species. Species j is seeded as Xoshiro(hash((seed, j))) so its random stream is a pure function of (seed, j) — independent of how species are distributed across threads or MPI processes. This is what makes simulation results reproducible across different thread and process counts (each species is always processed by exactly one task on one rank, drawing in a fixed cell order). See getrng.

Note: this per-species scheme is sufficient only because no single species' draws are ever split across ranks/tasks. If a species' cells were ever partitioned across ranks, a per-(species, cell) counter-based generator would be needed instead.

makeunique(eco::Ecosystem)

Convert type of similarity in SpeciesList to UniqueTypes, i.e. an identity matrix.

mean_abun(eco::Ecosystem, qs::Vector{Float64})

Calculate the mean arithmetic abundance for the entire ecosystem.

meta_shannon(eco::Ecosystem, qs::Vector{Float64})

Calculate the Shannon entropy for the entire ecosystem.

meta_simpson(eco::Ecosystem, qs::Vector{Float64})

Calculate the Simpson diversity for the entire ecosystem.

meta_speciesrichness(eco::Ecosystem, qs::Vector{Float64})

Calculate the species richness for the entire ecosystem.

move!(eco::Ecosystem, ::AbstractMovement, i::Int64, sp::Int64, grd::Matrix{Int64}, abun::Int64)

Calculate the movement of species sp from a given position in the landscape i, using the lookup table found in the Ecosystem and updating the movement patterns on a cached grid, grd. Optionally, a number of births can be provided, so that movement only takes place as part of the birth process, instead of the entire population

pair(vec)

Split a vector into consecutive overlapping pairs, returning a matrix with one pair per row. Used to traverse root-to-tip paths branch by branch.

pd(eco::Ecosystem, qs::Vector{Float64})

Calculate Faith's phylogenetic diversity (PD) for the entire ecosystem.

peakedgradAE(minT::Unitful.Temperature{Float64},
   maxT::Unitful.Temperature{Float64},
   dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64},
   area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝚯*𝐓^-1},
   active::Matrix{Bool})

Create a peaked temperature gradient ContinuousHab, SimpleBudget type abiotic environment. Given a minT and maxT temperature, it generates a gradient with minima at the top and bottom, peaking at maxT in the middle. It creates a ContinuousHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. The rate of temperature change is specified using the parameter rate. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

peakedgradAE(minT::Unitful.Temperature{Float64},
   maxT::Unitful.Temperature{Float64},
   dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64},
   area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝚯*𝐓^-1},
   active::Matrix{Bool})

Create a peaked temperature gradient ContinuousHab, SimpleBudget type abiotic environment. Given a minT and maxT temperature, it generates a gradient with minima at the top and bottom, peaking at maxT in the middle. It creates a ContinuousHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. The rate of temperature change is specified using the parameter rate. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

populate!(ml::GridLandscape, spplist::SpeciesList, abenv::AbstractAbiotic,
          rel::AbstractTraitRelationship, rngs::Vector{Random.Xoshiro})
populate!(ml::GridLandscape, spplist::SpeciesList,
          abenv::GridAbioticEnv{H, BudgetCollection2{B1, B2}}, rel, rngs)

Populate the grid landscape ml by randomly scattering each species' total abundance (taken from spplist.abun) across the grid cells, choosing each cell with probability proportional to its available energy budget. Inactive cells are given zero probability, so no individuals are placed outside the habitable region. Each species is drawn from its own generator in rngs, so the result is reproducible and independent of the number of threads or MPI processes.

rel is unused by these resource-based methods; it is accepted only so that they share a signature with traitpopulate! and can be passed interchangeably as the population function when constructing an Ecosystem. For a two-budget environment (BudgetCollection2) the sampling weight of a cell is the product of its two separately normalised budgets.

raingrad(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64},
  size::Unitful.Length{Float64},
  dim::Tuple{Int64, Int64}, rate::Quantity{Float64, 𝐋*𝐓^-1})

Create a ContinuousHab habitat with a rainfall gradient.

raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64},
  dimension::Tuple{Int64, Int64}, area::Unitful.Area{Float64},
  rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool})

As raingradAE but uses the rainfall values from the gradient directly as a WaterBudget, rather than computing a budget from a separate maxbud value.

```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` Create a rainfall gradient [`ContinuousHab`](@ref), [`SimpleBudget`](@ref) type abiotic environment. Given a `minR` and `maxR` rainfall, it generates a gradient from minimum at the bottom to maximum at the top. It creates a [`ContinuousHab`](@ref) environment with dimensions `dimension` and a specified area `area`. It also creates a [`SimpleBudget`](@ref) type filled with the maximum budget value `maxbud`. The rate of rainfall change is specified using the parameter `rate`. If a Bool matrix of active grid squares is included, `active`, this is used, else one is created with all grid cells active.

```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` As [`raingradAE`](@ref) but uses the rainfall values from the gradient directly as a [`WaterBudget`](@ref), rather than computing a budget from a separate `maxbud` value.

```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` Create a rainfall gradient [`ContinuousHab`](@ref), [`SimpleBudget`](@ref) type abiotic environment. Given a `minR` and `maxR` rainfall, it generates a gradient from minimum at the bottom to maximum at the top. It creates a [`ContinuousHab`](@ref) environment with dimensions `dimension` and a specified area `area`. It also creates a [`SimpleBudget`](@ref) type filled with the maximum budget value `maxbud`. The rate of rainfall change is specified using the parameter `rate`. If a Bool matrix of active grid squares is included, `active`, this is used, else one is created with all grid cells active. ```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` As [`raingradAE`](@ref) but uses the rainfall values from the gradient directly as a [`WaterBudget`](@ref), rather than computing a budget from a separate `maxbud` value.

raingradAE(minR::Unitful.Length{Float64},
  maxR::Unitful.Length{Float64},
  dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64},
  area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1},
  active::Matrix{Bool})

Create a rainfall gradient ContinuousHab, SimpleBudget type abiotic environment. Given a minR and maxR rainfall, it generates a gradient from minimum at the bottom to maximum at the top. It creates a ContinuousHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. The rate of rainfall change is specified using the parameter rate. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` Create a rainfall gradient [`ContinuousHab`](@ref), [`SimpleBudget`](@ref) type abiotic environment. Given a `minR` and `maxR` rainfall, it generates a gradient from minimum at the bottom to maximum at the top. It creates a [`ContinuousHab`](@ref) environment with dimensions `dimension` and a specified area `area`. It also creates a [`SimpleBudget`](@ref) type filled with the maximum budget value `maxbud`. The rate of rainfall change is specified using the parameter `rate`. If a Bool matrix of active grid squares is included, `active`, this is used, else one is created with all grid cells active.

```julia raingradAE(minR::Unitful.Length{Float64}, maxR::Unitful.Length{Float64}, dimension::Tuple{Int64, Int64}, area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝐋*𝐓^-1}, active::Matrix{Bool}) ``` As [`raingradAE`](@ref) but uses the rainfall values from the gradient directly as a [`WaterBudget`](@ref), rather than computing a budget from a separate `maxbud` value.

randomniches(dimension::Tuple, types::Vector{Int64}, clumpiness::Float64,
    weights::Vector, gridsquaresize::Unitful.Length)

Create a DiscreteHab habitat of dimension dimension, made up of integer niche types types with relative weightings weights and spatial clumpiness controlled by clumpiness. Cell size is set by gridsquaresize.

reenergise!(eco::Ecosystem, budget::Union{Float64, Unitful.Quantity{Float64}}, grid::Tuple{Int64, Int64})

Refill an ecosystem eco, with energy from a budget value, budget and a grid size.

repopulate!(eco::Ecosystem)
repopulate!(eco::Ecosystem, abun::Int64)

Repopulate an ecosystem eco by redistributing abundances according to resource availability. If an abun parameter is given, that number of individuals of the final species is added at randomly sampled locations instead.

reroot!(tree::AbstractTree, node::String)

Reroot a phylogenetic tree by removing and recreating node, then attaching a new root node "NewRoot" above the original root.

resetrate!(eco::Ecosystem, rate::Quantity{Float64, typeof(𝐓^-1)})

Reset the rate of habitat change for a species.

resettraits!(tree::AbstractTree)

Clear all node data records in the tree, resetting every node to an empty DataFrame.

root_to_tips(tree)

Return all root-to-tip paths in a phylogenetic tree as a vector of node-name vectors, one per tip.

runscenario!(eco::Ecosystem, timestep::Unitful.Time, scenario::S, currentstep::Unitful.Time) where S <: AbstractScenario

This function runs any scenario type for one timestep.

simplehabitat(val::Float64, size::Unitful.Length, dim::Tuple{Int64, Int64})

Create a dimensionless ContinuousHab filled with val. Uses NoChange as the update rule.

simplehabitat(val::Unitful.Quantity, size::Unitful.Length,
dim::Tuple{Int64, Int64})

Create a ContinuousHab habitat of dimension dim, with cell size and filled value, val.

simplehabitatAE(val::Union{Float64, Unitful.Quantity{Float64}},
    dimension::Tuple{Int64, Int64}, maxbud::Float64, area::Unitful.Area{Float64},
    active::Matrix{Bool})

Create a simple ContinuousHab, SimpleBudget type abiotic environment. It creates a ContinuousHab filled with a given value, val, dimensions (dimension) and a specified area (area). It also creates a SimpleBudget type filled with the maximum budget value (maxbud). If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

simplehabitatAE(val::Union{Float64, Unitful.Quantity{Float64}},
    dimension::Tuple{Int64, Int64}, maxbud::Float64, area::Unitful.Area{Float64},
    active::Matrix{Bool})

Create a simple ContinuousHab, SimpleBudget type abiotic environment. It creates a ContinuousHab filled with a given value, val, dimensions (dimension) and a specified area (area). It also creates a SimpleBudget type filled with the maximum budget value (maxbud). If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

simplenicheAE(numniches::Int64, dimension::Tuple,
                    maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64},
                    active::Matrix{Bool})

Create a simple DiscreteHab, SimpleBudget type abiotic environment. Given a number of niche types numniches, it creates a DiscreteHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

simplenicheAE(numniches::Int64, dimension::Tuple,
                    maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64},
                    active::Matrix{Bool})

Create a simple DiscreteHab, SimpleBudget type abiotic environment. Given a number of niche types numniches, it creates a DiscreteHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

simulate!(cache::CachedEcosystem, srt::Unitful.Time, timestep::Unitful.Time)

Run a cached ecosystem, cache at a specified timepoint, srt, for a particular timestep, timestep.

simulate!(eco::AbstractEcosystem, times::Unitful.Time, timestep::Unitful.Time)

Run an ecosystem, eco for a specified length of time, times, for a particular timestep, timestep.

simulate!(eco::Ecosystem, times::Unitful.Time, timestep::Unitful.Time,
          cacheInterval::Unitful.Time, cacheFolder::String,
          scenario_name::String)

Run an ecosystem, eco for specified length of times, duration, for a particular timestep, 'timestep'. A cache interval and folder/file name are specified for saving output.

simulate_action!(action!::Function, eco::AbstractEcosystem, times::Unitful.Time,
                 interval::Unitful.Time, timestep::Unitful.Time;
                 scenario = nothing, offset = false)

Run an ecosystem eco up to time times in steps of timestep, calling the user-supplied action! at regular intervals so that any periodic task can be performed as the simulation proceeds — recording a quantity, logging progress, applying a management intervention, checking a stopping condition, and so on. This is the general engine behind the simulate_record! and simulate_record_diversity! recorders; use it directly when you want to do something they do not.

At each step the ecosystem is advanced with update! and, if a scenario is given, modified with runscenario! (e.g. to remove habitat or change climate). Whenever the elapsed time falls on a multiple of interval, action!(counting) is called, where counting is the 1-based index of that occurrence (handy as a storage slot when the action is recording); interval must be a whole multiple of timestep. Anything the action needs to read or update — the ecosystem, an output array, an external counter — is captured by the closure, typically written as a do block:

totals = zeros(Int, length((0s):interval:times))
simulate_action!(eco, times, interval, timestep) do counting
    totals[counting] = sum(eco.abundances.matrix)
end

offset shifts the action grid to start at timestep rather than 0, which drops the first occurrence (one fewer action in total). Use it to make the number of actions match a pre-allocated array (such as one from generate_storage); the built-in diversity recorders pass offset = iseven(size(storage, 3)).

Returns the ecosystem eco, now advanced to times.

simulate_record!(storage::AbstractArray, eco::Ecosystem, times::Unitful.Time,
     interval::Unitful.Time, timestep::Unitful.Time)
simulate_record!(storage::AbstractArray, eco::Ecosystem, times::Unitful.Time,
     interval::Unitful.Time, timestep::Unitful.Time, scenario::AbstractScenario)

Run an ecosystem, eco for a specified length of time, times, for a particular timestep, timestep, recording abundances into storage at each time interval interval. If a scenario is given, it is also run at each timestep to modify the ecosystem, allowing simulation of events such as habitat loss or climate change.

Pre-allocate storage with generate_storage(eco, ntimes, reps), where ntimes = length((0s):interval:times) is the number of recordings.

To record diversity rather than raw abundances, see simulate_record_diversity!; to perform an arbitrary action at regular intervals via a callback, see simulate_action!.

simulate_record_diversity!(storage, eco, times, interval, timestep,
                           divfun, qs::Vector{Float64})
simulate_record_diversity!(storage, eco, times, interval, timestep,
                           scenario::SimpleScenario, divfun, qs::Vector{Float64})
simulate_record_diversity!(storage, storage2, eco, times, interval, timestep,
                           qs::Vector{Float64})
simulate_record_diversity!(storage, eco, times, interval, timestep,
                           divfuns::Array{Function}, q::Float64)
simulate_record_diversity!(storage, eco, times, interval, timestep,
                           scenario::SimpleScenario, divfuns::Vector{Function},
                           q::Float64)

Run an ecosystem eco up to times in steps of timestep, recording diversity into storage (and, for the alpha/beta/gamma form, storage2) every interval, which must be a whole multiple of timestep. These are all thin wrappers over simulate_action! — see it for the recording mechanics — and differ only in what diversity they record:

• divfun, qs — a single diversity function divfun (which returns a DataFrame with a :diversity column) evaluated over the diversity orders qs, reshaped into storage;
• storage, storage2, …, qs — normalised alpha, normalised beta and gamma diversity over qs; subcommunity-level values are written to storage (gridSize × 3 × timepoints × qs) and metacommunity-level values to storage2 (3 × timepoints × qs);
• divfuns, q — several diversity functions at a single diversity order q, one per column of storage.

The scenario::SimpleScenario variants additionally apply scenario at each timestep to modify the ecosystem (e.g. removal of habitat patches).

For the divfun/divfuns forms, pre-allocate storage with generate_storage(eco, ncols, ntimes, reps), where ncols is length(qs) (or length(divfuns)) and ntimes = length((0s):interval:times).

sorenson(eco::Ecosystem, qs::Vector{Float64})

Calculate the Sorenson similarity for the entire ecosystem.

species_blocksize()

Number of species iterated together as a contiguous inner block in update!, chosen so one block spans a CPU cache line (cachelinesize ÷ sizeof(Int)).

tematch(sppl::SpeciesList, abenv::AbstractAbiotic)

Check that the types of a trait list and habitat list are the same for a species list (sppl) and abiotic environment (abenv).

tempgrad(minT::Unitful.Temperature{Float64}, maxT::Unitful.Temperature{Float64},
  size::Unitful.Length{Float64},
  dim::Tuple{Int64, Int64}, rate::Quantity{Float64, 𝚯*𝐓^-1})

Create a ContinuousHab habitat with a temperature gradient.

tempgradAE(minT::Unitful.Temperature{Float64},
  maxT::Unitful.Temperature{Float64},
  dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64},
  area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝚯*𝐓^-1},
  active::Matrix{Bool})

Create a temperature gradient ContinuousHab, SimpleBudget type abiotic environment. Given a minT and maxT temperature, it generates a gradient from minimum at the bottom to maximum at the top. It creates a ContinuousHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. The rate of temperature change is specified using the parameter rate. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

tempgradAE(minT::Unitful.Temperature{Float64},
  maxT::Unitful.Temperature{Float64},
  dimension::Tuple{Int64, Int64}, maxbud::Unitful.Quantity{Float64},
  area::Unitful.Area{Float64}, rate::Quantity{Float64, 𝚯*𝐓^-1},
  active::Matrix{Bool})

Create a temperature gradient ContinuousHab, SimpleBudget type abiotic environment. Given a minT and maxT temperature, it generates a gradient from minimum at the bottom to maximum at the top. It creates a ContinuousHab environment with dimensions dimension and a specified area area. It also creates a SimpleBudget type filled with the maximum budget value maxbud. The rate of temperature change is specified using the parameter rate. If a Bool matrix of active grid squares is included, active, this is used, else one is created with all grid cells active.

traitfun(eco::AbstractEcosystem, pos::Int64, sp::Int64)

Calculate relationship between the current environment and a species' particular trait.

traitpopulate!(ml::GridLandscape, spplist::SpeciesList, abenv::AbstractAbiotic,
               rel::AbstractTraitRelationship, rngs::Vector{Random.Xoshiro})

Populate the grid landscape ml by scattering each species' total abundance (taken from spplist.abun) across the grid cells with probability proportional to how well the species' traits match each cell's environment, as scored by the trait relationship rel applied to spplist.traits and abenv.habitat. Where a species matches no cell the distribution falls back to uniform. Only native species (those flagged in spplist.native) are placed; non-native species are left empty.

This is the trait-based counterpart of populate!, which instead weights cells by their available energy budget.

traitrepopulate!(eco::Ecosystem)

Repopulate an ecosystem eco according to how well species traits match their environment, redistributing the total abundance across species at random.

trmatch(sppl::SpeciesList, traitrel::AbstractTraitRelationship)

Check that the types of a trait list and trait relationship list are the same for a species list (sppl) and trait relationship (traitrel).

EcoSISTEM.unziptemp(path::String)

Helper function for the FAIR Data Pipeline to unzip files that are stored as zips to a temporary folder.

update!(eco::AbstractEcosystem, timestep::Unitful.Time)

Dispatch function that selects the appropriate threaded implementation of update! based on the number of available threads.

update!(eco::Ecosystem, timestep::Unitful.Time)

Update an ecosystem's abundances and environment for one timestep.

update_energy_usage!(eco::Ecosystem)

Calculate how much energy has been used up by the current species in each grid square in the ecosystem, eco. This function is parameterised on whether the species have one type of energy requirement or two.

updatesimulation!(cache::CachedEcosystem, tm::Unitful.Time)

Trigger the computation and caching of ecosystem abundances at timepoint tm in a CachedEcosystem.

worldclimAE(wc::Worldclim_monthly, maxbud::Unitful.Quantity{Float64},
  area::Unitful.Area{Float64}, active::Matrix{Bool})

As worldclimAE with an explicit active matrix of grid squares, rather than inferring active cells from NaN values in the Worldclim data.

worldclimAE(wc::Worldclim_monthly, maxbud::Unitful.Quantity{Float64}, area::Unitful.Area{Float64})

Create a ContinuousTimeHab, SimpleBudget type abiotic environment from a Worldclim type climate. It either creates a SimpleBudget type filled with the maximum budget value maxbud or uses a provided budget of type SolarTimeBudget. If a Bool matrix of active grid squares is included, active, this is used, otherwise all grid cells are considered active.

worldclimAE(wc::Worldclim_monthly, bud::B, active::Matrix{Bool}) where B <: AbstractTimeBudget

As worldclimAE but accepts a pre-constructed AbstractTimeBudget object bud rather than computing a budget from a maximum value.

worldclimChange(eco::AbstractEcosystem, hab::ContinuousHab, timestep::Unitful.Time)

Step the Worldclim climate forward by one timestep.

AbstractClimate

Abstract supertype of all climate data.

CERA <: AbstractClimate

Type that houses data extracted from CERA-20C raster files.

CHELSA_monthly <: AbstractClimate

Type that houses data extracted from CHELSA raster files.

CRUTS <: AbstractClimate

Type that houses data extracted from CRUTS raster files.

ClimateRaster{<:RDS.RasterDataSource, <: AxisArray} <: AbstractClimate

Type for climate data derived from RasterDataSources.

ERA <: AbstractClimate

Type that houses data extracted from ERA raster files.

Reference <: AbstractClimate

Type that houses a reference data array.

Worldclim_monthly <: AbstractClimate

Type that houses data extracted from Worldclim raster files.

convert_coords(i::Int64, width::Int64)
convert_coords(x::Int64, y::Int64, width::Int64)

Function to convert coordinates from two-dimensional (x,y) format to one dimension (i), or vice versa, using the width of the grid. This function can also be applied to arrays of coordinates.

create_reference(gridsize::Float64)

Function to create a reference grid array of type Reference.

downresolution(data::Union{ERA, Worldclim_monthly, ClimateRaster{WorldClim{BioClim}, <: AxisArray}}, rescale::Int64; fn)

Function to decrease the resolution of a climate dataset, by a factor, rescale, and aggregation function, fn. The aggregation function has a default setting of taking the mean value.

downresolution!(resized_array::Matrix{T}, array::Matrix{T}, rescale::Int64, fn)
downresolution!(resized_array::Array{T, 3}, array::Matrix{T}, dim::Int64, rescale::Int64, fn)

Function to decrease the resolution of a climate dataset in place, by a factor, rescale, and aggregation function, fn. The aggregation function has a default setting of taking the mean value.

extractvalues(x::Vector{typeof(1.0°)},y::Vector{typeof(1.0°)},
    bc::ClimateRaster, dim::Unitful.Time)

Function to extract values from a bioclim object, at specified lat, long locations and time, dim.

extractvalues(x::Vector{typeof(1.0°)},y::Vector{typeof(1.0°)},
    bc::ClimateRaster, dim::Unitful.Time)

Function to extract values from a bioclim object, at specified x, y locations and over a time period, dim.

extractvalues(x::Vector{typeof(1.0°)},y::Vector{typeof(1.0°)},
    wc::Worldclim_monthly, dim::Unitful.Time)

Function to extract values from a worldclim object, at specified x, y locations and over a range of times, dim.

extractvalues(x::Vector{typeof(1.0°)},y::Vector{typeof(1.0°)},
    wc::Worldclim_monthly, dim::Unitful.Time)

Function to extract values from a worldclim object, at specified x, y locations and time, dim.

fitBrownian(tree::AbstractTree, traits::Vector{F}) where F <: AbstractFloat

Fit a Brownian motion model of trait evolution to traits measured at the tips of tree. Returns a Brownian object containing the maximum likelihood estimates of the diffusion rate σ² and root state z̄₀, their standard errors, the Hessian, and the log-likelihood.

fitLambda(tree::AbstractTree, traits::Vector{F}) where F <: AbstractFloat

Fit Pagel's lambda model of trait evolution to traits measured at the tips of tree. Returns a Lambda object containing the maximum likelihood estimates of σ², root state z̄₀, and phylogenetic signal λ, their standard errors, the Hessian, and the log-likelihood.

readCERA(dir::String, file::String, params::String)

Function to extract a certain parameter, param, from an CERA-20C netcdf file, and convert into an axis array.

readCHELSA_monthly(dir::String)

Function to extract all raster files from a specified folder directory, and convert into an axis array.

readCRUTS(dir::String)

Function to extract all raster files from a specified folder directory, and convert into an axis array.

readERA(dir::String, file::String, param::String, dim::Vector{Vector{<: Unitful.Time}}; cut = nothing)

Function to extract a certain parameter, param, from a directory, dir, containing ERA netcdf files, for a certain timerange, dim, and convert into an axis array.

readERA(dir::String, param::String, dim::StepRange(typeof(1month)); cut = nothing)

Function to extract a certain parameter, param, from an ERA netcdf file, for a certain timerange, dim, and convert into an axis array.

readag(f, filename)

Function to read raster file into julia.

readbioclim(T::Type{WorldClim{BioClim}}, files; cut = nothing)

Function to extract all raster files from a specified folder directory, and convert into an axis array.

readfile(file::String)

Function to import a selected file from a path string.

readlc(::Type{<:EarthEnv{<:LandCover}}, files; scale = 10, fn = x -> round(mean(x)),
       cut = nothing)

Function to extract all raster files from a specified folder directory, and convert into an axis array.

readworldclim(dir::String; cut = nothing)

Function to extract all raster files from a specified folder directory, and convert into an axis array.

searchdir(path,key)

Function to search a directory path using a given key string.

upresolution(data::Union{ERA, Worldclim_monthly, ClimateRaster}, rescale::Int64; fn)

Function to increase the resolution of a climate dataset, by a factor, rescale.

varcovar(tree::AbstractTree)

Compute the phylogenetic variance-covariance matrix from the branch lengths of tree. The diagonal entries are the root-to-tip distances and the off-diagonal entries are the shared root-to-ancestor distances between pairs of tips.