-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
180 lines (135 loc) · 8.3 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
---
output: github_document
bibliography: vignettes/resources/library.json
link-citations: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
message = FALSE,
warning = FALSE,
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# {{ packagename }}: Estimate disease severity and under-reporting <img src="man/figures/logo.svg" align="right" width="130"/>
<!-- badges: start -->
<a href="https://app.digitalpublicgoods.net/a/11092"><img src="https://digitalpublicgoods.net/registry/dpgicon.svg" alt="Digital Public Good" height="25">
[](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://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://www.repostatus.org/#active)
[](https://CRAN.R-project.org/package={{ packagename }})
<!-- badges: end -->
_{{ packagename }}_ is an R package to estimate disease severity and under-reporting in real-time, accounting for delays in epidemic time-series.
_{{ packagename }}_ provides simple, fast methods to calculate the overall or static case fatality risk (CFR) of an outbreak up to a given time point, as well as how the CFR changes over the course of the outbreak.
_{{ packagename }}_ can help estimate disease under-reporting in real-time, accounting for delays reporting the outcomes of cases.
_{{ packagename }}_ implements methods outlined in @nishiura2009. There are plans to add estimates based on other methods.
_{{ packagename }}_ 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
_{{ packagename }}_ can be installed from CRAN using
```r
install.packages("{{ packagename }}")
```
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::pak("{{ gh_repo }}")
```
## Quick start
### Overall severity of the 1976 Ebola outbreak
This example shows how to use _{{ packagename }}_ to estimate the overall case fatality risks from the 1976 Ebola outbreak [@camacho2014], while correcting for delays using a Gamma-distributed onset to death duration taken from @barry2018, with a shape $k$ of 2.40 and a scale $\theta$ of 3.33.
```{r example-ebola-calc}
# Load package
library(cfr)
# Load the Ebola 1976 data provided with the package
data(ebola1976)
# Focus on the first 20 days the outbreak
ebola1976_first_30 <- ebola1976[1:30, ]
# Calculate the static CFR without correcting for delays
cfr_static(data = ebola1976_first_30)
# Calculate the static CFR while correcting for delays
cfr_static(
data = ebola1976_first_30,
delay_density = function(x) dgamma(x, shape = 2.40, scale = 3.33)
)
```
### Change in real-time estimates of overall severity during the 1976 Ebola outbreak
In this example we show how the estimate of overall severity can change as more data on cases and deaths over time becomes available, using the function `cfr_rolling()`.
Because there is a delay from onset-to-death, a simple "naive" calculation that just divides deaths-to-date by cases-to-date will underestimate severity.
The `cfr_rolling()` function uses the `estimate_severity()` adjustment internally to account for delays, and instead compares deaths-to-date with cases-with-known-outcome-to-date.
The adjusted estimate converges to the naive estimate as the outbreak declines and a larger proportion of cases have known outcomes.
```{r example-ebola-plot}
# Calculate the CFR without correcting for delays on each day of the outbreak
rolling_cfr_naive <- cfr_rolling(
data = ebola1976
)
# see the first few rows
head(rolling_cfr_naive)
# Calculate the rolling daily CFR while correcting for delays
rolling_cfr_corrected <- cfr_rolling(
data = ebola1976,
delay_density = function(x) dgamma(x, shape = 2.40, scale = 3.33)
)
head(rolling_cfr_corrected)
```
We plot the rolling CFR to visualise how severity changes over time, using the [_ggplot2_ package](https://ggplot2.tidyverse.org/). The plotting code is hidden here.
```{r}
# combine the data for plotting
rolling_cfr_naive$method <- "naive"
rolling_cfr_corrected$method <- "corrected"
data_cfr <- rbind(
rolling_cfr_naive,
rolling_cfr_corrected
)
```
```{r fig-rolling-cfr-ebola, echo=FALSE, fig.cap="Disease severity of ebola in the 1976 outbreak estimated on each day of the epidemic. The rolling CFR value converges to the static value towards the end of the outbreak. Both corrected and uncorrected estimates are shown."}
library(ggplot2)
# visualise both corrected and uncorrected rolling estimates
ggplot(data_cfr) +
geom_ribbon(
aes(
date,
ymin = severity_low, ymax = severity_high,
fill = method
),
alpha = 0.2, show.legend = FALSE
) +
geom_line(
aes(date, severity_estimate, colour = method)
) +
scale_colour_brewer(
palette = "Dark2",
labels = c("Corrected CFR", "Naive CFR"),
name = NULL
) +
scale_fill_brewer(
palette = "Dark2"
) +
scale_x_date(
date_labels = "%d-%b-%Y",
name = "Date"
) +
labs(
y = "Disease severity"
) +
theme_classic() +
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".
## Help
To report a bug please open an [issue](https://github.com/{{ gh_repo }}/issues/new/choose).
## Contribute
Contributions to _{{ packagename }}_ are welcomed. Please follow the [package contributing guide](https://github.com/{{ gh_repo }}/blob/main/.github/CONTRIBUTING.md).
## 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.
## Related projects
_cfr_ functionality overlaps with that of some other packages, including
- [_coarseDataTools_](https://cran.r-project.org/package=coarseDataTools) is an R package that allows estimation of relative case fatality risk between covariate groups while accounting for delays due to survival time, when numbers of deaths and recoveries over time are known. _cfr_ uses simpler methods from @nishiura2009 that can be applied when only cases and deaths over time are known, generating estimates based on all data to date, as well as time-varying estimates. _cfr_ can also convert estimates of cases with known outcomes over time into an estimate of under-ascertainment, if a baseline estimate of fatality risk is available from the literature (e.g. from past outbreaks).
- [_EpiNow2_](https://cran.r-project.org/package=EpiNow2) is an R package that can allow estimation of case fatality risk if it is defined as a secondary observation of cases. In particular, it allows for estimation that accounts for the smooth underlying epidemic process, but this requires additional computational effort. A comparison of these methods is planned for a future release.
_cfr_ is in future expected to benefit from the functionality of the forthcoming [_epiparameter_ package](https://epiverse-trace.github.io/epiparameter/), which is also developed by Epiverse-TRACE. _epiparameter_ aims to provide a library of epidemiological parameters to parameterise delay density functions, as well as the convenient `<epidist>` class to store, access, and pass these parameters for delay correction.
## References