Skip to content

Input Specification

Jump to bottom
rouxcil edited this page Feb 12, 2020 · 15 revisions

Overview

A simulation is configured with a YAML specification file. If there is no input tree, then a host tree is simulated from this configuration before the simulation of lineage coalescence. If an input tree is provided by the user, then the program will skip directly to the lineage simulation stage. The YAML file can comprise of the following components:

Initial Conditions

The InitialConditions field of the YAML file is where we specify the starting conditions and time scale of the simulation.

Specification:

  • originTime - the number of simulation time units between the origin of this LineageType and the most recent sample (zero in reverse time).
  • size - the number of individuals per CompartmentType at originTime
    • CompartmentType name: value (positive integer)
  • indexType - CompartmentType of index case (i.e., first infected individual Compartment). Note this single individual is deducted from the corresponding size value at the start of simulation.

Example:

InitialConditions:
  originTime: 10.0  # duration of simulation
  size:
    host1: 50
    host2: 50
  indexType: host1

Compartment Type

A compartment represents a host individual that can carry one or more pathogen lineages. A CompartmentType is a class of compartments that is defined by specific rate parameter values, such as a coalescence rate. In a strict sense, it is a convenience class for replicating parameter values across a number of Compartment objects.

Specification:

  • name - a unique label for the CompartmentType
    • branching.rates - in reverse time, these are the rates that a Lineage moves from a recipient Compartment (where a new infection was established) of any other Type to a source Compartment of this Type. Specified as an expression that can be appended to the R command list.
      • time - in reverse time, this is used when time-heterogeneous rate are required for the CompartmentType. Specified as an expression that can be appended to the R command list.
    • migration.rates - in reverse time, these are the rates that a Lineage moves from a recipient Compartment (already infected) of any other Type to a source Compartment of this Type. Specified as an expression that can be appended to the R command list.
    • bottleneck.size - a positive integer value that indicates the maximum number of Lineages that can be transmitted from a source to recipient Compartment. In reverse (coalescent) time, this limits the number of Lineages that can be followed into the source Compartment.
    • coalescent.rate - the rate that Lineages in the same Compartment of this Type coalesce to a common ancestor
    • wait.time.distr - a probability distribution of waiting times between the infection time and first Lineage sampling time for a Compartment of this Type. We allow the user to specify a distribution instead of just a rate parameter, which implicitly assumes an exponential waiting time distribution; for example,
      • dist - when prefixed with d, specifies a R function for the density of a probability distribution function, e.g., dexp.
      • hyperparameters
        • a named list of hyperparameter values
    • popn.growth.dynamics - (optional) a piecewise linear model of Lineage population size within a Compartment of this Type, parameterized in forward time (from time of infection). This is provided for the user to be able to have varying coalescent rates (population size) within a compartment over time. If not specified (NULL value) then twt will use the coalescent.rate to draw waiting times to coalescent events.
      • piece1 - an arbitrary label for the first linear piece
        • startTime - lower time bound of this piece
        • startPopn - population size at lower (less recent) time
        • endTime - upper time bound of this piece
        • endPopn - population size at upper (more recent) time
        • slope - alternate parameterization, change in population size per unit time
        • intercept - alternate parameterization, population size at time zero

Example:

CompartmentTypes:
  'blood':                                        # blood no transmission to blood - transmission is to uninfected cell
    branching.rates: (blood=0.0, tissue=0.2)     # infection of a cell (transmission rate from blood -> cell)
    migration.rates: (blood=0.0, tissue=0.0)   
    coalescent.rate: 1.5                        # default rate to generate coalescent waiting times (no given death.rate.distr and/or popn.growth.dynamics) of lineages within this compartment
    bottleneck.size: 1                            # assume a single virus enters an uninfected cell
    death.rate.distr:                             # if this is not given, not allowed to use linear population growth dynamics to calculate coalescent times
    wait.time.distr:                              # distribution of waiting time between infection time and first sampling time of a Compartment
      distr: 'exp'
      hyperparameters:
        - rate: 20
    popn.growth.dynamics:                         # no replication in blood 
      piece1:
        - startTime: 0
        - startPopn: 1
        - endTime: 20
        - endPopn: 300
      piece2:
        - startTime: 20
        - startPopn: 300

  'tissue':
    branching.rates: 
      20: (blood=0.0, tissue=0.02)     # infection of a cell from simulation time 20 to 10 (transmission rate from cell -> cell)
      10: (blood=0.0, tissue=0.002)      # infection of a cell from simulation time 10 to 0 (transmission rate from cell -> cell)

Compartments

A Compartment is an individual instance of a CompartmentType. A Lineage object representing an individual pathogen is contained within one and only one Compartment at any time during the simulation, although it may switch to another Compartment due to transmission or migration.

Important: This field is only used to describe Compartments from which at least one Lineage has been sampled. There can be any number of unsampled Compartments that will be induced from the starting conditions specified in the OriginTime field.

Specification:

  • type - must match one of the CompartmentType labels
    • source - (optional) a reference to the label of another Compartment; used to manually specify a transmission history
    • branching.time - (optional) the time of the transmission event in reverse (coalescent) time; used to manually specify a transmission history.
    • replicates - (optional) a convenience method for quickly copying identical Compartments for this Type. Otherwise defaults to 1.

Examples

This quickly populates the host CompartmentType with 10 identical Compartments.

Compartments:
  'I':
    type: host
    replicates: 10

This manually specifies a "transmission chain" from A to B to C:

Compartments:
  'A':
    type: host
    source: NA
    branching.time: NA
    replicates: 1
  'B':
    type: host
    source: A
    branching.time: 3.0
    replicates: 1
  'C': 
    type: host
    source: B
    branching.time: 1.0 
    replicates: 1

LineageTypes

A LineageType is a class of lineages that are defined by specific rate parameter values. This is going to be an experimental class. This would allow sets of lineages to have a greater or lesser probability of being passed through a transmission bottleneck, or skew the probability of being coalesced to the next common ancestor (selection within hosts).

Lineages

A Lineage represents an individual pathogen lineage that may be transmitted or migrate between different Compartments. A lineage has a sampling time that is measured in reverse time relative to the most recent lineage sample. Note that we are only simulating sampled Lineages in reverse time - there may be any number of unsampled Lineages that we will ignore.

Specification

  • label - a unique label for a Lineage
    • type - reference to a LineageType (not yet implemented)
    • sampling.time - the time that the Lineage was sampled, in reverse (coalescent) time. The user can also specify different sampling times for replicate Lineages with the following format:
    • location - a reference to the unique label of a Compartment where the Lineage was sampled. Note that if replicate Compartments were specified, then the same base label should be used here (e.g., "virus" and not "virus_2"). The replicate argument will assign the same number of replicate Lineages to each replicate Compartment that was generated. For example, if we set replicates: 10 for Compartment host, and replicates: 3 for Lineage virus, then there will be a total of 30 Lineages (3 for every Compartment).
    • replicates - a convenient method to copy multiple Lineage objects with the exact same values - twt will generate a unique label for each replicate under the following format: <location>__<label>_<replicate #>

Examples

The following creates a total of 5 Lineage objects, of which 3 were sampled from host A with the unique labels A__1_1, A__1_2 and A__1_3:

Lineages:
  '1':
    type: virus
    sampling.time: (0.0, 2.0, 3.0)
    location: A
    replicates: 3
  '2':
    type: virus
    sampling.time: 0.0
    location: B
    replicates: 1
  '3':
    type: virus
    sampling.time: 0.0
    location: C
    replicates: 1
Clone this wiki locally