collect feedback + solve lintr checks

epiverse-trace/tutorials-early#37

Author: avallecam

episodes/quantify-transmissibility.Rmd

@@ -13,7 +13,7 @@ withr::local_options(list(mc.cores = 4))
 :::::::::::::::::::::::::::::::::::::: questions 
 
 - How can I estimate the time-varying reproduction number ($Rt$) and growth rate from a time series of case data?
-- How can I quantify geographical heterogeneity in these transmission metrics? 
+- How can I quantify geographical heterogeneity from these transmission metrics? 
 
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
@@ -28,11 +28,11 @@ withr::local_options(list(mc.cores = 4))
 
 ## Prerequisites
 
-Learners should familiarise themselves with following concept dependencies before working through this tutorial: 
+Learners should familiarise themselves with following concepts before working through this tutorial: 
 
-**Statistics** : probability distributions, principle of Bayesian analysis. 
+**Statistics**: probability distributions, principle of Bayesian analysis. 
 
-**Epidemic theory** : Effective reproduction number.
+**Epidemic theory**: Effective reproduction number.
 
 :::::::::::::::::::::::::::::::::
 
@@ -50,10 +50,9 @@ But in an ongoing outbreak, the population does not remain entirely susceptible
 
 ## Introduction
 
-Quantifying transmission metrics at the start of an outbreak can give important information on the strength of transmission (reproduction number) and the speed of transmission ([growth rate](../learners/reference.md#growth), doubling/halving time). To estimate these key metrics using case data we must account for delays between the date of infections and date of reported cases. In an outbreak situation, data are usually available on reported dates only, therefore we must use estimation methods to account for these delays when trying to understand changes in transmission over time. 
+The transmission intensity of an outbreak is quantified using two key metrics: the reproduction number, which informs on the strength of the transmission by indicating how many new cases are expected from each existing case; and the [growth rate](../learners/reference.md#growth), which informs on the speed of the transmission by indicating how rapidly the outbreak is spreading or declining (doubling/halving time) within a population. To estimate these key metrics using case data we must account for delays between the date of infections and date of reported cases. In an outbreak situation, data are usually available on reported dates only, therefore we must use estimation methods to account for these delays when trying to understand changes in transmission over time. For more details on the distinction between speed and strength of transmission and implications for control, see [Dushoff & Park, 2021](https://royalsocietypublishing.org/doi/full/10.1098/rspb.2020.1556).
 
-In the next tutorials we will focus on how to implement the functions in `{EpiNow2}` to estimate transmission metrics of case data. We will not cover the theoretical background of the models or inference framework, for details on these concepts see the [vignette](https://epiforecasts.io/EpiNow2/dev/articles/estimate_infections.html).
-For more details on the distinction between speed and strength of transmission and implications for control, see [Dushoff & Park, 2021](https://royalsocietypublishing.org/doi/full/10.1098/rspb.2020.1556).
+In the next tutorials we will focus on how to use the functions in `{EpiNow2}` to estimate transmission metrics of case data. We will not cover the theoretical background of the models or inference framework, for details on these concepts see the [vignette](https://epiforecasts.io/EpiNow2/dev/articles/estimate_infections.html).
 
 
 ::::::::::::::::::::::::::::::::::::: callout
@@ -70,14 +69,14 @@ In Bayesian inference, we use prior knowledge (prior distributions) with data (i
 
 :::::::::::::::::::::::::::::::::::::::::::::::: instructor
 
-We refer to the Prior probability distribution and the [Posterior probability](https://en.wikipedia.org/wiki/Posterior_probability) distribution.
+Refer to the prior probability distribution and the [posterior probability](https://en.wikipedia.org/wiki/Posterior_probability) distribution.
 
-Lines below, in the "`Expected change in daily cases`" callout, by "the posterior probability that $R_t < 1$", we refer specifically to the [area under the posterior probability distribution curve](https://www.nature.com/articles/nmeth.3368/figures/1). 
+In the ["`Expected change in daily cases`" callout](#expected-change-in-daily-cases), by "the posterior probability that $R_t < 1$", we refer specifically to the [area under the posterior probability distribution curve](https://www.nature.com/articles/nmeth.3368/figures/1). 
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 
-The first step is to load the `{EpiNow2}` package :
+The first step is to load the `{EpiNow2}` package:
 
 ```{r, eval = FALSE}
 library(EpiNow2)
@@ -101,31 +100,46 @@ dplyr::as_tibble(incidence2::covidregionaldataUK)
 
 To use the data, we must format the data to have two columns:
 
-+ `date` : the date (as a date object see `?is.Date()`),
-+ `confirm` : number of confirmed cases on that date.
++ `date`: the date (as a date object see `?is.Date()`),
++ `confirm`: number of confirmed cases on that date.
 
-Let's use `{tidyr}` and `incidence2::incidence()` for this:
+Let's use `{dplyr}` for this:
 
 ```{r, warning = FALSE, message = FALSE}
+library(dplyr)
+
+cases <- incidence2::covidregionaldataUK %>%
+  select(date, cases_new) %>%
+  group_by(date) %>%
+  summarise(confirm = sum(cases_new, na.rm = TRUE)) %>%
+  ungroup()
+```
+
+::::::::::::::::::::::::: spoiler
+
+### When to use incidence2?
+
+We can also use the `{incidence2}` package to aggregate cases. However, if you ever need to aggregate you data in a different time **interval** (i.e., days, weeks or months) or per **group** categories, we recommend you to explore the `incidence2::incidence()` function:
+
+```{r, warning = FALSE, message = FALSE, eval=FALSE}
 library(tidyr)
 library(dplyr)
 
-cases <- incidence2::covidregionaldataUK %>% 
+incidence2::covidregionaldataUK %>%
   # preprocess missing values
-  tidyr::replace_na(list(cases_new = 0)) %>% 
+  tidyr::replace_na(list(cases_new = 0)) %>%
   # compute the daily incidence
   incidence2::incidence(
     date_index = "date",
     counts = "cases_new",
-    interval = "day",
-    # rename column outputs to fit {EpiNow2} input
-    date_names_to = "date",
-    count_values_to = "confirm"
-  ) %>% 
-  # optional, but does not affect {EpiNow2} input
-  select(-count_variable)
+    groups = "region",
+    interval = "week"
+  )
 ```
 
+You can also estimate transmission metrics from {incidence2} objects using the `{i2extras}` package. Read further in the [Fitting curves](https://www.reconverse.org/i2extras/articles/fitting_epicurves.html) vignette!
+
+:::::::::::::::::::::::::
 
 There are case data available for `r dim(cases)[1]` days, but in an outbreak situation it is likely we would only have access to the beginning of this data set. Therefore we assume we only have the first 90 days of this data. 
 
@@ -140,7 +154,7 @@ ggplot(cases[1:90, ], aes(x = date, y = confirm)) +
 
 
 ### Delay distributions 
-We assume there are delays from the time of infection until the time a case is reported. We specify these delays as distributions to account for the uncertainty in individual level differences. The delay can consist of multiple types of delays/processes. A typical delay from time of infection to case reporting may consist of :
+We assume there are delays from the time of infection until the time a case is reported. We specify these delays as distributions to account for the uncertainty in individual level differences. The delay can consist of multiple types of delays/processes. A typical delay from time of infection to case reporting may consist of:
 
 <p class="text-center" style="background-color: aliceblue">**time from infection to symptom onset** (the [incubation period](../learners/reference.md#incubation)) + **time from symptom onset to case notification** (the reporting time)
 .</p>
@@ -149,7 +163,7 @@ The delay distribution for each of these processes can either estimated from dat
 
 ::::::::::::::::::::::::::::::::::::: callout
 ### Delays and data
-The number of delays and type of delay is a flexible input that depends on the data. The examples below highlight how the delays can be specified for different data sources:
+The number of delays and type of delay are a flexible input that depend on the data. The examples below highlight how the delays can be specified for different data sources:
 
 <center>
 
@@ -168,7 +182,7 @@ The number of delays and type of delay is a flexible input that depends on the d
 
 #### Incubation period distribution 
 
-The distribution of incubation period can usually be obtained from the literature. The package `{epiparameter}` contains a library of epidemiological parameters for different diseases obtained from the literature. 
+The distribution of incubation period for many diseases can usually be obtained from the literature. The package `{epiparameter}` contains a library of epidemiological parameters for different diseases obtained from the literature. 
 
 We specify a (fixed) gamma distribution with mean $\mu = 4$ and standard deviation $\sigma= 2$ (shape = $4$, scale = $1$) using the function `dist_spec()` as follows:
 
@@ -326,7 +340,7 @@ generation_time_fixed <- dist_spec(
 )
 ```
 
-*Note : in the code below fixed distributions are used instead of variable. This is to speed up computation time. It is generally recommended to use variable distributions that account for additional uncertainty.*
+*Note: in the code below fixed distributions are used instead of variable. This is to speed up computation time. It is generally recommended to use variable distributions that account for additional uncertainty.*
 
 ::::::::::::::::::::::::::::::::: spoiler
 
@@ -426,9 +440,9 @@ A factor describing expected change in daily cases based on the posterior probab
 
 The outbreak data of the start of the COVID-19 pandemic from the United Kingdom from the R package `{incidence2}` includes the region in which the cases were recorded. To find regional estimates of the effective reproduction number and cases, we must format the data to have three columns:
 
-+ `date` : the date,
-+ `region` : the region, 
-+ `confirm` : number of confirmed cases for a region on a given date.
++ `date`: the date,
++ `region`: the region, 
++ `confirm`: number of confirmed cases for a region on a given date.
 
 ```{r}
 regional_cases <-
@@ -464,7 +478,7 @@ estimates_regional$summary$plots$R
 
 ## Summary
 
-`EpiNow2` can be used to estimate transmission metrics from case data at the start of an outbreak. The reliability of these estimates depends on the quality of the data and appropriate choice of delay distributions. In the next tutorial we will learn how to make forecasts and investigate some of the additional inference options available in `EpiNow2`. 
+`EpiNow2` can be used to estimate transmission metrics from case data at any time in the course of an outbreak. The reliability of these estimates depends on the quality of the data and appropriate choice of delay distributions. In the next tutorial we will learn how to make forecasts and investigate some of the additional inference options available in `EpiNow2`. 
 
 ::::::::::::::::::::::::::::::::::::: keypoints