Developers

Chunk

Struct for saving chunk coordinates

Fields

• x::Int
• y::Int

Duration

Struct for saving the length of the runtime for the entire simulation.

Fields

• start_time::DateTime: time when simulation was started
• end_time::DateTime: time when simulation has finished

Env_Preferences

Struct for saving the environmental preferences of a species.

Fields

• upper_limit::Float64: species parameter
• lower_limit::Float64: species parameter
• optimum::Float64: species parameter

Landscape

Struct representing the landscape/environment.

Fields

• xlength::Int64: equivalent to size[2] of any Array in this struct
• ylength::Int64: equivalent to size[1] of any Array in this struct
• environment::Dict{String, Array{Float64, 3}}: contains all environment attributes,

addressable by name

• restrictions::Array{Float64, 3}: #TODO

Output

represents the output of a simulation run for a species.

Fields

• abundances: amount of individuals for each species in each timestep
• habitat: habitat suitability for each species in each timestep
• carry: carrying capacity for each species in each timestep
• growrate: growth rate for each species in each timestep
• bevmort: background mortality rate for each species in each timestep

Simulation_Data

Struct for saving all data related to the simulation

Fields

• parameters::Simulation_Parameters: simulation parameters of the experiment
• landscape::Landscape: landscape of the experiment
• species::Vector{Species}: a vector of all the species in the experiment
• duration::Duration: saves the duration the experiment took to compute

Simulation_Parameters

Struct for saving simulation parameters.

Fields

• experiment_name::String: name of the experiment
• config_dir::String: path to the folder containing the config_file
• config_file::String: path to the config_file
• output_dir::String: path to the folder where the output should be saved
• species_dir::String: path to the folder containing the species definitions
• environment_dir::String: path to the folder or file containing the environment tables
• input_backup::Bool: if true, the input files will be copied to the output folder
• env_attribute_files::Dict{String, String}: #TODO
• env_restriction_files::Dict{String, String}: #TODO
• env_attribute_mode::String: #TODO
• env_restriction_mode::String: #TODO
• attribute_restriction_blending::String: #TODO
• timesteps::Int64: number of timesteps in the simulation
• randomseed::Int64: seed for number generator used in the simulation
• reproduction_model::String: #TODO
• use_metabolic_theory::Bool: #TODO

#- use_stoch_allee::Bool: if true the allee effect will be stochastic #- use_stoch_carry::Bool: if true the carrying capacity will be stochastic

• use_stoch_num::Bool: #TODO Stochastic Survival see R code
• initialize_cells::String: #TODO

Simulation_Variables

Simulation variables used for a species during run_simulation!"

Fields

• habitat::Array{Float64, 2}: habitability of landscape cells for a species at current

simulation timestep

• is_habitat::BitArray{2}: if landscape cells are habitable for a species at current

simulation timestep

• future_habitat::Array{Float64}: TODO
• future_is_habitat::BitArray{2}: if landscape cells are habitable for a species at next

simulation timestep

• biomass::Array{Float64, 2}: biomass of a species individual at landscape cells
• growrate::Array{Float64, 2}: growrate of species at landscape cells
• carry::Array{Float64, 2}: carry property of species at landscape cells
• allee::Array{Float64, 2}: allee property of species at landscape cells
• bevmort::Array{Float64, 2}: Beverton mortaility of species at landscape cells
• occurrences::Vector{CartesianIndex{2}}: list of cells where species occurs at current

timestep

• offspring::Array{Float64, 2}: offspring of species at current timestep

Species

Saving all data related to a species.

Fields

• species_name::String: name of the species
• traits::Traits: a (Traits)[@ref] struct for the species
• abundances::Array{Union{Int64, Missing}, 3}: amount of individuals of this species in

each timestep

• habitat::Array{Float64, 3}: habitat suitability in each timestep
• dispersal_kernel::Matrix{Float64}:#TODO
• vars::Simulation_Variables:#TODO

Traits

Traits of a species.

#TODO: Add description in fields

Fields

