/
README.Rmd
193 lines (130 loc) · 10.1 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
# Infectious disease model library and utilities <img src="man/figures/logo.png" align="right" alt="" width="120" />
[](https://www.repostatus.org/#wip)
[](https://cran.r-project.org/package=idmodelr)
[](https://github.com/seabbs/idmodelr)
[](https://www.samabbott.co.uk/idmodelr/)
[](https://www.samabbott.co.uk/idmodelr/dev)
[](https://mybinder.org/v2/gh/seabbs/idmodelr/master?urlpath=rstudio)
[](https://travis-ci.org/seabbs/idmodelr)
[](https://ci.appveyor.com/project/seabbs/idmodelr)
[](https://codecov.io/github/seabbs/idmodelr?branch=master)
[](https://cran.r-project.org/package=idmodelr)
[](https://cran.r-project.org/package=idmodelr)
[](https://doi.org/10.5281/zenodo.2641048)
Explore a range of infectious disease models in a consistent framework. The primary aim of `idmodelr` is to provide a library of infectious disease models for researchers, students, and other interested individuals. These models can be used to understand the underlying dynamics and as a reference point when developing models for research. `idmodelr` also provides a range of utilities. These include: plotting functionality; a simulation wrapper; scenario analysis tooling; an interactive dashboard; tools for handling mult-dimensional models; and both model and parameter look up tables. Unlike other modelling packages such as [`pomp`](https://kingaa.github.io/pomp/), [`libbi`](http://libbi.org) and [`EpiModel`](http://www.epimodel.org), `idmodelr` serves primarily as an educational resource. It is most comparable to [`epirecipes`](http://epirecip.es/epicookbook/chapters/simple) but provides a more consistent framework, an `R` based workflow, and additional utility tooling. After users have explored model dynamics with `idmodelr` they may then implement their model using one of these packages in order to utilise the model fitting tools they provide. For newer modellers, this package reduces the barrier to entry by containing multiple infectious disease models, providing a consistent framework for simulation and visualisation, and [signposting](https://www.samabbott.co.uk/idmodelr/articles/resources.html) towards other, more research, focussed resources.
## Installation
Install the CRAN version:
```{r cran-installation, eval = FALSE}
install.packages("idmodelr")
```
Alternatively install the development version from GitHub:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("seabbs/idmodelr")
```
## Quick start
In this quick start guide we are going to be defining, simulating and plotting a Susceptible-Infected-Recovered deterministic compartmental model with simple population demographics (births = deaths). The first step is to load the `idmodelr` package.
```{r}
library(idmodelr)
```
The next step is to find the model of interest amongst those implemented in `idmodelr`. `model_details` lists all of the models implemented in `idmodelr` and can be search using `dplyr`, base R, or other dataframe tools.
```{r}
library(dplyr)
model_details %>%
dplyr::filter(model_family %in% "SIR") %>%
knitr::kable()
```
Now look at the model and the model help file (`?SIR_demographics_ode`) to get an understanding of how the model is constructed.
```{r}
SIR_demographics_ode
```
Check the parameters required by the model using `required_parameters`. This returns a table containing all the parameters that must be defined in order to use the model as well as descriptive information for each parameter.
```{r}
parameters <- required_parameters("SIR_demographics_ode")
knitr::kable(parameters)
```
Parameterise the model.
```{r}
parameters <- data.frame(
beta = 3, ##Transmission rate = contact rate * transmission probablity
tau = 0.5, ## Rate recovcery = 1 / duration of infection
mu = 1/81 ## Natural birth/death rate = 1 / average lifespan
)
```
Check the initial conditions required by looking at the start of the model function. In most cases this should match up to the model name (i.e S, I and R for an SIR model) but risk stratification etc. will require additional compartments.
```{r}
inits <- data.frame(
S = 999,
I = 1,
R = 0
)
```
Specify the timespan over which to run the model.
```{r}
times <- seq(0, 50, 0.1)
```
Simulate the model.
```{r}
traj <- simulate_model(model = SIR_demographics_ode,
sim_fn = solve_ode, ##as solving an ode
inits = inits,
params = parameters,
times = times)
traj
```
Summarise the model.
```{r}
summarise_model(traj) %>%
knitr::kable()
```
Plot the model trajectory.
```{r}
plot_model(traj, facet = FALSE)
```
Vary the model parameters, by increasing the mortality rate, and then simulate the updated model.
```{r}
parameters_up <- parameters
parameters_up[["mu"]] <- 1 / 20
traj_up <- simulate_model(model = SIR_demographics_ode,
sim_fn = solve_ode,
inits,
parameters_up,
times)
```
Plot the original trajectory and the updated trajectory. What has the impact of increasing mortality been?
```{r}
plot_model(traj, traj_up, facet = TRUE)
```
See the package vignettes for more help getting started and some additional ideas for exploring infectious disease model dynamics.
## Dashboard
A shiny application has been developed that showcases some of the functionality of the `idmodelr` package. This application allows the parameter spaces of a range of models built into `idmodelr` to be explored in an interactive session. It is designed to be used as a teaching aid when introducing people to the concepts behind infectious disease models without requiring them to interact with the underlying code. The code for the dashboard can be found [here](https://github.com/seabbs/exploreidmodels). It can be run locally using the following (*Note: this will install required packages to your system*),
```{r run-dash, eval = FALSE}
#install.packages("shiny")
shiny::runGitHub("exploreidmodels", "seabbs")
```
## Contributing
### Contributing a model
Additional models are extremely welcome!
To add models in the same family as those already implemented (i.e [`SIR_ode`](https://github.com/seabbs/idmodelr/blob/master/R/SIR.R)) please follow the implemented coding style closely (alternatively open an [issue](https://github.com/seabbs/idmodelr/issues) explaining why this style needs updating). Models should be named using their compartments in capitals followed by lower case model details, and finally the model type. An example of this is the `SIR_demographics_ode` model. For highly complex models only the most major model details should be listed (aim for less than 40 characters). An entry for `model_details` is also required (see [`model_details.R`](https://github.com/seabbs/idmodelr/blob/master/data-raw/model_details.R)). If new parameters have been used then a description must be added to `parameter_details` (see [`parameter_details.R`](https://github.com/seabbs/idmodelr/blob/master/data-raw/parameter_details.R)). Please consider also adding to the testing suite for your new model (or flagging the lack of tests). Models can either be added via a pull request or via an issue.
To add a new family of models (i.e stochastic models) please open an [issue](https://github.com/seabbs/idmodelr/issues) outlining your proposed approach. A new family of models is likely to require at least its own `solve_` (equivalent to [`solve_ode`](https://github.com/seabbs/idmodelr/blob/master/R/solve.R)) function and may also require other package changes. Models implemented in other languages (i.e C) are also very welcome.
### Other contributions
File an issue [here](https://github.com/seabbs/idmodelr/issues) if there is any other feature, that you think is missing from the package, or better yet submit a pull request!
Please note that the `idmodelr` project is released with a [Contributor Code of Conduct](https://github.com/seabbs/idmodelr/blob/master/.github/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
### Docker
This packge was developed in a docker container based on the [tidyverse](https://hub.docker.com/r/rocker/tidyverse/) docker image. To run the docker image run:
```{bash, eval = FALSE}
docker run -d -p 8787:8787 --name idmodelr -e USER=seabbs -e PASSWORD=seabbs seabbs/idmodelr
```
The rstudio client can be found on port `:8787` at your local machines ip. The default username:password is seabbs:seabbs, set the user with `-e USER=username`, and the password with ` - e PASSWORD=newpasswordhere`. The default is to save the analysis files into the user directory. Alternatively, access the development environment via [binder](https://mybinder.org/v2/gh/seabbs/idmodelr/master?urlpath=rstudio).