Run a slendr model in msprime — msprime • slendr

This function will execute a built-in msprime script and run a compiled slendr demographic model.

Usage

msprime(
  model,
  sequence_length,
  recombination_rate,
  samples = NULL,
  random_seed = NULL,
  verbose = FALSE,
  debug = FALSE,
  run = TRUE,
  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.
random_seed: Random seed (if NULL, a seed will be generated between 0 and the maximum integer number available)
verbose: Write the output log to the console (default FALSE)?
debug: Write msprime's debug log to the console (default FALSE)?
run: Should the msprime engine be run? If FALSE, the command line msprime command will be printed (and returned invisibly as a character vector) but not executed.
path: Path to the generated tree-sequence file. If NULL (the default), the tree sequence will not be saved to a file but will be returned as an in-memory object instead. If a path is given, it is interpreted as a path to a directory in which the function will save the tree sequence as a msprime.trees file and the function will return the path to the directory back. Note that this argument exists mostly to retain parity with the corresponding slim() function. In most circumstances, setting this argument is not necessary and users are better served by using the ts_save() function on the resulting tree-sequence object directly.

Value

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

(internally represented by the Python object tskit.trees.TreeSequence). If the path argument was set, it will return the path as a single-element character vector.

Examples

check_dependencies(python = 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, 10), list(eur, 100), list(chimp, 1))
ancient_samples <- schedule_sampling(model, times = c(40000, 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 msprime back end from a compiled slendr model object
ts <- msprime(model, sequence_length = 1e5, recombination_rate = 0, samples = samples)

# simulated tree-sequence object can be saved to a file using ts_save()...
output_file <- normalizePath(tempfile(fileext = ".trees"), winslash = "/", mustWork = FALSE)
ts_save(ts, output_file)
# ... and, at a later point, loaded by ts_load()
ts <- ts_load(output_file, model)

summary(ts)
#> ╔═══════════════════════════╗
#> ║TreeSequence               ║
#> ╠═══════════════╤═══════════╣
#> ║Trees          │          1║
#> ╟───────────────┼───────────╢
#> ║Sequence Length│     100000║
#> ╟───────────────┼───────────╢
#> ║Time Units     │generations║
#> ╟───────────────┼───────────╢
#> ║Sample Nodes   │        230║
#> ╟───────────────┼───────────╢
#> ║Total Size     │   39.2 KiB║
#> ╚═══════════════╧═══════════╝
#> ╔═══════════╤════╤═════════╤════════════╗
#> ║Table      │Rows│Size     │Has Metadata║
#> ╠═══════════╪════╪═════════╪════════════╣
#> ║Edges      │ 468│ 14.6 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Individuals│ 115│  3.2 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Migrations │   0│  8 Bytes│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Mutations  │   0│ 16 Bytes│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Nodes      │ 469│ 12.8 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Populations│   4│338 Bytes│         Yes║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Provenances│   1│  3.0 KiB│          No║
#> ╟───────────┼────┼─────────┼────────────╢
#> ║Sites      │   0│ 16 Bytes│          No║
#> ╚═══════════╧════╧═════════╧════════════╝
#>