treeswithintrees (twt
) is an R
package for the coalescent (reverse time) simulation of pathogen trees
within host transmission trees.
This illustrates a basic use case of the twt
package, where we
simulate the transmission (outer) tree and coalescent (inner) tree for
10 host individuals.
require(twt, quietly=TRUE)
#>
#> Attaching package: 'ggfree'
#> The following object is masked from 'package:ape':
#>
#> unroot
# locate the YAML file that specifies a compartmental SI model
path <- system.file('extdata', 'SI.yaml', package='twt')
model <- Model$new(yaml.load_file(path))
# run an outer tree simulation
outer <- sim.outer.tree(model)
# display the population trajectories
plot(outer, type='s')
# display the outer tree, dark lines = sampled hosts, grey = unsampled
plot(outer)
# run an inner tree simulation
inner <- sim.inner.tree(outer)
# display the inner tree annotated with transmission events (points)
plot(inner)
twt
is an R package. It was developed and tested with R version 3.6+,
so you may encounter problems if you try running this package on much
older versions. It depends on the following R packages:
twt
can be installed from the GitHub repository using the devtools
package in R:
if (!require(devtools)) {
# install devtools if not already present
install.packages('devtools')
}
devtools::install_github("PoonLab/twt")
For detailed instructions, please refer to INSTALL.md.
twt
is an R package for discrete event simulation of nested
host-pathogen trees using a mixture of forward- and reverse-time
methods. Forward-time simulation is used to simulate the stochastic
growth and decline of host populations starting from an index
case. Next, a transmission
tree is simulated backwards in time from a number of individual hosts
that have been sampled from the population(s) (potentially at different
points in time). We refer to this tree as the outer tree. When this
sample size is substantially smaller than the entire population,
simulating backwards is far more efficient because we can ignore a
large number of unrelated hosts. Finally, twt
simulates the inner
tree relating lineages that have been transmitted from host to another.
twt
is designed to be modular and customizable so that it can
accommodate a range of models at different levels of diversity, such as:
To be more versatile, twt
requires users to specify a model using the
YAML markup language.
For instructions on writing your own YAML file for a custom model, please refer to
our wiki documentation on this topic:
https://github.com/PoonLab/twt/wiki/Input-Specification
twt
attempts to accommodate a variety of nested models with a common set of basic
components: compartments and lineages. A
lineage is a sequence of individual pathogens descending from
an ancestor in the past. A compartment represents an
individual environment in which lineages are contained.
Compartments are grouped into Compartment
Types to make it more convenient to specify models and
for more efficient simulation. We assume that the compartments are
related through by a transmission or host tree, whose shape is
determined by the transmission rates among hosts. Lineages may also
migrate between compartments that are both hosts to other lineages.
Like many other simulation programs, twt uses a conventional Gillespie method to sample a sequence of discrete stochastic events over reverse time. If a host tree is not specified by the user, then the host/transmission tree is simulated while simulating the coalescence of the pathogen lineages within the hosts. Otherwise, the timing and direction of transmission events are parsed from the user tree and set as fixed events in the simulation.
Development of treeswithintrees was directly supported by a grant from the Government of Canada through Genome Canada and the Ontario Genomics Institute (OGI-131) and by the Canadian Institutes of Health Research (project grant PJT-155990).