• mass::Float64:
• sd_mass::Float64:
• growrate::Float64:
• sd_growrate::Float64:
• param_const_growrate::Union{Float64, Nothing}:
• max_dispersal_dist::Int64:
• max_dispersal_buffer::Int64:
• mean_dispersal_dist::Union{Int64, Float64}:
• allee::Float64: Allee effect counteracting negative diversity loss in small populations
• sd_allee::Float64: Allee effect standard deviation
• param_const_allee::Union{Float64, Nothing}:
• bevmort::Float64:
• sd_bevmort::Float64:
• param_const_bevmort::Union{Float64, Nothing}:
• carry::Float64:
• sd_carry::Float64:
• param_const_carry::Union{Float64, Nothing}:
• env_preferences::Dict{String, Env_Preferences}:
• habitat_cutoff_suitability::Float64:

BV(N::Int64, growrate::Float64, carry::Float64, mortality::Float64)

Returns the number of individuals in the next generation according to the Beverton-Holt model. Includes stochastic mortality.

BVNoStoch(N::Int64, growrate::Float64, carry::Float64, mortality::Float64)

Returns the number of individuals in the next generation according to the Beverton-Holt model. Does not include stochastic mortality.

DispersalNegExpFunction(alpha, r)

TODO

DispersalNegExpKernel(Dispersalbuffer, mean_dispersal_dist)

TODO

DispersalSurvivalRound(
Abundances::Array{Union{Missing, Int64},2},
Offspring::Array{Float64,2}, xy::Array{Int64,2},
max_dispersal_dist::Int64
)

TODO

DispersalSurvivalStoch(
Abundances::Array{Union{Missing, Int64},2},
Offspring::Array{Float64,2},xy::Array{Int64,2},
max_dispersal_dist::Int64
)

TODO

Disperse!(
species::Vector{Species},
LS::Landscape,
groups::NTuple{4, Vector{Chunk}},
timestep::Int64,

)

Dispersal

GetDisjunctChunkGroups(
max_dispersal_buffer::Int64,
size::Tuple{Int64, Int64, Int64},

)

Calculate the distinct chunk groups

GetDispersalSurvival(use_stoch_Num::Bool)

TBW

GetReproductionModel(reproduction_model::String)

TBW

HabitatMortality(Abundances::Matrix{Union{Missing,Int64}}, Is_habitat::BitArray{2})

Habitat based mortality.

This function kills individuals that are in non suitable Habitat.

• Abundances: array with the number of individuals in the landscape
• Is_habitat: array with boolean values that indicate

which cell is habitat in the next timestep

KernelDispersal!(N::Int64, Offspring::Array{Float64,2}, Dispersal_kernel::Array{Float64,2})

TODO

MortalityBev(N::Int64, mortality::Float64)

Returns how many Individuals die. Includes Stochasticity

MortalityBevNoStoch(N::Int64, mortality::Float64)

Returns how many Individuals die. No Stochasticity

ReproductionBeverton(N::Int64, growrate::Float64, carry::Float64, mortality::Float64)

Returns the number of offspring in the next generation according to the Beverton-Holt model.

ReproductionRicker(N::Int64, growrate::Float64, carry::Float64, unused::Union{Float64,Nothing})

Returns the number of Individuals in the next generation according to the Ricker model.

ReproductionRickerAllee(N::Int64, growrate::Float64, carry::Float64, allee::Union{Float64,Nothing})

Returns the number of Individuals in the next generation according to the Ricker model. Includes allee effects

Survive!(species::Vector{Species}, DispersalSurvival, t::Int64)

TBW

backup_config(SD::Simulation_Data, backup_path::String)

Record the settings actually used for a simulation run and creates a config file that can be used for future replicate runs.

backup_input(SP::Simulation_Parameters)

Initializes the output directory. This is called when input_backup in the configuration file is set to true and creates a backup of the input files in the output directory.

check_attribute_values!(attribute::Array{Float64}, key::String)

Sanity checks for Attribute Matrices. Will convert Celsius values to Kelvin.

check_environment_dir(config::Simulation_Parameters)

Checks if the environment directory exists and throws an error if it doesn't.

