From 4ab7fcf24d711835b5915dc8a9f650a66e2e25fe Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Mon, 29 Apr 2024 20:09:36 +0100 Subject: [PATCH 01/10] update installation steps + alternatives (#55) --- learners/setup.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index 8d3613f0..0b0de8c4 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -112,11 +112,66 @@ new_packages <- c( "tidyverse" ) -pak::pak(new_packages) +pak::pkg_install(new_packages) ``` These installation steps could ask you `? Do you want to continue (Y/n)` write `Y` and press Enter. +::::::::::::::::::::::::::::: spoiler + +### do you get an error with epiverse-trace packages? + +If you get an error message when installing {epiparameter}, try this alternative code: + +```r +# for epiparameter +install.packages("epiparameter", repos = c("https://epiverse-trace.r-universe.dev")) +``` + +::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::: spoiler + +### What to do if an Error persist? + +If the error message keyword include an string like `Personal access token (PAT)`, you may need to [set up your GitHub token](https://epiverse-trace.github.io/git-rstudio-basics/02-setup.html#set-up-your-github-token). + +First, install these R packages: + +```r +if(!require("pak")) install.packages("pak") + +new <- c("gh", + "gitcreds", + "usethis") + +pak::pak(new) +``` + +Then, follow these three steps to [set up your GitHub token (read this step-by-step guide)](https://epiverse-trace.github.io/git-rstudio-basics/02-setup.html#set-up-your-github-token): + +```r +# Generate a token +usethis::create_github_token() + +# Configure your token +gitcreds::gitcreds_set() + +# Get a situational report +usethis::git_sitrep() +``` + +Try again installing {epiparameter}: + +```r +if(!require("remotes")) install.packages("remotes") +remotes::install_github("epiverse-trace/epiparameter") +``` + +If the error persist, [contact us](#your-questions)! + +::::::::::::::::::::::::::: + You should update **all of the packages** required for the tutorial, even if you installed them relatively recently. New versions bring improvements and important bug fixes. When the installation has finished, you can try to load the packages by pasting the following code into the console: From c208b8ae1a016e7a5fa43c6046ab471e15113e74 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Mon, 29 Apr 2024 20:43:04 +0100 Subject: [PATCH 02/10] rearrange + make epinow() in one line (#56 # 58) --- episodes/quantify-transmissibility.Rmd | 64 +++++++++++--------------- 1 file changed, 26 insertions(+), 38 deletions(-) diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index e858179b..b9e5f45f 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -324,6 +324,10 @@ To find the maximum number of available cores on your machine, use `parallel::de :::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::: checklist + +**Note:** In the code below `_fixed` distributions are used instead of `_variable` (delay distributions with uncertainty). This is to speed up computation time. It is generally recommended to use variable distributions that account for additional uncertainty. + ```{r, echo = FALSE} rt_log_mean <- convert_to_logmean(2, 1) rt_log_sd <- convert_to_logsd(2, 1) @@ -346,50 +350,35 @@ 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.* - -::::::::::::::::::::::::::::::::: spoiler - -### On reducing computation time - -Using an appropriate number of samples and chains is crucial for ensuring convergence and obtaining reliable estimates in Bayesian computations using Stan. Inadequate sampling or insufficient chains may lead to issues such as divergent transitions, impacting the accuracy and stability of the inference process. +::::::::::::::::::::::::: -For the purpose of this tutorial, we can add more configuration details to get an useful output in less time. You can specify a fixed number of `samples` and `chains` to the `stan` argument using the `stan_opts()` function: +Now you are ready to run `EpiNow2::epinow()` to estimate the time-varying reproduction number: -The code in the proposed code chunk can take around 10 minutes. We expect this alternative code chunk below using `stan_opts()` to take approximately 3 minutes: +```{r, message = FALSE, eval = TRUE} +reported_cases <- cases[1:90, ] -```{r,eval=FALSE} estimates <- epinow( - # same code as previous chunk + # cases reported_cases = reported_cases, + # delays generation_time = generation_time_opts(generation_time_fixed), - delays = delay_opts( - incubation_period_fixed + reporting_delay_fixed - ), - rt = rt_opts( - prior = list(mean = rt_log_mean, sd = rt_log_sd) - ), - # [new] set a fixed number of samples and chains + delays = delay_opts(incubation_period_fixed + reporting_delay_fixed), + # prior + rt = rt_opts(prior = list(mean = rt_log_mean, sd = rt_log_sd)), + # computation (optional) stan = stan_opts(samples = 1000, chains = 3) ) ``` -::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::::::::::: callout -```{r, message = FALSE, eval = TRUE} -reported_cases <- cases[1:90, ] +### Do not wait for this to continue -estimates <- epinow( - reported_cases = reported_cases, - generation_time = generation_time_opts(generation_time_fixed), - delays = delay_opts( - incubation_period_fixed + reporting_delay_fixed - ), - rt = rt_opts( - prior = list(mean = rt_log_mean, sd = rt_log_sd) - ) -) -``` +Using `stan = stan_opts()` is optional. For the purpose of this tutorial on reducing computation time, we specified a fixed number of `samples = 1000` and `chains = 3` to the `stan` argument using the `stan_opts()` function. We expect this to take approximately 3 minutes. + +**Remember:** Using an appropriate number of *samples* and *chains* is crucial for ensuring convergence and obtaining reliable estimates in Bayesian computations using Stan. Inadequate sampling or insufficient chains may lead to issues such as divergent transitions, impacting the accuracy and stability of the inference process. + +::::::::::::::::::::::::::::::::: ### Results @@ -466,14 +455,13 @@ To find regional estimates, we use the same inputs as `epinow()` to the function ```{r, message = FALSE, eval = TRUE} estimates_regional <- regional_epinow( + # cases reported_cases = regional_cases, + # delays generation_time = generation_time_opts(generation_time_fixed), - delays = delay_opts( - incubation_period_fixed + reporting_delay_fixed - ), - rt = rt_opts( - prior = list(mean = rt_log_mean, sd = rt_log_sd) - ) + delays = delay_opts(incubation_period_fixed + reporting_delay_fixed), + # prior + rt = rt_opts(prior = list(mean = rt_log_mean, sd = rt_log_sd)) ) estimates_regional$summary$summarised_results$table From 01ad36c83f584ac0bb8bd497beeb5f2946587fec Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Mon, 29 Apr 2024 20:48:33 +0100 Subject: [PATCH 03/10] fix the package input after introduction (#60) --- episodes/quantify-transmissibility.Rmd | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index b9e5f45f..606971d8 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -4,12 +4,6 @@ teaching: 30 exercises: 0 --- -```{r setup, echo = FALSE, warning = FALSE, message = FALSE} -library(EpiNow2) -library(ggplot2) -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? @@ -77,13 +71,14 @@ In the ["`Expected change in daily cases`" callout](#expected-change-in-daily-ca :::::::::::::::::::::::::::::::::::::::::::::::: +In this tutorial we are going to learn how to use the `{EpiNow2}` package to estimate the time-varying reproduction number. We’ll use the `{dplyr}` package to arrange some of its inputs, `{ggplot2}` to visualize case distribution, and the pipe `%>%` to connect some of their functions, so let’s also call to the `{tidyverse}` package: -The first step is to load the `{EpiNow2}` package: - -```{r, eval = FALSE} +```{r,message=FALSE,warning=FALSE} library(EpiNow2) +library(tidyverse) ``` + :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor This tutorial illustrates the usage of `epinow()` to estimate the time-varying reproduction number and infection times. Learners should understand the necessary inputs to the model and the limitations of the model output. From ff68a316f5c4c927d4b58b6079af3def445082a3 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Mon, 29 Apr 2024 20:57:42 +0100 Subject: [PATCH 04/10] add namespace reminder (#63) --- episodes/delays-reuse.Rmd | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/episodes/delays-reuse.Rmd b/episodes/delays-reuse.Rmd index 1a560961..efbe9b52 100644 --- a/episodes/delays-reuse.Rmd +++ b/episodes/delays-reuse.Rmd @@ -196,6 +196,16 @@ epiparameter::epidist_db( ) ``` +::::::::::::::::::: checklist + +### The double-colon + +The double-colon `::` in R is used to access functions or objects from a specific package without loading the entire package into the current environment. This allows for a more targeted approach to using package components and helps avoid namespace conflicts. + +`::` lets you call a specific function from a package by explicitly mentioning the package name. For example, `dplyr::filter(data, condition)` uses `filter()` from the `{dplyr}` package without loading the entire package. + +::::::::::::::::::: + From the `{epiparameter}` package, we can use the `epidist_db()` function to ask for any `disease` and also for a specific epidemiological distribution (`epi_dist`). Let's ask now how many parameters we have in the epidemiological distributions database (`epidist_db`) with the generation time using the string `generation`: From a4fc535cffa52eedd610a5beb46c4d523b26e433 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Mon, 29 Apr 2024 21:03:51 +0100 Subject: [PATCH 05/10] add rtools installation for epinow2 (#65) --- learners/setup.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/learners/setup.md b/learners/setup.md index 0b0de8c4..e8886ebd 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -119,6 +119,22 @@ These installation steps could ask you `? Do you want to continue (Y/n)` write ` ::::::::::::::::::::::::::::: spoiler +### do you get an error with EpiNow2? + +Windows users will need a working installation of `Rtools` in order to build the package from source. `Rtools` is not an R package, but a software you need to download and install. We suggest you to follow [these steps](http://jtleek.com/modules/01_DataScientistToolbox/02_10_rtools/#1): + +1. Download the `Rtools` installer from +2. Install `Rtools` with default selections + +To verify your installation follow these two steps: + +3. Install `{devtools}` --> `install.packages("devtools")` +4. Verify Rtools installation with --> `devtools::find_rtools()` + +::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::: spoiler + ### do you get an error with epiverse-trace packages? If you get an error message when installing {epiparameter}, try this alternative code: From 918702887e8a00806f5b4e2f5c9737cda603e402 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Sat, 4 May 2024 02:02:50 +0100 Subject: [PATCH 06/10] add double colon reminder after all intros --- episodes/delays-functions.Rmd | 10 ++++++++++ episodes/quantify-transmissibility.Rmd | 23 +++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/episodes/delays-functions.Rmd b/episodes/delays-functions.Rmd index 978ce141..d2ec11a2 100644 --- a/episodes/delays-functions.Rmd +++ b/episodes/delays-functions.Rmd @@ -86,6 +86,16 @@ library(tidyverse) withr::local_options(list(mc.cores = 4)) ``` +::::::::::::::::::: checklist + +### The double-colon + +The double-colon `::` in R is used to access functions or objects from a specific package without loading the entire package into the current environment. This allows for a more targeted approach to using package components and helps avoid namespace conflicts. + +`::` lets you call a specific function from a package by explicitly mentioning the package name. For example, `dplyr::filter(data, condition)` uses `filter()` from the `{dplyr}` package without loading the entire package. + +::::::::::::::::::: + ## Distribution functions In R, all the statistical distributions have functions to access the following: diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index 606971d8..96b9011b 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -50,6 +50,29 @@ To estimate these key metrics using case data we must account for delays between 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). +In this tutorial we are going to learn how to use the `{EpiNow2}` package to estimate the time-varying reproduction number. We’ll use the `{dplyr}` package to arrange some of its inputs, `{ggplot2}` to visualize case distribution, and the pipe `%>%` to connect some of their functions, so let’s also call to the `{tidyverse}` package: + +```{r,message=FALSE,warning=FALSE} +library(EpiNow2) +library(tidyverse) +``` + +::::::::::::::::::: checklist + +### The double-colon + +The double-colon `::` in R is used to access functions or objects from a specific package without loading the entire package into the current environment. This allows for a more targeted approach to using package components and helps avoid namespace conflicts. + +`::` lets you call a specific function from a package by explicitly mentioning the package name. For example, `dplyr::filter(data, condition)` uses `filter()` from the `{dplyr}` package without loading the entire package. + +::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor + +This tutorial illustrates the usage of `epinow()` to estimate the time-varying reproduction number and infection times. Learners should understand the necessary inputs to the model and the limitations of the model output. + +:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::::::::::: callout ### Bayesian inference From 6f5b73ebf6edb2d2134f58c59d118f7b95b11663 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Sat, 4 May 2024 02:03:54 +0100 Subject: [PATCH 07/10] relocate bayesian callout after intro --- episodes/quantify-transmissibility.Rmd | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index 96b9011b..cf9cff65 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -94,20 +94,6 @@ In the ["`Expected change in daily cases`" callout](#expected-change-in-daily-ca :::::::::::::::::::::::::::::::::::::::::::::::: -In this tutorial we are going to learn how to use the `{EpiNow2}` package to estimate the time-varying reproduction number. We’ll use the `{dplyr}` package to arrange some of its inputs, `{ggplot2}` to visualize case distribution, and the pipe `%>%` to connect some of their functions, so let’s also call to the `{tidyverse}` package: - -```{r,message=FALSE,warning=FALSE} -library(EpiNow2) -library(tidyverse) -``` - - -:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor - -This tutorial illustrates the usage of `epinow()` to estimate the time-varying reproduction number and infection times. Learners should understand the necessary inputs to the model and the limitations of the model output. - -:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: - ## Delay distributions and case data ### Case data From 94390f099090b3efe5db2c7f4e0224f7c4fadd89 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Sat, 4 May 2024 02:55:45 +0100 Subject: [PATCH 08/10] update installation code for rtools (#65) --- learners/setup.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index e8886ebd..13df09ad 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -121,18 +121,31 @@ These installation steps could ask you `? Do you want to continue (Y/n)` write ` ### do you get an error with EpiNow2? -Windows users will need a working installation of `Rtools` in order to build the package from source. `Rtools` is not an R package, but a software you need to download and install. We suggest you to follow [these steps](http://jtleek.com/modules/01_DataScientistToolbox/02_10_rtools/#1): +Windows users will need a working installation of `Rtools` in order to build the package from source. `Rtools` is not an R package, but a software you need to download and install. We suggest you to follow: -1. Download the `Rtools` installer from -2. Install `Rtools` with default selections + -To verify your installation follow these two steps: +1. **Verify `Rtools` installation**. You can do so by using Windows search across your system. Optionally, you can use `{devtools}` running: -3. Install `{devtools}` --> `install.packages("devtools")` -4. Verify Rtools installation with --> `devtools::find_rtools()` +```r +if(!require("devtools")) install.packages("devtools") +devtools::find_rtools() +``` + +If the result is `FALSE`, then you should do step 2. + +2. **Install `Rtools`**. Download the `Rtools` installer from . Install with default selections. + +3. **Verify `Rtools` installation**. Again, we can use `{devtools}`: + +```r +if(!require("devtools")) install.packages("devtools") +devtools::find_rtools() +``` ::::::::::::::::::::::::::::: + ::::::::::::::::::::::::::::: spoiler ### do you get an error with epiverse-trace packages? From 76bcafa84359609cdeadb0065bf40420071f3698 Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Sat, 4 May 2024 04:04:19 +0100 Subject: [PATCH 09/10] make chunk visible to learner --- episodes/quantify-transmissibility.Rmd | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index cf9cff65..d2acffb9 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -332,26 +332,17 @@ To find the maximum number of available cores on your machine, use `parallel::de **Note:** In the code below `_fixed` distributions are used instead of `_variable` (delay distributions with uncertainty). This is to speed up computation time. It is generally recommended to use variable distributions that account for additional uncertainty. -```{r, echo = FALSE} -rt_log_mean <- convert_to_logmean(2, 1) -rt_log_sd <- convert_to_logsd(2, 1) - -incubation_period_fixed <- dist_spec( - mean = 4, sd = 2, - max = 20, distribution = "gamma" +```{r, echo = TRUE} +# fixed alternatives +generation_time_fixed <- dist_spec( + mean = 3.6, sd = 3.1, + max = 20, distribution = "lognormal" ) -log_mean <- convert_to_logmean(2, 1) -log_sd <- convert_to_logsd(2, 1) reporting_delay_fixed <- dist_spec( mean = log_mean, sd = log_sd, max = 10, distribution = "lognormal" ) - -generation_time_fixed <- dist_spec( - mean = 3.6, sd = 3.1, - max = 20, distribution = "lognormal" -) ``` ::::::::::::::::::::::::: From 8487425bc9ef1941efc57df34d97cd1261b7d96c Mon Sep 17 00:00:00 2001 From: Andree Valle Campos Date: Sat, 4 May 2024 04:10:13 +0100 Subject: [PATCH 10/10] activate the rt priors chunk --- episodes/quantify-transmissibility.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/quantify-transmissibility.Rmd b/episodes/quantify-transmissibility.Rmd index d2acffb9..0515845f 100644 --- a/episodes/quantify-transmissibility.Rmd +++ b/episodes/quantify-transmissibility.Rmd @@ -307,7 +307,7 @@ The function `epinow()` is a wrapper for the function `estimate_infections()` us There are numerous other inputs that can be passed to `epinow()`, see `EpiNow2::?epinow()` for more detail. One optional input is to specify a log normal prior for the effective reproduction number $R_t$ at the start of the outbreak. We specify a mean and standard deviation as arguments of `prior` within `rt_opts()`: -```{r, eval = FALSE} +```{r, eval = TRUE} rt_log_mean <- convert_to_logmean(2, 1) rt_log_sd <- convert_to_logsd(2, 1) rt <- rt_opts(prior = list(mean = rt_log_mean, sd = rt_log_sd))