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

run_simulation

R Documentation

Run the simulation

Description

Run the competitive radiation simulation.

Usage

run_simulation(
  path_to_output,
  nb_gens,
  immigration_rate,
  mainland_nb_species = comsie::default_mainland_nb_species(),
  mainland_z_sd = comsie::default_mainland_z_sd(),
  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(),
  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,
  brute_force_opt = "none"
)

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.
`immigration_rate`	a positive number, the rate at which external immigrant populations enter the community.
`mainland_nb_species`	integer, the number of species in the island community.
`mainland_z_sd`	standard deviation of the trait distribution of mainland species
`growth_rate`	numeric `>= 0`, the baseline growth rate. Generations being discrete, high values will cause chaos.
`competition_sd`	numeric `>= 0`.Parameter σ_{α} 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 σ_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 distrbution from which mutations are drawn.
`trait_dist_sp`	numeric, the minimal trait distance between two clusters of individuals triggering speciation.
`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 `comrad::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"`.
`brute_force_opt`	a string specifying which brute force option to use to speed up the calculation of competition coefficients. Defaults to "none". Other options are "omp", for multithreading with OpenMP, "simd" for single instruction, multiple data (SIMD) via the C++ library `xsimd`; and "simd_omp" for both.

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 comrad::read_comrad_tbl().