differences for PR #104

epiverse-trace · Jan 25, 2024 · 9b29459 · 9b29459
1 parent 387588d
commit 9b29459
Show file tree

Hide file tree

Showing 28 changed files with 1,878 additions and 2,090 deletions.
diff --git a/cache/__packages b/cache/__packages
@@ -0,0 +1,8 @@
+base
+methods
+datasets
+utils
+grDevices
+graphics
+stats
+EpiNow2
diff --git a/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.RData b/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.RData
diff --git a/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.rdb b/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.rdb
diff --git a/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.rdx b/cache/unnamed-chunk-4_5c79dc34bb873eb2a2dde3e60377e3c1.rdx
diff --git a/config.yaml b/config.yaml
diff --git a/fig/disease-reporting.jpg b/fig/disease-reporting.jpg
diff --git a/fig/fig5a-normaldistribution.png b/fig/fig5a-normaldistribution.png
diff --git a/fig/incubation-period-serial-interval.jpg b/fig/incubation-period-serial-interval.jpg
diff --git a/fig/infectiousness-covid19.jpg b/fig/infectiousness-covid19.jpg
diff --git a/fig/introduction-rendered-unnamed-chunk-5-1.png b/fig/introduction-rendered-unnamed-chunk-5-1.png
diff --git a/fig/model-choices-rendered-unnamed-chunk-3-1.png b/fig/model-choices-rendered-unnamed-chunk-3-1.png
diff --git a/fig/pkgs-hexlogos.png b/fig/pkgs-hexlogos.png
diff --git a/fig/read-delays-rendered-unnamed-chunk-20-1.png b/fig/read-delays-rendered-unnamed-chunk-20-1.png
diff --git a/fig/reproduction-generation-time.png b/fig/reproduction-generation-time.png
diff --git a/fig/reproduction-number-pre-symptomatic.png b/fig/reproduction-number-pre-symptomatic.png
diff --git a/fig/rt-adjusting-delays.png b/fig/rt-adjusting-delays.png
diff --git a/fig/seria-interval-fitted-distributions.jpg b/fig/seria-interval-fitted-distributions.jpg
diff --git a/fig/serial-interval-covid-sars.jpg b/fig/serial-interval-covid-sars.jpg
diff --git a/fig/serial-interval-observed.jpeg b/fig/serial-interval-observed.jpeg
diff --git a/fig/serial-interval-pairs.jpg b/fig/serial-interval-pairs.jpg
diff --git a/fig/simulating-transmission-rendered-plot-1.png b/fig/simulating-transmission-rendered-plot-1.png
diff --git a/fig/time-periods.jpg b/fig/time-periods.jpg
diff --git a/introduction.md b/introduction.md
@@ -0,0 +1,203 @@
+---
+title: 'Outbreak analytics pipelines'
+teaching: 10
+exercises: 2
+editor_options: 
+  chunk_output_type: console
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- Why use R packages for Outbreak analytics?
+- What can we do to analyse our outbreak data?
+- How can I start doing Outbreak Analytics with R?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Explain our vision on the need for outbreak analytics R packages. 
+- Share our strategy to create R packages into an outbreak analytics pipeline.
+- Define our plan to start your learning path in outbreak analytics with R.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: prereq
+
+## Prerequisites
+
+This episode requires you to be familiar with:
+
+**Data science** : Basic programming with R.
+
+**Epidemic theory** : Reproduction number.
+
+:::::::::::::::::::::::::::::::::
+
+## Why to use R packages for Outbreak analytics?
+
+Outbreaks appear with different diseases and in different contexts, but what all of them have in common are the key public health questions ([Cori et al. 2017](https://royalsocietypublishing.org/doi/10.1098/rstb.2016.0371#d1e605)).
+
+Is the epidemic going to take off? Is it under control? How much effort will be needed to control it? We can answer them by _quantifying the transmissibility_ of the disease. The most used parameter for this is the reproduction number ($R$), the average number of secondary infections caused by a typical primary case in the population
+of interest ([Prism, 2016](http://prism.edu.au/publications/prism-modeling-guideline/)). We can intuitively interpret it as: 
+
+- if $R>1$, the epidemic is likely to grow,
+- if $R<1$, the epidemic is likely to decline.
+
+We can estimate the reproduction number by initially using two __data inputs__: the incidence of reported cases and the [generation time](../learners/reference.md#generationtime) distribution. But to calculate it, we must apply the appropriate mathematical models written in code with the required computational methods. That is not enough! Following _good practices_, the code we write should be peer-reviewed and contain internal tests to double-check that we are getting the estimates we expect. Imagine rewriting all of it during a health emergency!
+
+In R, the fundamental unit of shareable code is the _package_. A package bundles together code, data, documentation, and tests and is easy to share with others ([Wickham and Bryan, 2023](https://r-pkgs.org/introduction.html)). We, as epidemiologists, can contribute to their collaborative maintenance as a community to perform less error-prone data analysis pipelines.
+
+::::::::::::::::::::::::::::::::: discussion
+
+### Questions to think about
+
+Remember your last experience with outbreak data and reflect on these questions:
+
+- What data sources did you need to understand the outbreak?
+- How did you get access to that data?
+- Is that analysis pipeline you followed reusable for the next response?
+
+Reflect on your experiences.
+
+:::::::::::::::::::::::::::::::::::::::::::
+
+
+## Example: Quantify transmission
+
+The `{EpiNow2}` package provides a three-step solution to _quantify the transmissibility_. Let's see how to do this with a minimal example. First, load the package:
+
+
+```r
+library(EpiNow2)
+```
+
+### First, get your case data
+
+Case incidence data must be stored in a data frame with the observed number of cases per day. We can read an example from the package:
+
+
+```r
+example_confirmed
+```
+
+```{.output}
+           date confirm
+  1: 2020-02-22      14
+  2: 2020-02-23      62
+  3: 2020-02-24      53
+  4: 2020-02-25      97
+  5: 2020-02-26      93
+ ---                   
+126: 2020-06-26     296
+127: 2020-06-27     255
+128: 2020-06-28     175
+129: 2020-06-29     174
+130: 2020-06-30     126
+```
+
+### Then, set the generation time
+
+Not all primary cases have the same probability of generating a secondary case. The onset and cessation of [infectiousness](../learners/reference.md#infectiousness) may occur gradually. For `{EpiNow2}`, we can specify it as a probability `distribution` with `mean`, standard deviation `sd`, and maximum value `max`:
+
+
+```r
+generation_time <- dist_spec(
+  mean = 3.6, 
+  sd = 3.1,
+  max = 20, 
+  distribution = "lognormal"
+)
+```
+
+### Let's calculate the reproduction number!
+
+In the `epinow()` function we can add:
+
+- the `reported_cases` data frame, 
+- the `generation_time` delay distribution, and 
+- the computation `stan` parameters for this calculation:
+
+
+```r
+epinow_estimates <- epinow(
+  # cases
+  reported_cases = example_confirmed[1:60],
+  # delays
+  generation_time = generation_time_opts(generation_time),
+  # computation
+  stan = stan_opts(
+    cores = 4, samples = 1000, chains = 3,
+    control = list(adapt_delta = 0.99)
+  )
+)
+```
+
+As an output, we get the time-varying (or [effective](../learners/reference.md#effectiverepro)) reproduction number, as well as the cases by date of report and date of infection:
+
+
+```r
+base::plot(epinow_estimates)
+```
+
+<img src="fig/introduction-rendered-unnamed-chunk-5-1.png" style="display: block; margin: auto;" />
+
+::::::::::::::::: callout
+
+### Is this $Rt$ estimation biased?
+
+Review [Gostic et al., 2020](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008409) about what additional adjustments this estimation requires to avoid false precision in $Rt$. 
+
+:::::::::::::::::::::::::
+
+## The problem!
+
+However, _quantifying the transmissibility_ during a real-life outbreak response is more challenging than this example!
+
+Usually, we receive outbreak data in non-standard formats, requiring specific steps and taking the most time to prepare usable data inputs. Some of them are:
+
+- Read delay distributions from the literature
+- Read and clean case data
+- Validate your line list
+- Describe case data
+
+And this is not the end. After _quantifying transmissibility_ we need to answer more key public health questions like: What is the attack rate we expect? What would be the impact of a given intervention? We can use the reproduction number and other outputs as new inputs for complementary tasks. For example:
+
+- Estimate severity
+- Create short-term forecast
+- Simulate transmission scenarios
+- Compare interventions
+
+So, all these tasks can be interconnected in a pipeline:
+
+![The outbreak analytics pipeline.](https://epiverse-trace.github.io/task_pipeline-minimal.svg)
+
+## What can we do?
+
+Our strategy is gradually incorporating specialised R packages into our traditional analysis pipeline. These packages should fill the gaps in these epidemiology-specific tasks in response to outbreaks. 
+
+Epiverse-TRACE's aim is to provide a software ecosystem for outbreak analytics. We support the development of software pieces, make the existing ones interoperable for the user experience, and stimulate a community of practice.
+
+![](fig/pkgs-hexlogos.png)
+
+
+
+## How can I start?
+
+Our plan for these tutorials is to introduce key solutions from packages in all the tasks before and after the _Quantify transmission_ task, plus the required theory concepts to interpret modelling outputs and make rigorous conclusions.
+
+- In the first set of episodes, you will learn how to optimise the reading of delay distributions and cleaning of case data to input them into the _Quantify transmission_ task. These preliminary tasks are the __Early tasks__. These include packages like `{readepi}`, `{cleanepi}`, `{linelist}`, `{epiparameter}`, and `{episoap}`.
+
+- Then, we will get deeper into the packages and required theory to _Quantify transmission_ and perform more real-time analysis tasks next to it. These are the __Middle tasks__. This includes `{EpiNow2}`, `{cfr}`, `{epichains}`, and `{superspreading}`.
+
+- Lastly, we will use _Quantify transmission_ data outputs to compare it to other indicators and simulate epidemic scenarios as part of the __Late tasks__. This includes `{finalsize}`, `{epidemics}`, and `{scenarios}`.
+
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- Our vision is to have pipelines of R packages for outbreak analytics.
+- Our strategy is to create interconnected tasks to get relevant outputs for public health questions.
+- We plan to introduce package solutions and theory bits for each of the tasks in the outbreak analytics pipeline.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
diff --git a/md5sum.txt b/md5sum.txt
@@ -1,15 +1,17 @@
 "file" "checksum" "built" "date"
-"CODE_OF_CONDUCT.md" "549f00b0992a7743c2bc16ea6ce3db57" "site/built/CODE_OF_CONDUCT.md" "2024-01-24"
-"LICENSE.md" "14377518ee654005a18cf28549eb30e3" "site/built/LICENSE.md" "2024-01-24"
-"config.yaml" "e7d8953245f9f9de37bb72649e2448f9" "site/built/config.yaml" "2024-01-24"
-"index.md" "adfca1a79e0106ee8b3f7731d0678b59" "site/built/index.md" "2024-01-24"
-"links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-01-24"
-"episodes/simulating-transmission.Rmd" "957e9471afa392a97da1551ce4a3b572" "site/built/simulating-transmission.md" "2024-01-24"
-"episodes/model-choices.Rmd" "937efd9fb7e05546ea4fbcb652e59ce9" "site/built/model-choices.md" "2024-01-24"
-"episodes/modelling-interventions.Rmd" "258a8c0cc1fe6fbfabc3f90ca0d41a36" "site/built/modelling-interventions.md" "2024-01-24"
-"episodes/compare-interventions.Rmd" "f5ffe39d7728f03fb8cbe5efade69501" "site/built/compare-interventions.md" "2024-01-24"
-"instructors/instructor-notes.md" "ca3834a1b0f9e70c4702aa7a367a6bb5" "site/built/instructor-notes.md" "2024-01-24"
-"learners/reference.md" "de73c95256f9030b72ac9d56ff91cfe6" "site/built/reference.md" "2024-01-24"
+"CODE_OF_CONDUCT.md" "549f00b0992a7743c2bc16ea6ce3db57" "site/built/CODE_OF_CONDUCT.md" "2024-01-25"
+"LICENSE.md" "14377518ee654005a18cf28549eb30e3" "site/built/LICENSE.md" "2024-01-25"
+"config.yaml" "fb7af8b838bc9c1b45fbf7f2b8ece35d" "site/built/config.yaml" "2024-01-25"
+"index.md" "adfca1a79e0106ee8b3f7731d0678b59" "site/built/index.md" "2024-01-25"
+"links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-01-25"
+"episodes/introduction.Rmd" "2f3ca852c76f3453045a1483a01a7341" "site/built/introduction.md" "2024-01-25"
+"episodes/read-delays.Rmd" "2a79e15a5f4407666ce2d34400e67c3e" "site/built/read-delays.md" "2024-01-25"
+"episodes/simulating-transmission.Rmd" "957e9471afa392a97da1551ce4a3b572" "site/built/simulating-transmission.md" "2024-01-25"
+"episodes/model-choices.Rmd" "937efd9fb7e05546ea4fbcb652e59ce9" "site/built/model-choices.md" "2024-01-25"
+"episodes/modelling-interventions.Rmd" "258a8c0cc1fe6fbfabc3f90ca0d41a36" "site/built/modelling-interventions.md" "2024-01-25"
+"episodes/compare-interventions.Rmd" "f5ffe39d7728f03fb8cbe5efade69501" "site/built/compare-interventions.md" "2024-01-25"
+"instructors/instructor-notes.md" "ca3834a1b0f9e70c4702aa7a367a6bb5" "site/built/instructor-notes.md" "2024-01-25"
+"learners/reference.md" "e5afb2306616baebf32332d6abaaf011" "site/built/reference.md" "2024-01-25"
 "learners/setup.md" "9030a5d0d8e636cb89ee8d48e864469e" "site/built/setup.md" "2024-01-25"
-"profiles/learner-profiles.md" "31b503c4b5bd1f0960ada730eca4a25e" "site/built/learner-profiles.md" "2024-01-24"
-"renv/profiles/lesson-requirements/renv.lock" "35ea7aa2979c577445bad81ae7866d90" "site/built/renv.lock" "2024-01-24"
+"profiles/learner-profiles.md" "31b503c4b5bd1f0960ada730eca4a25e" "site/built/learner-profiles.md" "2024-01-25"
+"renv/profiles/lesson-requirements/renv.lock" "e9d81f4d68b526854aa1fe63f5bb68e7" "site/built/renv.lock" "2024-01-25"
diff --git a/model-choices.md b/model-choices.md
@@ -149,8 +149,7 @@ Consider the following questions:
 
 A deterministic SEIR model with age specific direct transmission. 
 
-<!--html_preserve--><div class="grViz html-widget html-fill-item" id="htmlwidget-1f76c8c4de9e6eab6bae" style="width:504px;height:504px;"></div>
-<script type="application/json" data-for="htmlwidget-1f76c8c4de9e6eab6bae">{"x":{"diagram":"digraph {\n\n  # graph statement\n  #################\n  graph [layout = dot,\n         rankdir = LR,\n         overlap = true,\n         fontsize = 10]\n\n  # nodes\n  #######\n  node [shape = square,\n       fixedsize = true\n       width = 1.3]\n\n       S\n       E\n       I\n       R\n\n  # edges\n  #######\n  S -> E [label = \" infection \n(transmissibility &beta;)\"]\n  E -> I [label = \" onset of infectiousness \n(infectiousness rate &alpha;)\"]\n  I -> R [label = \" recovery \n(recovery rate &gamma;)\"]\n\n}","config":{"engine":"dot","options":null}},"evals":[],"jsHooks":[]}</script><!--/html_preserve-->
+<img src="fig/model-choices-rendered-diagram-1.png" style="display: block; margin: auto;" />
 
 
 The model is capable of predicting an Ebola type outbreak, but as the model is deterministic, we are not able to explore stochastic variation in the early stages of the outbreak.
@@ -169,8 +168,7 @@ The key parameters affecting the transition between states are:
 
 **Note: the functional relationship between the preinfectious  period ($\rho^E$) and the transition rate between exposed and infectious ($\gamma^E$) is $\rho^E = k^E/\gamma^E$ where $k^E$ is the shape of the Erlang distribution. Similarly for the infectious period $\rho^I = k^I/\gamma^I$. See [here](https://epiverse-trace.github.io/epidemics/articles/ebola_model.html#details-discrete-time-ebola-virus-disease-model) for more detail on the stochastic model formulation. ** 
 
-<!--html_preserve--><div class="grViz html-widget html-fill-item" id="htmlwidget-0307111a07767ecfc910" style="width:504px;height:504px;"></div>
-<script type="application/json" data-for="htmlwidget-0307111a07767ecfc910">{"x":{"diagram":"digraph {\n\n  # graph statement\n  #################\n  graph [layout = dot,\n  rankdir = LR,\n  overlap = true,\n  fontsize = 10]\n\n  # nodes\n  #######\n  node [shape = square,\n       fixedsize = true\n       width = 1.3]\n\n       S\n       E\n       I\n       H\n       F\n       R\n\n  # edges\n  #######\n  S -> E [label = \" infection (&beta;)\"]\n  E -> I [label = \" onset of \ninfectiousness (&gamma; E)\"]\n  I -> F [label = \" death (funeral) \n(&gamma; I)\"]\n  F -> R [label = \" safe burial (one timestep) \"]\n  I -> H [label = \" hospitalisation (p hosp)\"]\n  H -> R [label = \" recovery or safe burial \n (&gamma; I)\"]\n\n  subgraph {\n    rank = same; I; F;\n  }\n  subgraph {\n    rank = same; H; R;\n  }\n}","config":{"engine":"dot","options":null}},"evals":[],"jsHooks":[]}</script><!--/html_preserve-->
+<img src="fig/model-choices-rendered-unnamed-chunk-1-1.png" style="display: block; margin: auto;" />
 
 The model has additional parameters describing the transmission risk in hospital and funeral settings: