---
title: Evolutionary Dynamics - Practice
output:
  html_document:
    theme: null
    highlight: null
    fig_retina: null
    fig_caption: true
    mathjax: default 
    keep_md: false
bibliography: references.bib
---


```{r, echo = FALSE}
#this code loads the settings file for the current app so we can automatically 
#list the functions in the further information section
currentrmdfile = knitr::current_input() 
currentappinfo = gsub("_documentation.Rmd" ,"_settings.R",currentrmdfile)
source(currentappinfo)
```


## Overview {#shinytab1}
For this module, we will explore a stochastic SIR-type model with 2 different pathogen strains, wild-type and a drug resistant mutant in the presence of drug treatment. Read about the model in the "Model" tab. Then do the tasks described in the "What to do" tab.


## The Model {#shinytab2}

### Model Overview

This model tracks susceptibles, wild-type infected untreated, wild-type infected treated, drug-resistant infected and recovered hosts. 
The following compartments are included:  

* __S__ - uninfected and susceptible individuals 
* __I~u~__ - individuals who are infected with the wild-type/drug sensitive strain and not on treatment.
* __I~t~__ - individuals who are infected with the wild-type/drug sensitive strain and on treatment.
* __I~r~__ - individuals who are infected with the drug-resistant strain. Treatment has no impact on those hosts.
* __R__ - recovered/removed individuals. Those individuals have recovered and are immune. 


The included processes/mechanisms are the following:

* Susceptible individuals (S) can become infected by untreated or treated hosts infected with the wild-type strain at rates _b~u~_ and _b~t~_. 
* A fraction _f_ of those hosts are assumed to receive treatment, while the remainder does not. 
* Small fractions, that is low values for _c~u~_ and _c~t~_  of wild-type infected untreated or treated hosts can generate resistant mutants and transmit those, leading to resistant infections.
* Susceptible individuals (S) can become infected by hosts infected with the resistant strain at rate _b~r~_. 
* All infected hosts recover at some rate _g~i~_, with _i=u,t,r_. 
* Recovered individuals are immune to reinfection. 



### Model Implementation
The flow diagram for the model implemented in this app is:



```{r BIdiagram,  fig.cap='Flow diagram for this model. ',  echo=FALSE}
knitr::include_graphics("../media/evolutionmodel.png")
```



Note that this model is _not_ an ordinary differential equation model. It is instead its stochastic equivalent.
We can specify the model by writing down every possible transition/event/reaction that can occur and their propensities (the propensity multiplied with the
time step gives the probability that a given event/transition occurs). For our model these are the following:

Event type        |  Transitions               |   Propensity      |
----------        |  -----------               |   ----------      |
S turn into I~u~  |  S => S-1,  I~u~ => I~u~+1 |   (1-f) * (b~u~ * (1-c~u~) * I~u~ + b~t~ * (1-c~t~) * I~t~) * S  |
S turn into I~t~  |  S => S-1,  I~t~ => I~t~+1 |   f * (b~u~ * (1-c~u~) * I~u~ + b~t~ * (1-c~t~) * I~t~) * S  |
S turn into I~r~  |  S => S-1,  I~r~ => I~r~+1 |   (b~u~ * c~u~ * I~u~ + b~t~ * c~t~ * I~t~ + b~r~ * I~r~) * S  |
Recovery of I~u~  |  I~u~ => I~u~-1, R => R+1  |   g~u~ * I~u~       |
Recovery of I~t~  |  I~t~ => I~t~-1, R => R+1  |   g~t~ * I~t~       |
Recovery of I~r~  |  I~r~ => I~r~-1, R => R+1  |   g~r~ * I~r~       |




## What to do {#shinytab3}


**The tasks below are described in a way that assumes everything is in units of DAYS (rate parameters, therefore, have units of inverse days). If any quantity is not given in those units, you need to convert it first (e.g. if it says a week, you need to convert it to 7 days).**
      
### Task 1 

Set the model parameters such that it corresponds to the following setting: 

