---
title: Characterizing Infection States - Documentation
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}
This app allows you to explore a model that has several more compartments than the basic SIR model discussed in the _Introduction to ID_ app. Read about the model in the "Model" tab. Then do the tasks described in the "What to do" tab.


## The Model {#shinytab2}

### Model Overview

In the _Introduction to ID_ app, you explored a simple 3-compartment model, the basic SIR model. The model for this app has a few additional compartments, which allows us to include more details/realism into our model. We again focus on tracking individuals with regard to their infection/disease status. For this model, we track the following compartments/stages:

* **S** - susceptible, uninfected individuals 
* **P** - presymptomatic individuals who are infected and do not yet show symptoms. Those individuals can potentially be infectious.
* **A** - asymptomatic, infected individuals. Those individuals can potentially be infectious.
* **I** - individuals who are infected and show symptoms. Those individuals are likely infectious, but the model allows to adjust this, including no infectiousness.
* **R** - recovered/removed individuals. Those individuals have recovered and are immune. 
* **D** - individuals who have died due to the disease.

Of course, as with the basic SIR model, we could include further details by extending the number of compartments. In general, for each additional feature you want to track, the existing number of compartments needs to be replicated by the discrete categories you have. For gender, one would need to have 2x the compartments. Similarly if one wanted to stratify according to young/medium/old age, 3x the compartments are required, etc. 

In addition to specifying the *compartments* of a model, we need to specify the dynamics determining the changes for each compartment. In general, more compartments leads to more processes and more parameters governing these processes.

For this model, we include the following processes: 

* Susceptible individuals (S) can become infected by pre-symptomatic (P), asymptomatic (A) or symptomatic (I) hosts. The rates at which infections from the different types of infected individuals (P, A and I) occur are governed by 3 parameters, _b~P~_, _b~A~_, and _b~I~_. In other words, those b~i~ parameters determine how infectious an individual in stages P, A and I is.
* All infected individuals first enter the presymptomatic stage. They remain there for some time (determined by rate _g~P~_, the inverse of which is the average time spent in the presymptomatic stage). A fraction _f_ of presymptomatic hosts move into the asymptomatic category, and the rest become symptomatic infected hosts.
* Asymptomatic infected hosts recover after some time (specified by the rate _g~A~_). 
* Similarly, infected symptomatic hosts leave that stage at rate _g~I~_. For symptomatic hosts, two outcomes are possible, either recovery or death. The parameter _d_ determines the fraction of hosts that die.
* Recovered individuals are immune to reinfection. 



### Model Implementation
The flow diagram and the set of ordinary differential equations (ODE) which are used to implement this model are as follows:



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

$$\dot S = -S (b_P P + b_A A + b_I I)$$ 
$$\dot P = S (b_P P + b_A A + b_I I) - g_P P$$ 
$$\dot A = f g_P P - g_A A$$ 
$$\dot I = (1-f) g_P P - g_I I$$ 
$$\dot R = g_A A + (1-d) g_I I$$
$$\dot D = d g_I I$$





## 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: 
    * A population size, _S~0~_, of 1000, 1 initially infected presymptomatic host, _P~0~_, simulation duration _tmax_= 200 days.
    * Assume that only symptomatic individuals transmit, at rate _b~I~_ = 0.001.
    * Assume that the duration of the presymptomatic, asymptomatic and symptomatic periods are all 5 days long. (Hint: The parameters _g~P~_, _g~A~_, and _g~I~_ are the inverses of these periods.)
    * Assume that there are no asymptomatic infections, _f_=0, and nobody dies due to disease _d_=0.

* With parameters set to correspond to the scenario just described, run the simulation. You should end up with around 7 susceptibles left at the end of the simulation.
* Check the results with the assumptions for the model and make sure they agree. For instance you shouldn't get any deaths, and no asymptomatic infected.
* From the graph, contemplate how you would estimate the day at which the outbreak peaks. What's the problem? How would you solve it?
* Rerun the simulation, with the same values you just had. Does anything change? Why (not)?

### Task 2: 
* Assume now that half of the infected are asymptomatic. Don't change any other assumption.
* What do you expect to get for the number/fraction of S/I/R at the end of the outbreak and the time at which the outbreak peaks?
* Run another simulation, record the same values as above.
* Compare your expectations with the results. How do they agree/disagree? Does it make sense? Anything surprising happening?

### Task 3: 
* Now assume that the asymptomatics transmit at the same rate as the symptomatic. Change _b~A~_ accordingly. Leave everything else as before. How do you expect the results to change? (Try to make as precise/quantitative a prediction as you can).
* Run another simulation, compare your expectations with the results. How do they agree/disagree? Does it make sense? Anything surprising happening?

### Task 4: 
* Next, let's assume that half the symptomatic infected die. Change the corresponding parameter in the model to reflect this new assumption. Leave everything as in #3.
* How do you expect the results to change?
* Run another simulation, record the same values as above.
* Compare your expectations with the results. How do they agree/disagree? Does it make sense? Anything surprising happening?

### Task 5: 
* Set all transmission parameters to 0.0005, leave everything else as before. What do you expect will happen to the peak of _P_ and _I_ as well as the total fraction of population ever infected (i.e., _R_ + _D_ at the end of simulation), compared to the previous task?_
* Further explore how changes in the infectiousness of the different groups (_b~P~_, _b~A~_, _b~I~_) and the average time a person spends in each of those states (_g~P~_, _g~A~_, _g~I~_) affects the infection dynamics.
* Every time, think about what you expect to get, then run the simulation, compare your expectations with the results. Then make sense of it.

### Task 6: 
* Now assume that 90% of infections are asymptomatic. How do things change?  
* Further explore how changes in the fraction becoming asymptomatic and fraction dying does (or does not) affect the infection dynamics.
* Every time, think about what you expect to get, then run the simulation, compare your expectations with the results. Then make sense of it.



## 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.
* Some further information covering the concepts this app addresses can be found in [@keeling08, @vynnycky10, @kajita07, @milwid16].

### References


