---
title: Basic Virus Model
output:
  html_document:
    theme: null
    highlight: null
    fig_retina: null
    fig_caption: true
    mathjax: default 
    keep_md: false
bibliography: references.bib
---

```{r, include = FALSE}
#*************************************
#general setup to define package and get path locations
#all paths are inside the package and retrieved with system.file
packagename = "DSAIRM"
helperdir = "helperfunctions"
mbmodeldir = "mbmodels"
figuredir = "media"
appdocdir = "appinformation" 
#*************************************
#Note: for this to process/knit, several helper functions need to be available (sourced) first
#those are in the inst/helperfunctions folder
#Note: in general, the "processing-script.R" in the docsfordevelopers should be used to produce the html docs
#manual knitting of each doc only during development/testing
#*************************************
files_to_source = list.files(system.file(helperdir,package = packagename),full.names=TRUE)
sapply(files_to_source, source) #sourcing needs to happen inside each Rmd file since knitr starts a new environment
#load the settings file for the current app 
#so we can automatically include figure, list the functions in the further information section
#and use other information specific to the current app for the task table generation
currentrmdfile = knitr::current_input() 
appsettings = get_settings(currentrmdfile,appdocdir,packagename)
```



## Overview {#shinytab1}
This app allows exploration of a basic virus infection model, with compartments for uninfected cells, infected cells and (free) virus. 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 consists of 3 compartments and can capture some of the basic dynamics of viral infections. In this model, we track the following entities, by assigning each to a compartment:

* **U** - uninfected cells 
* **I** - infected cells
* **V** - (free) virus


In addition to specifying the *compartments* of a model, we need to specify the dynamics determining the changes for each compartment. Broadly speaking, there are processes that increase the numbers in a given compartment/stage, and processes that lead to a reduction. Those processes are sometimes called in-flows and out-flows. 

For our system, we specify the following processes/flows: 

1. Uninfected cells are produced at some rate _n_ and naturally die at some rate _d~U~_.
2. Virus infects cells at rate _b_.
3. Infected cells produce new virus at rate _p_ and die at rate _d~I~_.
4. Free virus is removed at rate _d~V~_ or goes on to infect further uninfected cells. 
5. To allow conversion from infectious virus units in the model to some experimental units (e.g. plaque forming units), an additional conversion factor, _g_, is included in the model.

### Model Diagram
The diagram illustrating this compartmental model is shown in the figure.

```{r virusdiagram, fig.cap='',  echo=FALSE, out.width = "70%"}
knitr::include_graphics("../media/virusdiagram.png")
```

### Model Equations
Implementing this model as a continuous-time, deterministic model leads to the following set of ordinary differential equations. 

$$\dot U = n - d_U U - bUV$$ 
$$\dot I = bUV - d_I I$$
$$\dot V = pI - d_V V - gb UV$$




## 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 initial conditions to 10^5^ uninfected cells, no infected cells and 10 virus particles.
* We start by considering an acute viral infection. We make the assumption that on the timescale of an acute infection (several days), the processes of natural, uninfected cell turnover are so slow that they can be ignored. Set values for the uninfected cell birth and death rates to reflect this assumption.
* Assume that infected cells have an average life-span of 1 day, and virus has a life-span of 6 hours (remember that the inverse of the lifespan is the rate of death, and make sure you convert to the right units).
* Set that the virus production by an infected cell is 100 virions per day and that the rate at which new cells become infected is 10^-6^.
* Assume there is no need to do any unit adjustment/conversion (i.e. the value of that parameter is 1).
* Run the simulation for 50 days, produce plots with and without log-scales.  

You should get a single, acute infection with virus and infected cells rising and declining. At the end you should be left with around 11068 uninfected cells (and no infected cells and virus).


### Task 2 
* Slowly increase the virus death rate. Contemplate what you expect to see, then run the simulation to compare. Keep increasing until you get essentially no more infection. You will have to adjust the simulation time for that, too.

### Task 3 
* Set the virus death rate back to what it was in task 1. Now change the virus production rate until you reach the value at which the virus does not cause any infection.
* You can also repeat this process for the infected cell death rate and the infection rate.

### Task 4 
A well-studied quantity in infectious disease epidemiology is the basic reproductive number (*R~0~*), which determines if a pathogen can cause an outbreak at the population level. An equivalent *R~0~* can be defined for a within-host model to determine if you get an infection or not. For this virus model (with no births and deaths of uninfected cells, i.e. _n=d~U~=0_), *R~0~* = *bpU~0~*/(*d~V~ d~I~*). 

* Plug numbers for the parameters from your simulations in task 2 and 3 into the equation for *R~0~* to figure out what value *R~0~* needs to be for there (not) to be an infection. Figure out the threshold value for *R~0~* at which you go from no infection to having an infection.

To learn more about *R~0~*, see e.g. [@heffernan05a; @roberts07; @beauchemin08]. Some of those references describe *R~0~* in the context of infectious disease epidemiology, but if you replace humans/hosts with cells, the same concepts apply at the within-host level.