check_for_nan(attribute::Array{Float64})

Checks for NaNs in parameter matrix

check_species_dir(config::Simulation_Parameters)

Checks if the species directory exists and throws an error if it doesn't.

demo_input()

Initializes a simple default run Simulation_Data struct.

df_output(SD::Simulation_Data)

Create a dataframe from the output of a simulation.

Arguments

• SD::Simulation_Data: A Simulation_Data object containing the output data.

Returns

• A DataFrame object with the following columns:
  • t: time
  • x: x-coordinate of the patch
  • y: y-coordinate of the patch
  • abundance: abundance of the species in the patch
  • reproduction: growth rate of the species in the patch
  • habitat: habitat suitability of the patch
  • carry: carrying capacity of the patch
  • bevmort: background mortality rate of the species in the patch

Examples

julia> df = df_output(SD)

disperse_chunk!(
species::Species,
occurrences::Vector{CartesianIndex{2}},
offspring::Matrix{Float64},
chunk::Chunk,
t::Int64,

)

Parallel Dispersal in a given chunk

get_Env_Preferences(species::Dict, key::String)

Returns the environmental preference for the supplied trait in key with limits and optimum as an Env_Preferences object.

get_Simulation_Parameters(config::Dict)

Returns a Simulation_Parameters object constructed from the configuration Dictionary.

get_Simulation_Variables()

Initializes an empty Simulation_Variables object. Each parameter is defined with an empty matrix eqivalent to the landscape's size.

get_Traits(species::Dict)

Extracts species traits from the configuration dictionary and returns a Trait object.

get_biomass(mass, sd_mass, ysize, xsize)

TBW

get_default_LS()

Creates a Default Landscape with random values and some NAs for testing.

get_default_simulation_parameters()

Returns a Dictionary with default simulation parameters.

get_default_species(LS::Landscape, SP::Simulation_Parameters)

TBW

get_environment_dir(config::Simulation_Parameters)

Returns full path to environment folder or returns config_dir/environment when no path to the species folder is provided.

get_habitat(
env_pref::Dict{String, Env_Preferences},
LS::Landscape,
attribute_mode::String,
t::Int

)

Get habitat in current timestep. Return Array{Float64, 2}

get_is_habitat(habitat, habitat_cutoff_suitability)

TBW

get_out_dir(SP::Simulation_Parameters)

Names a new output directory for the simulation used in backup_input()[@ref]. This directory will only be created if backup is true or the user later saves an output into the default paths

get_pop_bevmort(
traits::Traits,
LS::Landscape,
habitat::Array{Float64,2},
mass::Union{Float64,Array{Float64,2}},
use_metabolic_theory::Bool,
timestep::Int,
E::Float64,

)

TBW

get_pop_carry(
traits::Traits,
LS::Landscape,
habitat::Array{Float64,2},
mass::Array{Float64,2},
use_metabolic_theory::Bool,
timestep::Int,
E::Float64,

)

TBW

get_pop_var(
trait::Float64,
sd_trait::Float64,
exp_trait::Float64,
param_const_trait::Union{Float64,Nothing},
traits::Traits,
LS::Landscape,
mass::Array{Float64,2},
use_metabolic_theory::Bool,
timestep::Int, E::Float64,

)

TBW

get_species_dir(config::Simulation_Parameters)

Returns full path to species folder or returns config_dir/species when no path to the species folder is provided.

get_testrun_simulation_parameters()

TBW

gif(SD::Simulation_Data, arg::String, frames::Int)

Plots the specified output for timestep t.

Arguments

• SD::Simulation_Data: Simulation_Data object
• arg::String: argument on what shall be displayed. Must be one of restrictions, abundances, suitability, temperature, precipitation, carry, growrate, or mortality.
• frames::Int: number of frames per second

Returns

• The gif is saved under the name "arg.gif" in the output directory.

gif_complex(SD::Simulation_Data; frames = 2)

Plot environment, species environmental preferences, habitat suitability, and abundances and create a GIF.

Arguments

• SD::Simulation_Data: Simulation_Data object
• frames::Int: framerate

