Summary and Schedule

This is an Epiverse-TRACE tutorial built with The Carpentries Workbench.

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

Motivation

Outbreaks appear with different diseases and in different contexts, but what all of them have in common is the key public health questions (Cori et al. 2017). We can relate these key public health questions to outbreak data analysis tasks.

Epiverse-TRACE aims to provide a software ecosystem for outbreak analytics with integrated, generalisable and scalable community-driven software. We support the development of R packages, make the existing ones interoperable for the user experience, and stimulate a community of practice.

Epiverse-TRACE tutorials

The tutorials are built around an outbreak analysis pipeline split into three stages: Early tasks, Middle tasks and Late tasks.

An overview of the tutorial topics
An overview of the tutorial topics

Each task has its tutorial website. Each tutorial website consists of a set of episodes.

Early task tutorials ➠ Middle task tutorials ➠ Late task tutorials ➠
Read and clean case data, and make linelist Real-time analysis and forecasting Scenario modelling
Read, clean and validate case data, convert linelist data to incidence for visualization. Access delay distributions and estimate transmission metrics, forecast cases, estimate severity and superspreading. Simulate disease spread and investigate interventions.

Each episode contains:

  • Overview: describes what questions will be answered and what are the objectives of the episode.
  • Prerequisites: describes what episodes/packages need to be covered before the current episode.
  • Example R code: work through the episodes on your own computer using the example R code.
  • Challenges: complete challenges to test your understanding.
  • Explainers: add to your understanding of mathematical and modelling concepts with the explainer boxes.

Also check out the glossary for any terms you may be unfamiliar with.

Epiverse-TRACE R packages

Our strategy is to gradually incorporate specialised R packages into a traditional analysis pipeline. These packages should fill the gaps in these epidemiology-specific tasks in response to outbreaks.

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).

Prerequisite

This content assumes intermediate R knowledge. This tutorials are for you if:

  • You can read data into R, transform and reshape data, and make a wide variety of graphs
  • You are familiar with functions from dplyr, tidyr, and ggplot2
  • You can use the magrittr pipe %>% and/or native pipe |>.

We expect learners to have some exposure to basic Statistical, Mathematical and Epidemic theory concepts, but NOT intermediate or expert familiarity with modeling.

Software Setup

Follow these two steps:

1. Install or upgrade R and RStudio

R and RStudio are two separate pieces of software:

  • R is a programming language and software used to run code written in R.
  • RStudio is an integrated development environment (IDE) that makes using R easier. We recommend to use RStudio to interact with R.

To install R and RStudio, follow these instructions https://posit.co/download/rstudio-desktop/.

Already installed?

Hold on: This is a great time to make sure your R installation is current.

This tutorial requires R version 4.0.0 or later.

To check if your R version is up to date:

  • In RStudio your R version will be printed in the console window. Or run sessionInfo() there.

  • To update R, download and install the latest version from the R project website for your operating system.

    • After installing a new version, you will have to reinstall all your packages with the new version.

    • For Windows, the installr package can upgrade your R version and migrate your package library.

  • To update RStudio, open RStudio and click on Help > Check for Updates. If a new version is available follow the instructions on the screen.

Check for Updates regularly

While this may sound scary, it is far more common to run into issues due to using out-of-date versions of R or R packages. Keeping up with the latest versions of R, RStudio, and any packages you regularly use is a good practice.

2. Install the required R packages

Open RStudio and copy and paste the following code chunk into the console window, then press the Enter (Windows and Linux) or Return (MacOS) to execute the command:

R 

# for episodes on access delays and quantify transmission

if(!require("pak")) install.packages("pak")

new_packages <- c(
  "EpiNow2",
  "epiverse-trace/epiparameter",
  "incidence2",
  "tidyverse"
)

pak::pkg_install(new_packages)

R 

# for episodes on forecast and severity

if(!require("pak")) install.packages("pak")

new_packages <- c(
  "EpiNow2",
  "cfr",
  "epiverse-trace/epiparameter",
  "incidence2",
  "outbreaks",
  "tidyverse"
)

pak::pkg_install(new_packages)

R 

# for episodes on superspreading and transmission chains

if(!require("pak")) install.packages("pak")

superspreading_packages <- c(
  "epicontacts",
  "fitdistrplus",
  "epiverse-trace/superspreading",
  "epichains",
  "epiverse-trace/epiparameter",
  "incidence2",
  "outbreaks",
  "tidyverse"
)

pak::pkg_install(superspreading_packages)

These installation steps could ask you ? Do you want to continue (Y/n) write Y and press Enter.

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. Verify Rtools installation. You can do so by using Windows search across your system. Optionally, you can use devtools running:

R 

if(!require("devtools")) install.packages("devtools")
devtools::find_rtools()

If the result is FALSE, then you should do step 2.

  1. Install Rtools. Download the Rtools installer from https://cran.r-project.org/bin/windows/Rtools/. Install with default selections.

  2. Verify Rtools installation. Again, we can use devtools:

R 

if(!require("devtools")) install.packages("devtools")
devtools::find_rtools()

If you get an error message when installing {superspreading}, {epichains}, or {epiparameter}, try this alternative code:

R 

# for superspreading
install.packages("superspreading", repos = c("https://epiverse-trace.r-universe.dev"))

# for epiparameter
install.packages("epiparameter", repos = c("https://epiverse-trace.r-universe.dev"))

# for epichains
install.packages("epichains", repos = c("https://epiverse-trace.r-universe.dev"))

If the error message keyword include an string like Personal access token (PAT), you may need to 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):

R 

# Generate a token
usethis::create_github_token()

# Configure your token 
gitcreds::gitcreds_set()

# Get a situational report
usethis::git_sitrep()

Try again installing a package like {superspreading}:

R 

if(!require("remotes")) install.packages("remotes")
remotes::install_github("epiverse-trace/superspreading")

If the error persist, contact us!

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:

R 

# for episodes on access delays and quantify transmission

library(EpiNow2)
library(epiparameter)
library(incidence2)
library(tidyverse)

R 

# for episodes on forecast and severity

library(EpiNow2)
library(cfr)
library(epiparameter)
library(incidence2)
library(outbreaks)
library(tidyverse)

R 

# for episodes on superspreading and transmission chains

library(epicontacts)
library(fitdistrplus)
library(superspreading)
library(epichains)
library(epiparameter)
library(incidence2)
library(outbreaks)
library(tidyverse)

If you do NOT see an error like there is no package called ‘...’ you are good to go! If you do, contact us!

Data sets

Download the data

We will download the data directly from R during the tutorial. However, if you are expecting problems with the network, it may be better to download the data beforehand and store it on your machine.

The data files for the tutorial can be downloaded manually here:

Your Questions

If you need any assistance installing the software or have any other questions about this tutorial, please send an email to