---
title: "DSAIDE Package Tutorial"
author: "<a href=http://handelgroup.uga.edu>Andreas Handel</a>"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    fig_caption: yes
    css: dsaidevignettestyle.css
vignette: >
  %\VignetteIndexEntry{DSAIDE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: vignetterefs.bib
---



## Summary
_Dynamical Systems Approaches to Infectious Disease Epidemiology (DSAIDE)_ is an R package that allows you to explore and study concepts of infectious disease epidemiology using dynamical systems models, without the need to read or write computer code.
The package also provides a path toward using and building your own models by relatively seamlessly moving from the graphical user interface to direct interaction with pre-written simulations all the way to modifying the underlying simulations to fit your needs. 
The different use cases for the package are described below.


## Package description

The package consists of several simulations/apps that allow for the simulation and exploration of different topics in infectious disease epidemiology. 

The underlying models are written as compartmental dynamical models, either deterministic using differential equations (deSolve package) or stochastic using a Gillespie-type approach (adaptivetau package). A graphical user interface is wrapped around each simulation/app. The graphical user interface is written using the functionality of the R Shiny package. This allows exploration of models and infectious disease epidemiology concepts without the need to write any code. At the same time, the package is structured in a way that should allow those interested in the actual models and learning R coding to easily move from one stage to another.

Each app is meant to be fully self-explanatory and contains a description of the model, a list of tasks the user could try, and further information on background reading and other resources. 


## Intended audience and goal of the package

The audience for this app consists individuals interested in infectious disease epidemiology from a _systems/modeling perspective_. For instance the apps allow exploration of concepts such as _patterns of infectious disease incidence_, _reproductive number concept_, _extinctions and critical community size_, etc. All these concepts are not well described by applying classical epidemiology approaches (i.e. assuming independence between individuals) to infectious diseases, but can readily by understood using a systems/modeling approach.

While the package was written as a component of a course on infectious disease epidemiology/modeling, the documentation for each app tries to be fairly complete and self-contained. This should allow you to get some understanding of the topics and models without requiring additional information. However, the information provided inside each app is not sufficient to get a very thorough understanding. If you use this package on your own without taking a class on the topc, it might be possible to learn the material covered by the apps in depth by working through some of the references provided for each app or general infectious disease modeling textbooks (e.g. [@keeling08; @vynnycky10; @bjoernstad18]). 



## Installing the package 
The package can be installed from CRAN or Github. See the documentation on the [package page](https://ahgroup.github.io/DSAIDE/) for more details.

Package installation is a one-time process, unless R itself is being upgraded/reinstalled. Note that the package depends on other packages, which will also be installed as needed.


## Using the package

The following sections describe the main envisioned ways the content in this R package can be used and extended. The idea is that you start at level 1, and then depending on needs and interests, you can decide to move on to the next level.


### Level 1: Interactive use through the graphical user interface

The interactive exploration of the models and infectious disease concepts through the graphical user interface is the main intended use of this package. The steps to get there are simple. 

#### Load and run the package

Every time a new R/Rstudio session is started, the package needs to be loaded: 
```{r, eval=FALSE, echo=TRUE}
library('DSAIDE')
```
followed by starting the main menu for the package:
```{r, eval=FALSE, echo=TRUE}
dsaidemenu()
```

This will bring up a graphical menu from which you can select each app. Each app contains the information needed to understand the underlying model, and has a list of (non exhaustive) suggested tasks to learn about the topic covered by the app. After exploring an app, you can return to the main menu and move on to another app, or eventually exit the main menu and close the R session. No code needs to be written at this level of exploration and learning.

### Level 2: Directly interacting with the simulation functions
Once you are comfortable interacting with the models and have a good understanding of the concepts covered by the different apps, it is possible, without too much effort, to interact with the code more directly. This will provide more flexibility but will require writing some code.

To facilitate direct interaction and modification of the underlying simulations, each app is structured in such a way that the underlying model/simulation is a stand-alone function. For some apps, there are multiple underlying functions involved. You can call any of these functions directly, without going through the graphical interface. The 'Further Information' tab inside each app provides the name of the corresponding underlying function(s).

Consider as example the first app, called "ID Dynamics Intro". The simulator function for this model is called `simulate_sir_ode.R`. After loading the package (if not already loaded) with 

```{r eval=TRUE, echo=FALSE}
library('DSAIDE') 
```

you can learn about the inputs and outputs of the function by looking at its documentation 

```{r eval=FALSE, echo=TRUE}
help('simulate_sir_ode')
```

The help file explains that you can run the simulation by specifying initial number of susceptibles and infected, the duration for which the simulation should be run, and the infection and recovery parameters. 
Each parameter has some default, listed in the help file. Running a simulation model without any specifications runs it with the defaults:

```{r, eval=TRUE, echo=TRUE}
result <- simulate_sir_ode()
```

Calling the simulation function execuctes the underlying dynamical model (here a simple 3 compartment ODE model, as described in the "Model" section of the app). Most simulation functions produce and return time-series for the dynamics of each of the variables that are tracked as a list. You can then take the results returned from the simulation function and further process them. For instance you could plot the time-series for susceptible as function of time:

```{r, eval=TRUE, echo=TRUE}
plot(result$ts[ , "time"],result$ts[ , "S"],xlab='Time',ylab='Number Susceptible',type='l')
```


You can overwrite the default settings by providing your own values for specific parameters, as shown in this example:

```{r, eval=TRUE, echo=TRUE}
result <- simulate_sir_ode(S = 2000, b = 0.001, g = 0.5, tfinal = 200)
plot(result$ts[ , "time"],result$ts[ , "S"],xlab='Time',ylab='Number Susceptible',type='l')
```

Any values that you do not specify will be kept at their defaults.

Note that unless explicitly specified, the models do not have inherent time units. Instead, those depend on the time units you choose for the parameters. It is important to ensure that all quantities (parameters and time settings) have the same time units, e.g. days or months (or the inverse of those units for the rate parameters). 

Not all simulator functions return time-series. The help file for each function will tell you what is returned.

The ability to call the simulation functions directly instead of going through the graphical interface allows additional exploration of the models. For instance if you wanted to explore the behavior of a model systematically for different values of a given parameter, this would need to be done manually if run through the graphical interface. Calling the function directly allows you to automate this by wrapping the function inside a loop over the parameter of interest, recording some quantity of interest for each run, and report the result at the end. The following is a simple example, showing a loop over different values of the recovery rate and recording the peak of the outbreak each time, with the final result _peak of outbreak as function of recovery time_ shown in a plot:

```{r, eval=TRUE, echo=TRUE}
gvec = seq(0.01,0.3,by=0.01) #values of recovery rate, g, for which to run the simulation 
peak = rep(0,length(gvec)) #this will record the peak values for each g
for (n in 1:length(gvec))
{
  #call the simulator function with different values of g each time
  result <- simulate_sir_ode(S = 500, b = 1/2500, g = gvec[n],  tfinal = 200)
  peak[n] <- max(result$ts[,"I"]) #record max number of infected for each value of g
}
#plot final result
plot(gvec,peak,type='p',xlab='Rate of recovery',ylab='Max number of infected')
```

Thus, you can add your own custom code to the existing simulator functions and with a few lines of extra code analyze and explore many more questions and scenarios than those accessible through the graphical interface. This provides a lot more flexibility, but requires writing some R code to interface with the supplied simulator functions. 

### Level 3: Modifying the simulation functions

Level 2 provides you with some flexibility, but the main constraint is that only pre-written, existing models can be used and analyzed. This constraint can be overcome by directly modifiying and customizing the underlying simulation functions. As was true for moving from level 1 to 2, this move from level 2 to what I call level 3 provides further (almost unlimited) flexibility at the cost of having to write increasingly more `R` code.

To make modifying the existing functions easy, copies of all simulator functions are provided in a folder called _simulatorfunctions_ which can be downloaded as a zip file from the main menu. Each function in that folder starts with `simulate_`. The _Further Information_ section in each app tells you which simulator function goes with which app.

The code for each simulator function is (hopefully) well documented. Some basic to intermediate level of `R` coding experience is likely required to successfully modify the functions. In addition to modifying the simulator function of interest, you will likely also have to write some additional code to interact with their modified function (as described in _Level 2_).

The following provides a simple example of this process of modifying a simulator function and exploring its results. Assume that we want to modify the simple SIR model encoded in `simulate_sir_ode.R`. After getting the file and making a copy (let's call the modified function `mysimulator.R`), we can make modifications. Say we want to include waning immunity with recovered returning to the susceptible class at rate _w_. 

We will need to modify the following lines of code:

old:
```{r eval=FALSE, echo=TRUE}
simulate_sir_ode <- function(S = 1000, I = 1, R = 0, b = 0.002, g = 1, tstart = 0, tfinal = 100, dt = 0.1 ) 
```

new:
```{r eval=FALSE, echo=TRUE, color='red'}
mysimulator <- function( S = 1000, I = 1, R = 0, b = 0.002, g = 1, w = 0, tstart = 0, tfinal = 100, dt = 0.1 ) 
```

old:
```{r eval=FALSE, echo=TRUE}
pars = c(b = b, g = g)
```

new:
```{r eval=FALSE, echo=TRUE, color='red'}
pars = c(b = b, g = g, w = w)
```


old (ignoring comments present in the code):
```{r eval=FALSE, echo=TRUE}
dS = -b*S*I
dI = b*S*I -g*I
dR = g*I
```

new:
```{r eval=FALSE, echo=TRUE, color='red'}
dS = -b*S*I +w*R
dI = b*S*I -g*I
dR = g*I -w*R
```

Note that if we wanted to share this function with others, we would need to also update the function documentation at the start of the file. For personal use of the function, this is a good idea but not required.

We could now for instance explore how different rates of waning immunity impact the maximum peak size over all outbreaks. This requires a slight modification of the code shown above in _Level 2_ as follows:


```{r eval=TRUE, echo=TRUE}
source('mysimulator.R') #to initialize the new function - it needs to be in same directory as this code
wvec = seq(0,1,by=0.02) #values of immunity loss rate, w, for which to run the simulation 
peak = rep(0,length(wvec)) #this will record the peak values for each g
for (n in 1:length(wvec))
{
  result <- mysimulator( S = 1000, I = 1, R = 0, b = 1e-3, g = 0.5, w = wvec[n], tstart = 0, tfinal = 300, dt = 0.1)
  peak[n] <- max(result$ts[,"I"])
}
plot(wvec,peak,type='p',xlab='Rate of waning immunity',ylab='Max number of infected')
```


For most users and especially novice coders, it is likely best to start with one of the provided models and modify as needed. However, at this level, you have essentially full control and are only limited by what can be accomplished using the `R` programming language and their ability and interest in writing customized code. 

## Contributing to the package
The package is on GitHub and you can use the usual GitHub process to file bug reports, send feature requests, contribute updates and bug fixes, etc. If you have any comments or feedback, I very much welcome them. Please file a [GitHub issue](https://github.com/ahgroup/DSAIDE/issues) and let me know what you think.

The package is built in a way that makes it (hopefully) easy for others to contribute new simulations/apps. To that end, the package contains [this Markdown file](https://github.com/ahgroup/DSAIDE/blob/master/inst/docsfordevelopers/documentation.md) which provides further information on the details of the package structure. If you plan to develop new apps, or make other substantial contributions, it's best to get in touch with me first via email or GitHub.

## Further information
* [I published a paper describing the package and how to use it](https://doi.org/10.1371/journal.pcbi.1005642). The package structure has changed since the paper was published, but it still describes the overall idea and context well, if you are interested in that.  
* A 'companion' package to this one, called Dynamical Systems Approaches for Immune Respone Modeling (DSAIRM), focuses on models for analyzing with-host infection dynamics. It has the same structure as DSAIDE. [See the DSAIRM site for more information.](https://ahgroup.github.io/DSAIRM)
* I have solutions (as R Markdown files) to most of the 'What to do' tasks for the different apps. If you are an instructor using this package as part of a class, email me if you are interested in having access to these solutions.

## Contributors
This R package is developed and maintained by [Andreas Handel](http://handelgroup.uga.edu/). A full list of contributors [can be found here](https://ahgroup.github.io/DSAIDE/authors.html).

## Citation
If the package does in any way help you with your work such that it warrants citing in one of your papers, please cite [the DSAIDE publication in PLoS Comp Bio](https://doi.org/10.1371/journal.pcbi.1005642).

## References
