Load a tree sequence file produced by a given model — ts_load • slendr

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

Usage

ts_load(
  file,
  model = 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,
  demography = NULL
)

Arguments

file: A path to the tree-sequence file (either originating from a slendr model or a standard non-slendr tree sequence).
model: Optional slendr_model object which produced the tree-sequence file. Used for adding various annotation data and metadata to the standard tskit tree-sequence object.
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 samples be retained in the tree sequence? Default is FALSE.
demography: Ancestral demography to be passed internally to msprime.sim_ancestry() (see msprime's documentation for mode detail)

Value

Tree-sequence object of the class slendr_ts, which serves as an interface point for the Python module tskit using slendr functions with the ts_ prefix.

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

check_dependencies(python = TRUE) # make sure dependencies are present

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

# load an example model with an already simulated tree sequence
slendr_ts <- system.file("extdata/models/introgression.trees", package = "slendr")
model <- read_model(path = system.file("extdata/models/introgression", package = "slendr"))

# load tree sequence generated by a given model
ts <- ts_load(slendr_ts, model)

# even tree sequences generated by non-slendr models can be
msprime_ts <- system.file("extdata/models/msprime.trees", package = "slendr")
ts <- ts_load(msprime_ts)

# load tree sequence and immediately simplify it only to sampled individuals
# (note that the example tree sequence is already simplified so this operation
# does not do anything in this case)
ts <- ts_load(slendr_ts, model = 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_1", "EUR_2"))

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

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

ts
#> ╔════════════════════════╗
#> ║TreeSequence            ║
#> ╠═══════════════╤════════╣
#> ║Trees          │      24║
#> ╟───────────────┼────────╢
#> ║Sequence Length│  500000║
#> ╟───────────────┼────────╢
#> ║Time Units     │   ticks║
#> ╟───────────────┼────────╢
#> ║Sample Nodes   │      26║
#> ╟───────────────┼────────╢
#> ║Total Size     │58.6 KiB║
#> ╚═══════════════╧════════╝
#> ╔═══════════╤════╤════════╤════════════╗
#> ║Table      │Rows│Size    │Has Metadata║
#> ╠═══════════╪════╪════════╪════════════╣
#> ║Edges      │ 133│ 4.2 KiB│          No║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Individuals│  55│ 7.2 KiB│         Yes║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Migrations │   0│ 8 Bytes│          No║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Mutations  │   0│ 1.2 KiB│          No║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Nodes      │  68│ 3.2 KiB│         Yes║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Populations│   5│ 2.6 KiB│         Yes║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Provenances│   4│36.6 KiB│          No║
#> ╟───────────┼────┼────────┼────────────╢
#> ║Sites      │   0│16 Bytes│          No║
#> ╚═══════════╧════╧════════╧════════════╝
#>