generated from epiverse-trace/packagetemplate
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
229 lines (177 loc) · 10.8 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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
---
output: github_document
bibliography: vignettes/references.json
link-citations: true
---
```{r, include = FALSE}
knitr::opts_chunk[["set"]](
collapse = TRUE,
comment = "#>",
message = FALSE,
warning = FALSE,
fig.path = "man/figures/README-",
out.width = "100%",
dpi = 150
)
```
# {{ packagename }}: Composable epidemic scenario modelling <img src="man/figures/logo.svg" align="right" width="130"/>
<!-- badges: start -->
[](https://opensource.org/license/mit/)
[](https://github.com/{{ gh_repo }}/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/{{ gh_repo }}?branch=main)
[](https://www.repostatus.org/#wip)
[](https://CRAN.R-project.org/package={{ packagename }})
<!-- badges: end -->
_{{ packagename }}_ is an R package that provides modular representations of populations and public health response measures, allowing them to be combined with epidemiological model structures curated from the published literature, to conveniently compose and compare epidemic scenario models.
The models in _{{ packagename }}_ focus on directly transmitted infections, and implement methods outlined in @bjornstad2020a and @bjornstad2020.
The models in _{{ packagename }}_ can help provide rough estimates of the course of epidemics, and the effectiveness of pharmaceutical and non-pharmaceutical interventions.
_{{ packagename }}_ relies on [Eigen](https://gitlab.com/libeigen/eigen) via [{RcppEigen}](https://cran.r-project.org/package=RcppEigen), and on [Boost Odeint](https://www.boost.org/doc/libs/1_82_0/libs/numeric/odeint/doc/html/index.html) via [{BH}](https://cran.r-project.org/package=BH), and is developed at the [Centre for the Mathematical Modelling of Infectious Diseases](https://www.lshtm.ac.uk/research/centres/centre-mathematical-modelling-infectious-diseases) at the London School of Hygiene and Tropical Medicine as part of the [Epiverse-TRACE initiative](https://data.org/initiatives/epiverse/).
## Installation
The current development version of _{{ packagename }}_ can be installed from [GitHub](https://github.com/) using the _pak_ package.
```r
if(!require("pak")) install.packages("pak")
pak::pkg_install("{{ gh_repo }}")
```
Alternatively, install pre-compiled binaries from [the Epiverse TRACE R-universe](https://epiverse-trace.r-universe.dev/epidemics)
```r
install.packages("epidemics", repos = c("https://epiverse-trace.r-universe.dev", "https://cloud.r-project.org"))
```
### Installation Notes
1. Some users who are also using or developing packages that use Stan might face issues if they have modified their toolchain to accommodate packages such as [_cmdstanr_](https://mc-stan.org/cmdstanr/); see [this resolved issue](https://github.com/stan-dev/cmdstanr/issues/790) for a starting point if you face similar problems.
2. Users on Windows systems will need to have packages from the _RTools_ family installed and on their system path; see [this link for guidance on using _RTools_](https://cran.r-project.org/bin/windows/Rtools/) for your version of R.
## Quick start
Here we show an example of using the default model in _{{ packagename }}_ to model an epidemic in the U.K. population with an $R_0$ similar to that of pandemic influenza, with heterogeneity in social contacts among different age groups, and with the implementation of school closures to dampen the spread of the infection.
```{r}
# load epidemics
library(epidemics)
library(ggplot2)
library(dplyr)
```
Prepare the social contact pattern for a population (here, the U.K population), divided into three age groups: 0 -- 19, 20 -- 39, and 40+.
```{r}
# load contact and population data from socialmixr::polymod
polymod <- socialmixr::polymod
contact_data <- socialmixr::contact_matrix(
polymod,
countries = "United Kingdom",
age.limits = c(0, 20, 40),
symmetric = TRUE
)
# prepare contact matrix
contact_matrix <- t(contact_data[["matrix"]])
# prepare the demography vector
demography_vector <- contact_data[["demography"]][["population"]]
names(demography_vector) <- rownames(contact_matrix)
```
Prepare the initial conditions for the population by age group --- here, one in every million individuals is infected at the start of the epidemic (for a total of about 60 infections).
```{r}
# initial conditions: one in every 1 million is infected
initial_i <- 1e-6
initial_conditions <- c(
S = 1 - initial_i, E = 0, I = initial_i, R = 0, V = 0
)
# build for all age groups
initial_conditions <- rbind(
initial_conditions,
initial_conditions,
initial_conditions
)
rownames(initial_conditions) <- rownames(contact_matrix)
```
Prepare an object of the class `<population>`, using the function `population()`.
```{r}
# prepare the population to model as affected by the epidemic
uk_population <- population(
name = "UK",
contact_matrix = contact_matrix,
demography_vector = demography_vector,
initial_conditions = initial_conditions
)
```
Define an intervention to close schools for two months. This intervention mostly only affects individuals in the age range 0 -- 19, and reduces their contacts by 50%, reducing the contacts of other age groups by 1%. This is an object of the class `<contacts_intervention>`, created using the function `intervention()`, while setting `type = "contacts"`.
```{r}
# an intervention to close schools
close_schools <- intervention(
type = "contacts",
time_begin = 200,
time_end = 260,
reduction = matrix(c(0.5, 0.01, 0.01))
)
# view the intervention
close_schools
```
Run the default epidemic model, using the function `model_default()`.
We assume an $R_0$ of 1.5 which is similar to pandemic influenza, an infectious period of 7 days, and a pre-infectious period of 3 days.
From these values we can calculate transmission rate $\beta$ `1.5 / 7.0`, infectiousness_rate $\alpha$ `1.0 / 3.0` and recovery_rate $\gamma$ `1.0 / 7.0`.
```{r message=FALSE}
# run an epidemic model using `epidemic()`
output <- model_default(
population = uk_population,
transmission_rate = 1.5 / 7.0,
infectiousness_rate = 1.0 / 3.0,
recovery_rate = 1.0 / 7.0,
intervention = list(contacts = close_schools),
time_end = 600, increment = 1.0
)
```
Visualise the development of individuals in the "infectious" compartment over model time. Note that these curves represent the number of individuals that are infectious, and not the number of newly infectious individuals.
```{r fig-modelout, echo=FALSE}
filter(output, compartment == "infectious") %>%
ggplot() +
geom_vline(
xintercept = c(close_schools[["time_begin"]], close_schools[["time_end"]]),
colour = "red",
linetype = "dashed",
linewidth = 0.2
) +
annotate(
geom = "text",
label = "Schools closed",
colour = "red",
x = 230, y = 400e3,
angle = 90,
vjust = "outward"
) +
geom_line(
aes(time, value, colour = demography_group)
) +
scale_colour_brewer(
palette = "Dark2",
labels = rownames(contact_matrix),
name = "Age group"
) +
scale_y_continuous(
labels = scales::comma,
name = "Individuals infected"
) +
labs(
x = "Model time (days)"
) +
theme_bw() +
theme(
legend.position = "top"
)
```
## Package vignettes
More details on how to use _{{ packagename }}_ can be found in the [online documentation as package vignettes](https://epiverse-trace.github.io/{{ packagename }}/), under "Articles".
## Package models
_{{ packagename }}_ provides a convenient interface to a library of compartmental models that can help to model epidemic scenarios for directly transmitted respiratory infections such as influenza or Covid-19 as well haemorrhagic fevers such as Ebola virus disease:
1. A deterministic SEIR-V model with susceptible, exposed, infectious, recovered, and vaccinated compartments (SEIR-V), allowing for heterogeneity in social contacts, the implementation of a group-specific non-pharmaceutical intervention that reduces social contacts, and a vaccination regime with group-specific start and end dates;
2. The deterministic Vacamole model developed at [RIVM, the Dutch Public Health Institute](https://www.rivm.nl/) for the Covid-19 pandemic, with a focus on scenario modelling for hospitalisation and vaccination [@ainslie2022];
3. A stochastic, discrete-time, compartmental SEIR model suitable for modelling haemorrhagic fevers such as Ebola Virus Disease, including hospitalisation and hospital and funeral transmissions, adapted from @li2019 and @getz2018;
4. An initial implementation of a compartmental model for diphtheria in the context of internally displaced persons camps, including a reporting rate, hospitalisation rate, and delays in entering and leaving hospital, taken from @finger2019.
More models are planned to be added in the near future.
Please get in touch if you would like to see your model added to the _{{ packagename }}_ model library --- we are happy to help with translating it into our framework, with a special focus on making the model applicable to LMIC settings.
## Related projects
_epidemics_ aims to be a library of published epidemiological models, and the following projects may be useful for building your own models:
- The [R package _finalsize_](https://cran.r-project.org/package=finalsize) is also developed by Epiverse-TRACE and helps to calculate the final size of an epidemic in a heterogeneous population, and is a quicker option for estimates of total infections when the temporal dynamics are less important;
- The [Epirecipes project](http://epirecip.es/epicookbook/) is a cookbook-style guide that focuses on different ways to implement epidemic models in R and other languages;
- The [R package _odin_](https://cran.r-project.org/package=odin) generates systems of ordinary differential equations (ODE) and integrate them, using a domain specific language (DSL), and is widely used to translate compartmental models from R to C code for performance gains;
- Many R packages provide modelling options, and these can be found on the [CRAN Epidemiology Task View](https://cran.r-project.org/view=Epidemiology) under the section "Infectious disease modelling".
## Help
To report a bug please open an [issue](https://github.com/{{ gh_repo }}/issues/new/choose).
## Contribute
Contributions to _{{ packagename }}_ are welcomed via [pull requests](https://github.com/{{ gh_repo }}/pulls).
## Code of conduct
Please note that the _{{ packagename }}_ project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
## References