treeswithintrees

treeswithintrees (twt) is an R package for the coalescent (reverse time) simulation of pathogen trees within host transmission trees.

Usage

This illustrates a basic workflow under a serial SIR model:

1. Simulate forward-time epidemic dynamics
2. Reconstruct the transmission (outer) tree
3. Clean and export the transmission tree

require(twt, quietly = TRUE)
#> 
#> Attaching package: 'ggfree'
#> The following object is masked from 'package:ape':
#> 
#>     unroot
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:ape':
#> 
#>     degree, edges, mst, ring
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union

# Load example YAML model from this repository
path <- file.path("examples", "SIR_serial.yaml")
stopifnot(file.exists(path))

settings <- yaml::read_yaml(path)

# Create model
mod <- Model$new(settings)
mod
#> twt ModelParameters:
#>    simTime :  10 
#>    beta :  1e-4 
#>    gamma :  0.1 
#>    psi :  0.05 
#> Compartments: S  I  I_samp  R

# Optional: visualize model structure
plot(mod)

# 1) Simulate epidemic dynamics (forward time)
elog <- sim.dynamics(mod)
#> Failed sample size requirements (attempt 1/3)
#> Failed sample size requirements (attempt 2/3)

# Plot population trajectories
counts <- get.counts(elog, mod)
plot(counts)

# 2) Reconstruct transmission tree (outer tree)
outer <- sim.outer.tree(mod, elog)

# Plot outer tree (raw)
plot(outer)

# Convert to phylo object
phy <- as.phylo(outer)

# Clean up single-child nodes (migration bookkeeping)
phy <- ape::collapse.singles(phy)

# Plot cleaned transmission tree
plot(phy)

# Export Newick tree
ape::write.tree(phy, file = "transmission_tree.nwk")

Description

twt performs discrete event simulation of nested host–pathogen trees using a combination of forward- and reverse-time methods.

Forward-time simulation models stochastic epidemic dynamics starting from an index case. All stochastic events are recorded in an event log.

Backward-time reconstruction extracts the ancestry of sampled infections to produce a transmission (outer) tree. This approach is computationally efficient because it traces only sampled lineages rather than the entire host population.

Inner trees (within-host coalescent)

Given an outer transmission tree, twt can simulate inner trees that describe within-host pathogen ancestry and coalescent dynamics along transmission histories.

Conceptually:

• Each infected host carries pathogen lineages.
• Transmission events move lineages between hosts, optionally through bottlenecks.
• Within each host, lineages coalesce backward in time at rates defined in the model (coalescent.rate).
• The resulting inner tree embeds within-host genealogies along the outer transmission tree.

The inner-tree interface is under active development, and function signatures or output formats may change across versions. Consult package documentation and vignettes for the most current usage.

twt supports:

• Compartmental epidemic models (e.g., SIR)
• Structured populations and migration
• Serial sampling
• Within-host coalescent simulation
• Gillespie-style discrete stochastic simulation

Models are specified using the YAML markup language.

Example Serial SIR Model

The example above uses examples/SIR_serial.yaml:

Parameters:
  simTime:  10.0
  beta:  1e-4
  gamma:  0.1
  psi:  0.05

Compartments:
  S:
    infected: false
    transmission:
      I: {I: beta*S*I}
    size: 9999
  I:
    infected: true
    migration:
      R: gamma*I
      I_samp: psi*I
    size: 1
    bottleneck.size: 1
    coalescent.rate: 0.01
  I_samp:
    infected: true
    size: 0
  R:
    infected: false
    size: 0

Sampling:
  mode: compartment
  targets:
    I_samp: 100

Installation

twt is developed and tested with R ≥ 3.6 and depends on:

• R6
• ape
• yaml
• ggfree

Install from GitHub using devtools:

if (!require(devtools)) {
  install.packages("devtools")
}
devtools::install_github("PoonLab/twt")

For detailed instructions, see INSTALL.md.

Funding

Development of treeswithintrees was supported by the Government of Canada through Genome Canada and the Ontario Genomics Institute (OGI-131), and by the Canadian Institutes of Health Research (PJT-155990).