Returns

• The gif is saved under the name "all.gif" in the output directory.

Examples

julia> gif_complex(SD)

img(SD::Simulation_Data, t::Int, arg::String)

Plots the specified output for timestep t.

Arguments

• SD::Simulation_Data: Simulation_Data object
• t::Int: timestep
• arg::String: argument on what shall be displayed. Must be one of restrictions, abundances, suitability, temperature, precipitation, carry, growrate, or mortality.

Returns

• f::Figure: Figure object

img_complex(SD::Simulation_Data, t::Int)

Plot environment, species environmental preferences, habitat suitability, and abundances for a given timestep.

Arguments

• SD::Simulation_Data: Simulation_Data object
• t::Int: timestep

Returns

• f::Figure: Figure object

Examples

julia> f = img_complex(SD, 19)
julia> f

init_species_sim_vars!(
species::Array{Species},
LS::Landscape,
parameters::Simulation_Parameters,
timestep::Int,

)

TBW

initialize_abundances(
    SP::Simulation_Parameters,
    habitat::Array{Float64, 2},
    carry::Float64)

Initialization of Abundances.

initialize_output(
SP::Simulation_Parameters,
LS::Landscape,
abundances::Array{Int64,3},
habitat::Array{Float64,3},

)

Initializes the output struct. Calculation of the first timesteps is done outside the function.

make_out_dir(out_dir::String)

create an output directory if it does not exist

parse_environment_parameters!(config::Dict, input_config::Dict)

Build the Dicts containing environment attribute and restriction files.

parse_species_datatypes!(species::Dict)

Convert all Float and Integer arguments to their respective Julia types (as needed for the species)

plot_abundances(SD::Simulation_Data)

Plot the total abundances of a species over time.

Arguments

• SD::Simulation_Data: Simulation_Data object

Returns

• f::Figure: Figure object

Examples

julia> f = plot_abundances(SD)
julia> f

randomize!(value,sd)

Takes a parameter or array of parameters and modifies it according to a lognormal distribution based on standard deviation sd

read_input(path::String)

Read in the configuration and associated files in the folder and return a Simulation_Data struct.

Arguments

• path::String: Path to the configuration file.

Returns

• SD::Simulation_Data: Returns the initialised simulation data struct with the first timestep.

Examples

julia> SD = read_input("path/to/config.csv")
precipitation
temperature
...

See also run_simulation!(), Simulation_Data

read_species_dir(species_dir::String, LS::Landscape, SP::Simulation_Parameters)

Read species directory, calculate properties and parameters if not provided and return as a vector of Species objects.

read_ts_config(env_dir::String, ls_timeseries_config::String)

Returns the timeseries generator configuration as a Dict (no struct as it's only used once)

reproduce(species, reproduction, timestep)

Reproduction function. Takes a vector of species structs, a reproduction function and a timestep and calculates the amount of species in the next timestep.

run_simulation!(SD::Simulation_Data)

Run an ecological simulation.

Take the initialized simulation data SD and run the simulation for the specified number of timesteps.

Arguments

• SD::MetaRange.Simulation_Data: MetaRange simulation data struct produced by

read_input()

Returns

• SD::MetaRange.Simulation_Data: Returns the struct with later timesteps after initialisation simulated.

Examples

julia> run_simulation!(SD)

See also read_input(), Simulation_Data

save_output(SD::Simulation_Data)

Save all output variables in a .tsv file.

This function writes all output variables abundance - into a .tsv file.

Arguments

• SD::Simulation_Data: Simulation_Data object

Returns

• A .tsv file with the following columns in the output directory`:
  • t: time
  • x: x-coordinate of the patch
  • y: y-coordinate of the patch
  • abundance: abundance of the species in the patch
  • reproduction: growth rate of the species in the patch
  • habitat: habitat suitability of the patch
  • carry: carrying capacity of the patch
  • bevmort: background mortality rate of the species in the patch

Examples

julia> save_output(SD)

sp_sanity_checks!(config::Dict)

Check if necessary configuration fields are missing

species_default()

Returns a dictionary of default species