Major refactoring: actual compartmental models

[ArtPoon]

The way that twt is currently set up, it can only simulate S->I dynamics because the conversion of susceptible to infected individuals is hard-coded into each CompartmentType/Deme. This was not a great design decision on my part. I am currently revising the object classes in the renaming branch as follows:

• Compartment restores the conventional meaning of the term - it represents a variable in a dynamic model, i.e., a population of individuals sharing attributes in common such as transmission rates. A Compartment can now represent a population of susceptible (uninfected) individuals.
• Host is an individual member of a Compartment population that contains one or more sampled Pathogen lineages. We want to relate Hosts with an outer tree (i.e., transmission tree/graph). It should be possible for a Host to be infected more than once.
• Pathogen is a sampled lineage that we want to relate by the inner tree.

[ArtPoon]

In refactoring the Model class, I found it useful to write the YAML file in a format that I would want to use to specify a model, rather than the other way around:

Parameters:
  originTime:  10.0  # simulation time units before most recent sample date
  beta1:  0.0001  
  beta2:  0.0003  # higher transmission rate
  hom:  3.0  # homophily 
  gamma:  0.001  # clearance rate
  omega:  0.01  # loss of immunity
Compartments:
  'S1':
    rates:
      I1: (beta1*hom*I1 + beta2*I2)*S1
    size: 999
  'I1':
    rates:
      R1: gamma*I1
    size: 1
    bottleneck.size: 1  # define only for compartments that carry Pathogens
    coalescent.rate: 0.01
  'R1':
    rates:
      S1: omega*R1
    size: 0
  'S2':
    rates:
      I2: (beta1*I1 + beta2*hom*I2)*S2
    size: 999
  'I2':
    rates:
      R2: gamma*I2
    size: 1
    bottleneck.size: 1+rpois(1,0.5)  # an expression for random outcomes
    coalescent.rate: 0.02
  'R2':
    rates:
      S2: omega*R2
    size: 0
Pathogens:
  # how to specify this?

[ArtPoon]

indexType was used to specify which CompartmentType would hold the "first" infection:

twt/R/simOuterTree.R

Lines 412 to 416 in d3b6557

	# initialize populations at origin (named vectors)
	susceptible <- unlist(init.conds$size)
	infected <- sapply(susceptible, function(x) 0)
	susceptible[init.conds$indexType] <- susceptible[init.conds$indexType] - 1
	infected[init.conds$indexType] <- 1

This is now accomplished by setting the initial size for one of the infected Compartments.

[ArtPoon]

I think we can drop specification of Hosts, i.e., infected individuals carrying one or more sampled Pathogen lineages. It may be possible to induce Host objects by specifying Pathogens, because these are direct samples.

The tricky part is how to make it convenient for the user to specify a large number of sampled Pathogen lineages across a number of hosts. Some potential use cases:

• User wants to specify a birth-death model with a constant sampling rate, one Pathogen lineage per sampled host. In this case the user would need to specify sampling rates for each relevant compartment. We would need to incorporate this into the forward-time simulation of population dynamics. Also, would we have a target number of samples as a stopping condition for the forward simulation?
• In the current implementation of twt, the user can specify multiple lineages sampled from the same host at different points in time. If there is a substantial number of hosts like this, then fully specifying the simulation model is kind of a pain. I also can't think of a good use case for this right now. I think for now we will keep it to one Pathogen lineage per host. This support declaring Host, not Pathogen.
• Furthermore, I think the user will seldom want to manually specify a wide range of sampling dates. We could give them the option of setting a vector of sampling times for each compartment, or an R expression for drawing those times from some distribution.

[ArtPoon]

For now let's prioritize implementing the first use case. Probably the simplest way to implement this would be like REMASTER, i.e., add Compartments for sampled infected individuals, and make the target sample sizes a stopping criterion. This would mean adding something like this to the YAML:

Parameters:
  originTime:  10.0  # simulation time units before most recent sample date
  beta1:  0.0001  # transmission rate
  gamma:  0.001  # clearance rate
  psi:  0.001  # sampling rate
  omega:  0.01  # loss of immunity
Compartments:
  'S':
    rates:
      I: beta*I*S
    size: 999  # initial
  'I':
    rates:
      R: gamma*I
      I_samp: 
    size: 1  # index case!
    bottleneck.size: 1  # define only for compartments that carry Pathogens
    coalescent.rate: 0.01
  'I_samp':
    rates:  # can we set this to nothing? if not then this has to be an optional key
    size: 0
  'R':
    rates:
      S: omega*R  # revert to susceptible
    size: 0
sampling:
  mode: compartment  # indicates that one or more Compartments represent a sampled state (could also call this 'serial')
  targets:
    I_samp: 100  # if compartment reaches this target size then stop forward-time simulation