Simulation

Overview

Simulation for treeswithintrees (twt) occurs in two stages unless the user provides a transmission (host) tree as an input. The first stage generates the transmission (outer) tree, and the second stage generates the pathogen (inner) tree given the outer tree.

First, twt simulates the transmission tree given the numbers of sampled and unsampled infected hosts and uninfected hosts. Accounting for the unsampled and uninfected hosts is necessary to determine the rate that sampled infections converge to transmission events going back in time. Note that the transmission tree may contain singleton nodes where a branch of the transmission history switches from a sampled host to its source unsampled host.

Second, twt fixes the transmission tree and simulates the pathogen tree within it, with set migration and coalescent rates and bottleneck sizes. Note that since we have fixed the transmission tree, it is no longer necessary to track unsampled and uninfected hosts.

In general, simulations proceed back in time and consist of fixed and random events. Random events are determined by the rate parameters associated with each potential event, and we assume exponential waiting times (constant rates) to the next random event. Fixed events are predetermined and override random events.

Simulating the outer tree

The fixed events for simulating the outer tree are the sampling times of the sampled hosts.

The random events are the convergence of hosts to transmission events. These may involve the transmission from either a sampled or an unsampled host to an uninfected (susceptible) host. Consequently, the overall rate that a sampled host coalesces with another host is proportional to:

• the intrinsic transmission rate of the CompartmentType of the source (beta).
• the number of sampled or unsampled infected individuals of the CompartmentType of the source
• the number of uninfected individuals of the CompartmentType of the recipient These are all parameters that have to be specified by the user.

Simulating the inner tree

Inputs

Input	Class	Value	Required
Sample times	Lineage	Numeric	Yes
Sample locations	Lineage	Compartment	Yes
Number of unsampled lineages	CompartmentType	Numeric	No?
Number of uninfected members	CompartmentType	Numeric	No?

Summary

The simulation comprises fixed and random events. Initially, the fixed events are the sampling times and locations of pathogen lineages, which must be provided by the user. If the user does not supply a transmission tree, then the tree needs to be generated by sampling transmission events. Rates of transmission between compartments of different types is determined by the total numbers of susceptible and (sampled/unsampled) infected members of the respective types, and the per-contact rate.

• Sampling lineages from a host/compartment
• A transmission event between hosts in the case of an input user tree.

Random events may consist of:

• The coalescence of lineages within a host/compartment
• A transmission event between hosts/compartments
• A migration event between hosts/compartments

Pseudocode

1. Generate CompartmentType, Compartment and Lineage objects from user inputs (YAML and/or Newick tree).
2. Initialize the list of fixed events.

• Add lineage sampling events from Lineage objects.
• If the user input includes a tree (host tree) then add transmission events, and go to step X.
• If the user input does not include a host tree, then transmission events must be simulated first before coalescence (and migration).

3. Simulate transmission events and fix them to the timeline of lineage sampled events. For each CompartmentType:

• Enumerate active compartments, including Unsampled Hosts (U) at time t=0.
• Enumerate active lineages of Infected (I), pairs of active lineages within hosts at time t=0.
• Enumerate number of Susceptibles (S) at time t=0.

4. Begin main loop

• Compute total event rate from the sum of all I and U compartments with the current number of S compartments
• Sample waiting time from exponential distribution of the negative total event rate, and update time t.
• Sample event type
• Update infection time or source of sampled compartments, and update the number of S, I, and U.
• Stop if I = 1, else continue loop.