Skip to content

Transmission

Jump to bottom
Art Poon edited this page Apr 10, 2018 · 7 revisions

A transmission event comprises the following information:

  • time of occurrence (in coalescent time)
  • source Compartment
  • recipient Compartment
  • bottleneck size

A transmission event may involve the transmission from either a sampled or an unsampled host to an uninfected (susceptible) host. As a result, every transmission increments the number of uninfected hosts by one. 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.

For now, we assume that the total population size of hosts (N) is constant over time. Suppose there is only one CompartmentType. At time 0 (the present), the number of sampled infected hosts be I, unsampled infected hosts be I', and uninfected hosts be S. N=I+I'+S for all times t. Let's say we've sampled two infected hosts at t=0 (I=2) and that there are a total of N=100 individuals in the population.

Transmission Events

Before simulating coalescent and migration events for the inner tree, Lineage sampling times and transmission events must be fixed onto a coalescent timeline. This is deemed as the outer tree. There are three cases that we can allow for transmission events to be fixed:

  1. User provides a host transmission tree in the form of a Newick string
  2. User manually inputs a host transmission tree into YAML specification format under the Compartments header
  3. No host tree is provided, and transmission events need to be generated

All 3 cases will result in generating an EventLogger object as a record of all the fixed events.

Case 1: Newick String Host Transmission Tree

The host transmission tree provided by the user must be in Newick string format with node labels.

Case 2: Manual Input Host Transmission Tree

Host transmission tree is interpreted from the input YAML file provided by the user following the guidelines under Compartments. Each individually specified Compartment must include the name of the source of transmission, as well as the branching.time for when the transmission occurred.

Case 3: Generating Transmission Events

For this case, we have to simulate transmission events and fix them to the timeline of Lineage sampled events.

Pseudocode

  1. For each Compartment Type, enumerate I, I', and S at time t=0.
  2. Record the oldest Lineage sampling time (coalescent time) for each i Compartment.
  3. Create a dictionary of all possible Compartment Types that can be a source of infection for a given recipient Compartment's Type.
    • this includes the Types across all u Compartments
    • this removes source -> recipient pairs with an intrinsic branching rate of 0
  4. Starting at time t=0, begin main loop:
    1. Draw all possible recipients that have their oldest Lineage sampling time earlier than or equal to the current time t.
    2. Retrieve recipients' source transmission types from dictionary of all possible source Compartment Types for each qualified sampled recipient.
    3. Calculate individual transmission rates among all source recipient pairings of Compartment Types.
      • individual transmission rate = intrinsic transmission rate x (Is + I's) x (Sr + 1)
    4. Calculate the total rate of ANY transmission event occurring.
      • this is the weighted sum of the individual rates in the dictionary.
    5. Sample waiting time from the negative exponential distribution of the total rate.
    6. Update the current time by adding the waiting time, and check if the current time exceeds any max Lineage sampling time within the i Compartments that previously did not qualify as recipients. If so, re-filter the population of possible recipients to include the newly qualified i Compartment(s).
    7. Else, determine the source and recipient by relative transmission rate sums by Type. Sample individual recipient and source Compartments within Types, uniformly distributed.
    8. If the source is a u Compartment, it now will hold a connection to a sampled Lineage that we care about. This u Compartment is temporarily promoted to an i Compartment until it becomes a recipient from another source infection.
    9. The counts of I, I', and S are updated, with (I+I') decreasing by one and S increasing by one at each transmission event as we go back in time.

Sampled infected hosts/cells

Sampled infected hosts/cells (i) are Compartments that contain Lineages that have been sampled.
In terms of the outer-tree simulation, i Compartments are separated further into sampled and not-yet-sampled categories as we start at time t=0 and simulate the transmission histories back in time. At each iteration of the outer-tree simulation, i Compartments are determined to be sampled in relation to the current time of the iteration. If a Compartment's oldest Lineage sample was taken at the iteration's current time or earlier, it is then considered as a sampled and qualifying recipient Compartment for that iteration. This is to ensure that Compartments do not receive a transmission in forward time after they have already retrieved an infected Lineage sample from that Compartment.

Unsampled infected hosts/cells

Unsampled infected hosts/cells (u) are individuals that do not contain any sampled Lineages, but may still contribute to transmission events in a transmission tree either as the recipient or the source of an infection. The number of u for each Compartment Type (I') decreases as we go back in time as these unsampled infections transition into susceptible (s) individuals.

The resolution of u Compartments earlier in coalescent time than the sampled infected (i) Compartment containing the most recently sampled Lineage is excluded from the simulation because they do not hold any sampled lineages that are being tracked. These u Compartments are not part of the I' inputted by the user. In the current implementation, u Compartments are able to be recipients in a transmission event, but only after first being a source to an I Compartment.

Similarly, the resolution of u Compartments later in coalescent time than the transmission event involving the final i Compartment provides no information, so these u Compartments are excluded from the transmission tree.

Susceptible uninfected hosts/cells

Uninfected hosts/cells are susceptible (s) individuals. The number of s for each Compartment Type (S) increases as we follow the transmission tree back in time.

Clone this wiki locally