metaRangeSimulation | R Documentation |
Creates an simulation object in form of an R6 class that stores and handles all the individual parts that are necessary to run a simulation.
A <metaRangeSimulation>
object
ID
<string>
simulation identification.
globals
<environment>
a place to store global variables.
environment
<metaRangeEnvironment>
A metaRangeEnvironment
that holds all the environmental values influencing the simulation.
number_time_steps
<integer>
number of time steps in the simulation.
time_step_layer
<integer>
vector of layer IDs
that describe which environmental layer to use at each time step.
current_time_step
<integer>
current time step.
queue
<metaRangePriorityQueue>
manages the order in which the processes should be executed.
processes
<list>
of global (simulation level) <metaRangeProcess>
(es).
seed
<integer>
seed for the random number generator.
new()
Creates a new metaRangeSimulation object.
metaRangeSimulation$new(source_environment, ID = NULL, seed = NULL)
source_environment
<SpatRasterDataset>
created by terra::sds()
that represents the environment.
The individual data sets represent different environmental variables
(e.g. temperature or habitat availability) and the different layer of the data sets
represent the different timesteps of the simulation.
The function metaRangeSimulation$set_time_layer_mapping()
can be used
to extend/ shorten the simulation timesteps and set the mapping between each time step and a corresponding
environmental layer. This can be used e.g. to repeat the first (few) layer as a burn-in period.
The number of layers must be the same for all data sets.
ID
<string>
optional simulation identification string.
Will be set automatically if none is specified.
seed
<integer>
optional seed for the random number generator.
Will be set automatically if none is specified.
A <metaRangeSimulation>
object.
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim
add_globals()
Add global variables to the simulation
metaRangeSimulation$add_globals(...)
...
<any>
the variables to add.
Variables to add to the simulation. They will be saved and accessible
through the 'globals' field.
<invisible self>
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_globals(a = 1, b = 2) sim$globals$a #> [1] 1
set_time_layer_mapping()
Set the time layer of the simulation.
metaRangeSimulation$set_time_layer_mapping(x)
x
<integer>
vector of layer indices
that describe which environmental layer to use at each time step.
<invisible self>
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$set_time_layer_mapping(1:2) stopifnot(identical(sim$time_step_layer, 1:2))
get_current_time_step()
Get current time step
metaRangeSimulation$get_current_time_step()
<integer>
the current time step
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$get_current_time_step() #> [1] 1
add_species()
Adds new species to the simulation
metaRangeSimulation$add_species(names)
names
<character>
names of the species to add.
<invisible boolean>
TRUE
on success FALSE
on failure.
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_species(c("species_1", "species_2")) sim$species_1
species_names()
Returns the names of all species in the simulation.
metaRangeSimulation$species_names()
<character>
vector of species names
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_species("species_1") sim$add_species("species_2") sim$species_names() #> [1] "species_1" "species_2"
add_process()
Adds a process to the simulation.
metaRangeSimulation$add_process( species = NULL, process_name, process_fun, execution_priority, queue = TRUE )
species
<character>
Names of the species that the process should be added to.
If NULL
the process will be added to the simulation object itself.
process_name
<string>
Name of the process to add.
process_fun
<named function>
The function to call when the process gets executed.
execution_priority
<positive integer>
When this process should run within each time step.
1 == highest priority i.e. this function will be the executed first.
queue
<boolean>
If TRUE
the process will be added to the process execution queue directly.
If FALSE
the process will be added to the simulation but not to the queue,
which means that in order to execute the process, it has to be added manually
via the metaRangePriorityQueue$enqueue()
method.
<invisible self>
.
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_species("species_1") sim$add_process("species_1", "species_process_1", function() {message("process_1")}, 1) sim$species_1$processes$species_process_1 sim$add_process(species = NULL, "global_process_2", function() {message("process_2")}, 2) sim$processes$global_process_2
add_traits()
Adds traits to a species.
metaRangeSimulation$add_traits(species, population_level = TRUE, ...)
species
<character>
Names of the species that the traits should be added to.
population_level
<boolean>
If TRUE
the traits will be added at the population level
(i.e. as a matrix with same dimensions (nrow/ncol) as the environment with one value for each population).
This means that the traits either need to be single values that will be extended
to such a matrix via base::matrix()
or they already need to be a matrix with these dimension.
If FALSE
the traits will be added without any conversion and may have any type and dimension.
...
<atomic>
(see base::is.atomic()
) The named traits to be added.
Named means: Name = value
e.g. a = 1
.
<invisible self>
.
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_species("species_1") sim$add_traits("species_1", population_level = TRUE, a = 1) sim$add_traits("species_1", population_level = FALSE, b = 2, c = "c") sim$species_1$traits$a #> [,1] [,2] #> [1,] 1 1 #> [2,] 1 1 sim$species_1$traits$b #> [1] 2 sim$species_1$traits$c #> [1] "c"
exit()
When called, will end the simulation (prematurely) once the current process is finished. Useful to e.g. end the simulation safely (i.e. without an error) when no species is alive anymore and there would be no benefit to continue the execution until the last time step.
metaRangeSimulation$exit()
invisible NULL
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4)) names(sim_env) <- "env_var_name" sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_species("species_1") sim$add_process("species_1", "species_process_1", function() {self$sim$exit()}, 1) sim$begin()
begin()
Begins the simulation
metaRangeSimulation$begin()
<invisible self>
The finished simulation
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4)) names(sim_env) <- "env_var_name" sim <- metaRangeSimulation$new(source_environment = sim_env) sim$add_process( species = NULL, "timestep_counter", function() { message("timestep: ", self$get_current_time_step()) }, 1 ) sim$begin()
print()
Prints information about the simulation to the console
metaRangeSimulation$print()
<invisible self>
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$print()
summary()
Summarizes information about the simulation and outputs it to the console
metaRangeSimulation$summary()
<invisible self>
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2)) sim <- metaRangeSimulation$new(source_environment = sim_env) sim$summary()
## ------------------------------------------------
## Method `metaRangeSimulation$new`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim
## ------------------------------------------------
## Method `metaRangeSimulation$add_globals`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_globals(a = 1, b = 2)
sim$globals$a
#> [1] 1
## ------------------------------------------------
## Method `metaRangeSimulation$set_time_layer_mapping`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$set_time_layer_mapping(1:2)
stopifnot(identical(sim$time_step_layer, 1:2))
## ------------------------------------------------
## Method `metaRangeSimulation$get_current_time_step`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$get_current_time_step()
#> [1] 1
## ------------------------------------------------
## Method `metaRangeSimulation$add_species`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_species(c("species_1", "species_2"))
sim$species_1
## ------------------------------------------------
## Method `metaRangeSimulation$species_names`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_species("species_1")
sim$add_species("species_2")
sim$species_names()
#> [1] "species_1" "species_2"
## ------------------------------------------------
## Method `metaRangeSimulation$add_process`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_species("species_1")
sim$add_process("species_1", "species_process_1", function() {message("process_1")}, 1)
sim$species_1$processes$species_process_1
sim$add_process(species = NULL, "global_process_2", function() {message("process_2")}, 2)
sim$processes$global_process_2
## ------------------------------------------------
## Method `metaRangeSimulation$add_traits`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_species("species_1")
sim$add_traits("species_1", population_level = TRUE, a = 1)
sim$add_traits("species_1", population_level = FALSE, b = 2, c = "c")
sim$species_1$traits$a
#> [,1] [,2]
#> [1,] 1 1
#> [2,] 1 1
sim$species_1$traits$b
#> [1] 2
sim$species_1$traits$c
#> [1] "c"
## ------------------------------------------------
## Method `metaRangeSimulation$exit`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4))
names(sim_env) <- "env_var_name"
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_species("species_1")
sim$add_process("species_1", "species_process_1", function() {self$sim$exit()}, 1)
sim$begin()
## ------------------------------------------------
## Method `metaRangeSimulation$begin`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2, nlyr = 4))
names(sim_env) <- "env_var_name"
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$add_process(
species = NULL,
"timestep_counter",
function() {
message("timestep: ", self$get_current_time_step())
},
1
)
sim$begin()
## ------------------------------------------------
## Method `metaRangeSimulation$print`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$print()
## ------------------------------------------------
## Method `metaRangeSimulation$summary`
## ------------------------------------------------
sim_env <- terra::sds(terra::rast(vals = 1, nrow = 2, ncol = 2))
sim <- metaRangeSimulation$new(source_environment = sim_env)
sim$summary()
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.