### Task 5 
Without birth/production of new uninfected cells, the most you can get is a single acute infection (or no infection at all). To convince yourself that it is impossible to produce a chronic infection, play around with the model, try all kinds of parameter values (but keep _n=0_).

Production of new uninfected cells is an example of _resource replenishment_. This is needed to allow a steady state/chronic infection, and this concept applies in general (e.g. on the population level, new susceptible individuals need to be created either through birth or through losing immunity). 

Let's explore the model with uninfected cell production, i.e. resource replenishment. 

### Task 6
* We start by focusing on the dynamics of uninfected cells only. To that end, set the number of initial infected cells and virus particles to 0. Keep the number of uninfected cells at 10^5^, set birth and death of uninfected cells to zero.
* Run the simulation. Nothing should happen, uninfected cells should stay at their starting value.
* Now play around with birth rate and death rate of uninfected cells and see how that affects the dynamics.
* The number of uninfected cells once the system has settled down only depends on the birth and death rate, not the starting conditions. Confirm this by trying different values for *U~0~* while keeping birth and death rate at some fixed values.
* One can write down an equation for uninfected cells at steady state as a function of birth and death rate, i.e. *U~s~* = f(*n*,*d~U~*), where f() is the mathematical symbol for "some function". In this case, it is a very simple function. Based on your explorations of different values for birth and death rate and the resulting values of *U~s~*, figure out this equation.
* To test your equation, set birth rate to 20000, set initial condition for uninfected cells to 10^5^ and find the value for the death rate that keeps the number of uninfected cells unchanged at 10^5^.

### Task 7 
Now we'll explore an infection in the presence of uninfected cell birth and death. 

* Set all parameters as in task 1. 
* Set birth and death as described at the end of the previous task.
* Run the simulation. You should get an initial large increase in virus load, which then settles down and reaches a steady state of around 295000. Similarly, the variables _U_ and _I_ settle down to steady state values.

### Task 8 
* Investigate how the steady state values for _U_, _I_ and _V_ depend on the parameters _b_, _p_, _d~V~_ and _d~I~_. You might need to increase the simulation time to ensure the system has settled down to its steady state.
* Once the system has settled down, there are no more changes in the numbers for each compartment. Mathematically, that means that the left side of the differential equations becomes 0, and they turn into the following algebraic equations:
_0 = n - d~U~ U - bUV_, _0 = bUV - d~I~_, _0 = pI - d~V~ V - gb UV_. One can solve those equations for each of the compartments to get a mathematical expression of what _U_, _I_ and _V_ are at steady state. If your algebra is not too rusty, try to do this. You should find that _U~s~ = d~I~ d~V~/(b(p - d~I~ g))_ and similar (slightly bigger) equations for _I~s~_ and _V~s~_ (the subscript _s_ denotes that these are the steady-state values of the variables).

If you haven't done algebra in a while, or if you find doing math by hand too tedious, modern computer software often helps. R cannot solve such equations analytically, but other software packages can. The main ones used for analytic math are Mathematica and Maple. Both are powerful and expensive. If you only need to solve simple equations occasionally, there is [Maxima](http://maxima.sourceforge.net/), which is free. You can download it and enter the equations above and it will solve it for you. Note that once you go beyond 4-5 variables, the steady state equations are usually very complicated, often so much so that they are not useful anymore. And once you go beyond 5 variables, in most cases your software will struggle to give you something meaningful. Fortunately, while it is less quick and elegant, you can always simulate your model and see what (if any) steady state it reaches.


* Once you found the steady state equations, either by hand or with the help of some computer software, check that your equations agree with the simulations. Plug the values for the parameters into each of the equations and see if the steady state values _U~s~_, _I~s~_ and _V~s~_ you computed with the equations is the same as you get as steady state value from the simulation. If that's not the case, it means your equations aren't right yet.

It is useful to note that while the total numbers for each variable do not change at steady state, this is a dynamic equilibrium. There are still constantly cells and virus being produced and destroyed, it just so happens that the production and destruction mechanisms are equally strong and thus the overall numbers do not change.


### Task 9 
Continue to explore the model. Even though it's a fairly simple model, you can get interesting dynamics from it, such as acute infections and chronic infections. Contemplate what specific pathogens this model could represent. Also note that you can get all this dynamics without any immune response present. The interaction between cells and virus are enough to produce patterns of infection dynamics that broadly agree with patterns we can see for real infections. This of course does not mean the immune response is not important. But it does illustrate that if all we have is (noisy) virus kinetics data, we are likely able to capture that dynamics with many different types of models, including a simple one like this that is likely not too realistic for any given pathogen. 


## 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 running the simulation is 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('DSAIRM')` into the R console.
* If you want to learn a bit more about these kinds of models applied to acute viral infections, specifically influenza, see e.g. [@beauchemin11; @smith11]. 
* A few examples of these kinds of models applied to chronic viral infections, see e.g. [@guedj10; @chatterjee12; @perelson13]. 


### References


