run_simulation: Run the simulation
In TheoPannetier/comrad: R implementation of a Competitive Radiation model

run_simulation

R Documentation

Run the simulation

Description

Run the individual-based model simulation.

Usage

run_simulation(
  path_to_output,
  nb_gens,
  init_comm = comrad::default_init_comm(),
  init_comm_is_from = NA,
  growth_rate = comrad::default_growth_rate(),
  competition_sd = comrad::default_competition_sd(),
  carrying_cap_sd = comrad::default_carrying_cap_sd(),
  carrying_cap_opt = comrad::default_carrying_cap_opt(),
  trait_opt = comrad::default_trait_opt(),
  mutation_sd = comrad::default_mutation_sd(),
  trait_dist_sp = comrad::default_trait_dist_sp(),
  switch_carr_cap_sd_after = NA,
  switch_carr_cap_sd_to = NA,
  sampling_on_event = FALSE,
  sampling_freq = ifelse(sampling_on_event, NA, comrad::set_sampling_freq(nb_gens)),
  sampling_frac = comrad::default_sampling_frac(),
  seed = comrad::default_seed(),
  hpc_job_id = NULL
)

Arguments

`path_to_output`	character, path to save the output file, which must be a `.csv`. If `NULL`, the output is not saved and the final state of the community is returned at the end of the simulation.
`nb_gens`	integer, the number of generations to run the simulation for.
`init_comm`	The initial community. Default is `default_init_comm()`, any other input should have the same structure, i.e. a data frame with four columns, "t" / "z" / "species" / "ancestral_species", and one row for each individual in the community.
`init_comm_is_from`	optional string passed to metadata, where the initial community was taken from (a filename or anything else).
`growth_rate`	numeric `⁠>= 0⁠`, the baseline growth rate. Generations being discrete, high values will cause chaos.
`competition_sd`	numeric `⁠>= 0⁠`.Parameter `\sigma_{\alpha}` of the competition coefficient. Modulates the the strength of competition between two individuals given their distance in trait space.
`carrying_cap_sd`	numeric `⁠>= 0⁠`. Parameter `\sigma_K` of the carrying capacity. Modulates how fast the carrying capacity decays when moving away from the optimal trait value.
`carrying_cap_opt`	numeric, value of the carrying capacity at `trait_opt`
`trait_opt`	numeric. The optimal trait value, `z_{opt}`. `get_carrying_cap(trait_opt) = carrying_cap_opt`.
`mutation_sd`	numeric `⁠>= 0⁠`, the standard deviation of the normal distribution from which mutations are drawn.
`trait_dist_sp`	numeric, the minimal trait distance between two clusters of individuals triggering speciation.
`switch_carr_cap_sd_after`	if not `NA`, the value of `carrying_cap_sd` will switch to `switch_carr_cap_sd_to` at t = `switch_carr_cap_sd_after` + 1.
`switch_carr_cap_sd_to`	the value to switch `carrying_cap_sd` to if `switch_carr_cap_sd_after` is not `NA`.
`sampling_on_event`	logical. If `TRUE`, the community is sampled every time a speciation or extinction happens, and `sampling_freq` is ignored and must be set to `NA`.
`sampling_freq`	numeric `> 0`, the frequency (in generations) at which the community is written to output. See `set_sampling_freq()` for the default option.
`sampling_frac`	numeric (between 0 and 1), fraction of the community (in terms of individuals) written to output at every sampled generation. A truncation is operated.
`seed`	integer `> 0`, the seed to set for the random number generator. Defaults to an integer based on current day and time.
`hpc_job_id`	used to record a job ID in the metadata, only relevant for simulations run on a high-performance cluster. Otherwise takes value `"local"`.

Value

Returns a table with a row corresponding to each individual, and five columns: t is the generation time, z the individual's trait value, species the name of the species it belongs to, and ancestral_species the previous species it descends from. If path_to_output = NULL, the community at the last generation is returned. If the path to a .csv file is supplied, each sampled generation is appended to the file. In the .csv, the table is preceded by some lines of metadata, which are automatically ignored if the file is read with read_comrad_tbl().