* Susceptible _S~0~_ = 500, and initially untreated infected host _I~u0~_ = 1. No other infected hosts _I~t0~_ = 0 and _I~r0~_ = 0.
* Set simulation duration, _tmax_, to approximately half a year.
* Assume that untreated individuals transmit at _b~u~_ = 0.001, treated at _b~t~_ = 0.0005, and resistant at _b~r~_ = 0.0008.     
* Assume that the duration of the infectious period is 5 days for untreated, 4 days for treated and 5 days for resistant (for those individuals, treatment has no effect). Set the rates _g~i~_ accordingly.
* Set the number of simulations to 20.
* Assume nobody receives treatment and no resistance is generated (_f = c~u~ = c~t~ = 0_).
    
With parameters set to correspond to the scenario just described, run the simulation. You should see some simulations with outbreaks and some without. For those _with outbreaks_, you should have around 10-100 susceptible left at the end.

### Task 2 
* With everything as before, set the initial number of untreated infected hosts to 10. 
* Run simulations. You should pretty much always get outbreaks. Record the average number of susceptibles left.
* Why do you see almost always outbreaks for this setting and fewer outbreaks/more extinctions for task 1?


### Task 3 
* With the same settings as _Task 2_ turn on treatment ( _f_ > 0 ). 
* Set number of simulations to 50 (the simulations might take a few seconds to run).
* Run the simulation with fraction receiving treatment, _f_, at 0, 0.25, 0.5, 0.75 and 1.
* Observe what happens to the number susceptibles left at the end of the outbreak as you change treatment levels. Draw conclusions about the usefulness of treatment.

### Task 4 
* Now allow resistance to be generated during treatment (_c~t~_ > 0). Set _c~t~ = 0.2_ for the fraction of resistant generation from treatment.
* Run the simulation for the treatment levels specified in the previous task.
* Observe what happens to the number susceptibles left at the end of the outbreak as you change treatment levels. Draw conclusions about the usefulness of treatment.
* In your head or on a piece of paper, sketch out the relationship between treatment level and the number of susceptibles left at the end in the absence and presence of resistance generation (_c~t~_ = 0 and _c~t~_ > 0). What do you conclude from that?


### Task 5 
* Set the rate of transmission for resistant hosts to _b~r~ = 0.001_. Keep untreated hosts and treated host values as before.
* Set resistance generation during treatment to _c~t~ = 0.3_. 
* Keep everything else as previously.
* Contemplate what these changes mean biologically, and what you should expect from the simulations.
* Run the model for each of the 5 treatment levels specified above and record the average number of susceptibles left at the end. 
* Again, sketch out the relationship between treatment level and the number of susceptibles left at the end and compare to what you found in tasks 3 and 4. What do you conclude from that?


### Task 6 
Keep exploring. For instance, try the following:

* Turn on resistance generation for both treated, _c~t~_, and untreated, _c~u~_. 
* Explore how population size, _S~0~_, the fraction of resistance generation ( _c~t~_ or _c~u~_ ) and fitness of the different strains ( _b~t~_ or _b~u~_ or _b~r~_ ) affect outcomes.
* If you want to explore the relation between treatment level and outbreak size (tasks 3-5) in more detail, you could access the underlying simulation directly and write a bit of R code to loop over treatment values following the "Level 2" example described in the DSAIDE tutorial.

## Further Information {#shinytab4}

* This app (and all others) are structured such that the Shiny part (the graphical interface you see and the server-side function that goes with it) calls an underlying R script (or several) which runs the simulation for the model of interest and returns the results.
* For this app, the underlying function(s) running the simulation are called ``r appsettings$simfunction``. You can call them directly, without going through the shiny app. Use the `help()` command for more information on how to use the functions directly. If you go that route, you need to use the results returned from this function and produce useful output (such as a plot) yourself. 
* You can also download all simulator functions and modify them for your own purposes.  Of course to modify these functions, you'll need to do some coding.
* For examples on using the simulators directly and how to modify them, read the package vignette by typing `vignette('DSAIDE')` into the R console.
* The model is a simpler version of a previously published model in [@handel09a].


### References