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,
ts = NULL,
output_dir = NULL,
random_seed = NULL,
method = c("batch", "gui"),
verbose = FALSE,
load = TRUE,
run = TRUE,
slim_path = NULL,
burnin = 0,
max_attempts = 1,
spatial = !is.null(model$world),
coalescent_only = TRUE,
locations = 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.- ts
Path to the output tree-sequence file. If
NULL
(the default), tree sequence will be saved to a temporary file. IfFALSE
, no tree-sequence file will be generated (this is only useful for running customized slendr SLiM scripts). This argument cannot be set whenoutput_dir
is set.- output_dir
Path to a directory where various output files can be saved. This argument cannot be set when
output
is set. This is predominately intended to provide easier means to save outputs of slim simulations utilizing user-defined extension scripts. For tree-sequence only simulations, useoutput
to set the path to the output tree sequence file instead.- random_seed
Random seed (if
NULL
, a seed will be generated between 0 and the maximum integer number available)- method
How to run the script? ("gui" - open in SLiMgui, "batch" - run on the command line)
- 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.- 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.- slim_path
Path to the appropriate SLiM binary (this is useful if the
slim
binary is not on the$PATH
). Note that this argument must be specified if the function is being run on Windows.- 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 toTRUE
(the default) orFALSE
? See "retainCoalescentOnly" in the SLiM manual for more detail.- 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 withanimate_model
).
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.
Details
The arguments sequence_length
and recombination_rate
can be
omitted for slendr models utilizing customized initialization of genomic
architecture. In such cases, users may either provide hard-coded values
directly through SLiM's initializeGenomicElement()
and
initializeRecombinationRate()
functions or utilize slendr's
templating functionality provided by its substitute()
function.
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 <- normalizePath(tempfile(fileext = ".trees"), winslash = "/", mustWork = FALSE)
slim(model, sequence_length = 1e5, recombination_rate = 0, samples = samples,
ts = 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 │ 10046║
#> ╟───────────────┼───────╢
#> ║Total Size │2.6 MiB║
#> ╚═══════════════╧═══════╝
#> ╔═══════════╤═════╤═════════╤════════════╗
#> ║Table │Rows │Size │Has Metadata║
#> ╠═══════════╪═════╪═════════╪════════════╣
#> ║Edges │18361│573.8 KiB│ No║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Individuals│12858│ 1.2 MiB│ Yes║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Migrations │ 0│ 8 Bytes│ No║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Mutations │ 0│ 1.2 KiB│ No║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Nodes │18362│682.1 KiB│ Yes║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Populations│ 4│ 2.5 KiB│ Yes║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Provenances│ 1│ 42.0 KiB│ No║
#> ╟───────────┼─────┼─────────┼────────────╢
#> ║Sites │ 0│ 16 Bytes│ No║
#> ╚═══════════╧═════╧═════════╧════════════╝
#>