Load a tree sequence file produced by a given model

This function loads a tree sequence file simulated from a given slendr model. Optionally, the tree sequence can be recapitated and simplified.

ts_load(
  source = NULL,
  file = NULL,
  recapitate = FALSE,
  simplify = FALSE,
  mutate = FALSE,
  recombination_rate = NULL,
  mutation_rate = NULL,
  Ne = NULL,
  random_seed = NULL,
  simplify_to = NULL,
  keep_input_roots = FALSE,
  migration_matrix = NULL
)

Arguments

source

Either a compiled slendr_model object encoding the definition of a slendr model used to produce a tree-sequence file (see the argument param), or a path to a tree-sequence file coming from a non-slendr simulation.

file

A path to the tree sequence file generated by the model specified by the argument source. If missing, an attempt will be made to search for a tree-sequence file in the model directory.

recapitate

Should the tree sequence be recapitated?

simplify

Should the tree sequence be simplified down to a set of sampled individuals (those explicitly recorded)?

mutate

Should the tree sequence be mutated?

recombination_rate, Ne

Arguments passed to ts_recapitate

mutation_rate

Mutation rate passed to ts_mutate

random_seed

Random seed passed to pyslim's recapitate method

simplify_to

A character vector of individual names. If NULL, all remembered individuals will be retained. Only used when simplify = TRUE.

keep_input_roots

Should the history ancestral to the MRCA of all samplbee retained in the tree sequence? Default is FALSE.

migration_matrix

Migration matrix used for coalescence of ancient lineages (passed to ts_recapitate)

Value

Tree sequence object of the class slendr_ts

Details

The loading, recapitation and simplification is performed using the Python module pyslim which serves as a link between tree sequences generated by SLiM and the tskit module for manipulation of tree sequence data. All of these steps have been modelled after the official pyslim tutorial and documentation available at: https://tskit.dev/pyslim/docs/latest/tutorial.html.

The recapitation and simplification steps can also be performed individually using the functions ts_recapitate and ts_simplify.

See also

ts_nodes for extracting useful information about individuals, nodes, coalescent times and geospatial locations of nodes on a map

Examples

if (FALSE) {
# load tree sequence from its default location in a model directory
ts <- ts_load(model)

# load tree sequence from another location
ts <- ts_load(model, file = "output.trees")

# load tree sequence and immediately simplify it only to sampled individuals
ts <- ts_load(model, simplify = TRUE)

# load tree sequence and simplify it to a subset of sampled individuals
ts_small <- ts_simplify(ts, simplify_to = c("CH_1", "NEA_1", "NEA_2",
                                            "AFR_1", "AFR_2", "EUR_20", "EUR_50"))

# load tree sequence, recapitate it and simplify it
ts <- ts_load(model, recapitate = TRUE, simplify = TRUE,
              recombination_rate = 1e-8, Ne = 10000)

# load tree sequence, recapitate it, simplify it and overlay neutral mutations
ts <- ts_load(model, recapitate = TRUE, simplify = TRUE, random_seed = 42,
              recombination_rate = 1e-8, Ne = 10000, mutation_rate = 1e-8)
}