Run a slendr model in SLiM — slim • slendr

This function will execute a SLiM script generated by the compile function during the compilation of a slendr demographic model.

Usage

slim(
  model,
  sequence_length,
  recombination_rate,
  samples = NULL,
  output = NULL,
  burnin = 0,
  max_attempts = 1,
  spatial = !is.null(model$world),
  coalescent_only = TRUE,
  method = c("batch", "gui"),
  random_seed = NULL,
  run = TRUE,
  verbose = FALSE,
  load = TRUE,
  locations = NULL,
  slim_path = NULL
)

Arguments

model: Model object created by the compile function
sequence_length: Total length of the simulated sequence (in base-pairs)
recombination_rate: Recombination rate of the simulated sequence (in recombinations per basepair per generation)
samples: A data frame of times at which a given number of individuals should be remembered in the tree-sequence (see schedule_sampling for a function that can generate the sampling schedule in the correct format). If missing, only individuals present at the end of the simulation will be recorded in the tree-sequence output file.
output: Path to the output tree-sequence file. If NULL (the default), tree sequence will be saved to a temporary file.
burnin: Length of the burnin (in model's time units, i.e. years)
max_attempts: How many attempts should be made to place an offspring near one of its parents? Serves to prevent infinite loops on the SLiM backend. Default value is 1.
spatial: Should the model be executed in spatial mode? By default, if a world map was specified during model definition, simulation will proceed in a spatial mode.
coalescent_only: Should initializeTreeSeq(retainCoalescentOnly = <...>) be set to TRUE (the default) or FALSE? See "retainCoalescentOnly" in the SLiM manual for more detail.
method: How to run the script? ("gui" - open in SLiMgui, "batch" - run on the command line)
random_seed: Random seed (if missing, SLiM's own seed will be used)
run: Should the SLiM engine be run? If FALSE, the command line SLiM command will be printed (and returned invisibly as a character vector) but not executed.
verbose: Write the SLiM output log to the console (default FALSE)?
load: Should the final tree sequence be immediately loaded and returned? Default is TRUE. The alternative (FALSE) is useful when a tree-sequence file is written to a custom location to be loaded at a later point.
locations: If NULL, locations are not saved. Otherwise, the path to the file where locations of each individual throughout the simulation will be saved (most likely for use with animate_model).
slim_path: Optional way to specify path to an appropriate SLiM binary (this is useful if the slim binary is not on the $PATH).

Value

A tree-sequence object loaded via Python-R reticulate interface function ts_load

(internally represented by the Python object tskit.trees.TreeSequence). Optionally, depending on the value of the arguments load = or run =, nothing or a character vector, respectively.

Examples

check_dependencies(python = TRUE, slim = TRUE, quit = TRUE) # dependencies must be present

init_env()
#> The interface to all required Python modules has been activated.

# load an example model
model <- read_model(path = system.file("extdata/models/introgression", package = "slendr"))

# afr and eur objects would normally be created before slendr model compilation,
# but here we take them out of the model object already compiled for this
# example (in a standard slendr simulation pipeline, this wouldn't be necessary)
afr <- model$populations[["AFR"]]
eur <- model$populations[["EUR"]]
chimp <- model$populations[["CH"]]

# schedule the sampling of a couple of ancient and present-day individuals
# given model at 20 ky, 10 ky, 5ky ago and at present-day (time 0)
modern_samples <- schedule_sampling(model, times = 0, list(afr, 5), list(eur, 5), list(chimp, 1))
ancient_samples <- schedule_sampling(model, times = c(30000, 20000, 10000), list(eur, 1))

# sampling schedules are just data frames and can be merged easily
samples <- rbind(modern_samples, ancient_samples)

# run a simulation using the SLiM back end from a compiled slendr model object and return
# a tree-sequence output
ts <- slim(model, sequence_length = 1e5, recombination_rate = 0, samples = samples)

# automatic loading of a simulated output can be prevented by `load = FALSE`, which can be
# useful when a custom path to a tree-sequence output is given for later downstream analyses
output_file <- tempfile(fileext = ".trees")
slim(model, sequence_length = 1e5, recombination_rate = 0, samples = samples,
     output = output_file, load = FALSE)
# ... at a later stage:
ts <- ts_load(output_file, model)

ts
#> ╔═════════════════════════╗
#> ║TreeSequence             ║
#> ╠═══════════════╤═════════╣
#> ║Trees          │        1║
#> ╟───────────────┼─────────╢
#> ║Sequence Length│   100000║
#> ╟───────────────┼─────────╢
#> ║Time Units     │    ticks║
#> ╟───────────────┼─────────╢
#> ║Sample Nodes   │     1046║
#> ╟───────────────┼─────────╢
#> ║Total Size     │320.3 KiB║
#> ╚═══════════════╧═════════╝
#> ╔═══════════╤════╤═════════╤════════════╗
#> ║Table      │Rows│Size     │Has Metadata║
#> ╠═══════════╪════╪═════════╪════════════╣
#> ║Edges      │1916│ 59.9 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Individuals│1339│132.5 KiB│         Yes║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Migrations │   0│  8 Bytes│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Mutations  │   0│  1.2 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Nodes      │1917│ 71.8 KiB│         Yes║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Populations│   4│  2.5 KiB│         Yes║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Provenances│   1│ 34.6 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Sites      │   0│ 16 Bytes│          No║
#> ╚═══════════╧════╧═════════╧════════════╝
#>