-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
299 lines (223 loc) · 12.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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# epiworldR
<!-- badges: start -->
[](https://CRAN.R-project.org/package=epiworldR)
[](https://github.com/UofUEpiBio/epiworldR/actions/workflows/r.yml)
[](https://cran.r-project.org/package=epiworldR)
[](https://github.com/UofUEpiBio/epiworldR/blob/master/LICENSE.md)
[](https://app.codecov.io/gh/UofUEpiBio/epiworldR)
<!-- badges: end -->
This R package is a wrapper of the C++ library [epiworld](https://github.com/UofUEpiBio/epiworld){target="_blank"}. It provides a general framework for modeling disease transmission using [agent-based models](https://en.wikipedia.org/w/index.php?title=Agent-based_model&oldid=1153634802){target="_blank"}. Some of the main features include:
- Fast simulation with an average of 30 million agents/day per second.
- One model can include multiple diseases.
- Policies (tools) can be multiple and user-defined.
- Transmission can be a function of agents' features.
- Out-of-the-box parallelization for multiple simulations.
From the package's description:
> A flexible framework for Agent-Based Models (ABM), the epiworldR package provides methods for prototyping disease outbreaks and transmission models using a C++ backend, making it very fast. It supports multiple epidemiological models, including the Susceptible-Infected-Susceptible (SIS), Susceptible-Infected-Removed (SIR), Susceptible-Exposed-Infected-Removed (SEIR), and others, involving arbitrary mitigation policies and multiple-disease models. Users can specify infectiousness/susceptibility rates as a function of agents’ features, providing great complexity for the model dynamics. Furthermore, epiworldR is ideal for simulation studies featuring large populations.
Current available models:
```{r print-models, echo=FALSE, results='asis'}
models <- list.files(path = "R/", pattern = "Model.*.R", full.names = FALSE) |>
gsub(pattern = "(Model.*)\\.R", replacement = "\\1")
sprintf("%i. `%s`\n", 1:length(models), models) |>
cat()
```
## Installation
You can install the development version of epiworldR from [GitHub](https://github.com/) with:
``` r
devtools::install_github("UofUEpiBio/epiworldR")
```
Or from CRAN
```r
install.packages("epiworldR")
```
# Examples
This R package includes several popular epidemiological models, including
[SIS](https://en.wikipedia.org/w/index.php?title=Compartmental_models_in_epidemiology&oldid=1155757336#Variations_on_the_basic_SIR_model){target="_blank"},
[SIR](https://en.wikipedia.org/w/index.php?title=Compartmental_models_in_epidemiology&oldid=1155757336#The_SIR_model){target="_blank"}, and
[SEIR](https://en.wikipedia.org/w/index.php?title=Compartmental_models_in_epidemiology&oldid=1155757336#The_SEIR_model){target="_blank"} using either a fully connected graph (similar to a compartmental model) or a user-defined network.
## SIR model using a random graph
This Susceptible-Infected-Recovered model features a population of 100,000 agents simulated in a small-world network. Each agent is connected to ten other agents. One percent of the population has the virus, with a 70% chance of transmission. Infected individuals recover at a 0.3 rate:
```{r example}
library(epiworldR)
# Creating a SIR model
sir <- ModelSIR(
name = "COVID-19",
prevalence = .01,
transmission_rate = .7,
recovery = .3
) |>
# Adding a Small world population
agents_smallworld(n = 100000, k = 10, d = FALSE, p = .01) |>
# Running the model for 50 days
run(ndays = 50, seed = 1912)
sir
```
Visualizing the outputs
```{r sir-figures}
summary(sir)
plot(sir)
plot_incidence(sir)
```
## SEIR model with a fully connected graph
The SEIR model is similar to the SIR model but includes an exposed state. Here, we simulate a population of 10,000 agents with a 0.01 prevalence, a 0.6 transmission rate, a 0.5 recovery rate, and 7 days-incubation period. The population is fully connected, meaning agents can transmit the disease to any other agent:
```{r seir-conn}
model_seirconn <- ModelSEIRCONN(
name = "COVID-19",
prevalence = 0.01,
n = 10000,
contact_rate = 10,
incubation_days = 7,
transmission_rate = 0.1,
recovery_rate = 1 / 7
) |> add_virus(
virus(
name = "COVID-19",
prevalence = 0.01,
as_proportion = TRUE,
prob_infecting = 0.01,
recovery_rate = 0.6,
prob_death = 0.5,
incubation = 7
))
set.seed(132)
run(model_seirconn, ndays = 100)
summary(model_seirconn)
```
Computing some key statistics
```{r seir-conn-figures}
plot(model_seirconn)
repnum <- get_reproductive_number(model_seirconn)
head(plot(repnum))
head(plot_generation_time(model_seirconn))
```
## SIR Logit
This model provides a more complex transmission and recovery pattern based
on agents' features. With it, we can reflect co-morbidities that could change
the probability of infection and recovery. Here, we simulate a population
including a dataset with two features: an intercept and a binary variable
`Female`. The probability of infection and recovery are functions of the intercept and
the `Female` variables. The following code simulates a population of 100,000 agents
in a small-world network. Each agent is connected to eight other agents. One
percent of the population has the virus, with an 80% chance of transmission.
Infected individuals recover at a 0.3 rate:
```{r logit-model}
# Simulating a population of 100,000 agents
set.seed(2223)
n <- 100000
# Agents' features
X <- cbind(
Intercept = 1,
Female = sample.int(2, n, replace = TRUE) - 1
)
coef_infect <- c(.1, -2, 2)
coef_recover <- rnorm(2)
# Creating the model
model_logit <- ModelSIRLogit(
"covid2",
data = X,
coefs_infect = coef_infect,
coefs_recover = coef_recover,
coef_infect_cols = 1L:ncol(X),
coef_recover_cols = 1L:ncol(X),
prob_infection = .8,
recovery_rate = .3,
prevalence = .01
)
# Adding a small-world population
agents_smallworld(model_logit, n, 8, FALSE, .01)
# Running the model
run(model_logit, 50)
plot(model_logit)
# Females are supposed to be more likely to become infected
rn <- get_reproductive_number(model_logit)
(table(
X[, "Female"],
(1:n %in% rn$source)
) |> prop.table())[, 2]
# Looking into the agents
get_agents(model_logit)
```
## Transmission network
This example shows how we can draw a transmission network from a simulation. The following code simulates a population of 500 agents in a small-world network. Each agent is connected to ten other agents. One percent of the population has the virus, with a 50% chance of transmission. Infected individuals recover at a 0.5 rate:
```{r transmission-net}
# Creating a SIR model
sir <- ModelSIR(
name = "COVID-19",
prevalence = .01,
transmission_rate = .5,
recovery = .5
) |>
# Adding a Small world population
agents_smallworld(n = 500, k = 10, d = FALSE, p = .01) |>
# Running the model for 50 days
run(ndays = 50, seed = 1912)
# Transmission network
net <- get_transmissions(sir)
# Plotting
library(epiworldR)
library(netplot)
x <- igraph::graph_from_edgelist(
as.matrix(net[, 2:3]) + 1
)
nplot(x, edge.curvature = 0, edge.color = "gray", skip.vertex = TRUE)
```
## Multiple simulations
`epiworldR` supports running multiple simulations using the `run_multiple` function. The following code simulates 50 SIR models with 1000 agents each. Each agent is connected to ten other agents. One percent of the population has the virus, with a 90% chance of transmission. Infected individuals recover at a 0.1 rate. The results are saved in a `data.frame`:
```{r multiple-example}
model_sir <- ModelSIRCONN(
name = "COVID-19",
prevalence = 0.01,
n = 1000,
contact_rate = 2,
transmission_rate = 0.9, recovery_rate = 0.1
)
# Generating a saver
saver <- make_saver("total_hist", "reproductive")
# Running and printing
# Notice the use of nthread = 2 to run the simulations in parallel
run_multiple(model_sir, ndays = 100, nsims = 50, saver = saver, nthread = 2)
# Retrieving the results
ans <- run_multiple_get_results(model_sir)
head(ans$total_hist)
head(ans$reproductive)
plot(ans$reproductive)
```
# Tutorials
- The virtual INSNA Sunbelt 2023 session can be found here: https://github.com/UofUEpiBio/epiworldR-workshop/tree/sunbelt2023-virtual
- The in-person INSNA Sunbelt 2023 session can be found here:
https://github.com/UofUEpiBio/epiworldR-workshop/tree/sunbetl2023-inperson
# Citation
If you use `epiworldR` in your research, please cite it as follows:
```{r}
citation("epiworldR")
```
# Existing Alternatives
Several alternatives to `epiworldR` exist and provide researchers with a range of options, each with its own unique features and strengths, enabling the exploration and analysis of infectious disease dynamics through agent-based modeling. Below is a manually curated table of existing alternatives, including ABM [@ABM], abmR [@abmR], cystiSim [@cystiSim], villager [@villager], and RNetLogo [@RNetLogo].
| Package | Multiple Viruses | Multiple Tools | Multiple Runs | Global Actions | Built-In Epi Models | Dependencies | Activity |
|:--------|:--------|:--------|:--------|:--------|---------|:--------|:--------|
| [**epiworldR**](https://cran.r-project.org/package=epiworldR) | yes | yes | yes | yes | yes | [](https://CRAN.R-project.org/package=epiworldR) | [](https://github.com/UofUEpiBio/epiworldR) |
| [**ABM**](https://cran.r-project.org/package=ABM) | \- | \- | \- | yes | yes | [](https://CRAN.R-project.org/package=ABM) | [](https://github.com/junlingm/ABM) |
| [**abmR**](https://cran.r-project.org/package=abmR) | \- | \- | yes | \- | \- | [](https://CRAN.R-project.org/package=abmR) | [](https://github.com/bgoch5/abmR) |
| [**cystiSim**](https://cran.r-project.org/package=cystiSim) | \- | yes | yes | \- | \- | [](https://CRAN.R-project.org/package=cystiSim) | [](https://github.com/brechtdv/cystiSim) |
| [**villager**](https://cran.r-project.org/package=villager) | \- | \- | \- | yes | \- | [](https://CRAN.R-project.org/package=villager) | [](https://github.com/zizroc/villager) |
| [**RNetLogo**](https://cran.r-project.org/package=RNetLogo) | \- | yes | yes | yes | \- | [](https://CRAN.R-project.org/package=RNetLogo) | [](https://github.com/cran/RNetLogo) |
# Other ABM R packages
You may want to check out other R packages for agent-based modeling: [`ABM`](https://cran.r-project.org/package=ABM){target="_blank"},
[`abmR`](https://cran.r-project.org/package=abmR){target="_blank"},
[`cystiSim`](https://cran.r-project.org/package=cystiSim){target="_blank"},
[`villager`](https://cran.r-project.org/package=villager){target="_blank"}, and
[`RNetLogo`](https://cran.r-project.org/package=RNetLogo){target="_blank"}.
## Code of Conduct
The epiworldR project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.