Skip to content

setup.md

Latest commit

 

History

History
273 lines (167 loc) · 11.2 KB

setup.md

File metadata and controls

273 lines (167 loc) · 11.2 KB
title Setup

Motivation

Outbreaks of infectious diseases can appear as a result of different pathogens, and in different contexts, but they typically lead to similar public health questions, from understanding patterns of transmission and severity to examining the effect of control measures (Cori et al. 2017). We can relate each of these public health questions to a series of outbreak data analysis tasks. The more efficiently and reliably we can perform these tasks, the faster and more accurately we can answer the underlying questions.

Epiverse-TRACE aims to provide a software ecosystem for outbreak analytics with integrated, generalisable and scalable community-driven software. We support the development of new R packages, help link together existing tools to make them more user-friendly, and contribute to a community of practice, spanning field epidemiologists, data scientists, lab researchers, health agency analysts, software engineers and more.

Epiverse-TRACE tutorials

Our tutorials are built around an outbreak analysis pipeline split into three stages: Early tasks, Middle tasks and Late tasks. The outputs of tasks completed in earlier stages commonly feed into the tasks required for later ones.

An overview of the tutorial topics

Each task has its tutorial website and each tutorial website consists of a set of episodes covering different topics.

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 the objectives of the episode.
  • Prerequisites: describes what episodes/packages ideally need to be covered before the current episode.
  • Example R code: example R code so you can work through the episodes on your own computer.
  • Challenges: challenges that can be completed to test your understanding.
  • Explainers: boxes to enhance your understanding of mathematical and modelling concepts.

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)

:::::::::::::::::::::::::::: prereq

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

::::::::::::::::::::::::::::: callout

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.

::::::::::::::::::::::::::::: callout

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. Check and Install Build Tools

Some packages require a complementary set of tools to build them. 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:

if(!require("pkgbuild")) install.packages("pkgbuild")
pkgbuild::check_build_tools(debug = TRUE)

We expect a message like the one below:

Your system is ready to build packages!

If the build tools are not available, this will trigger an automated install.

  1. Run the command in the console.
  2. Don’t interrupt it—wait until R prints the confirmation message.
  3. Once that’s done, restart your R session (or just restart RStudio) to ensure the changes take effect.

If the automatic installation does not work, you can manually install them according to your operating system.

::::::::::::::::::::::::::::: tab

Windows

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:

Mac

Mac users require two additional steps as detailed in this guide to Configuring C Toolchain for Mac:

  • Install and use macrtools to setup the C++ toolchain
  • Enable some compiler optimizations.

Linux

Linux users require specific details per distribution. Find them in this guide to Configuring C Toolchain for Linux.

:::::::::::::::::::::::::::::

::::::::::::: callout

Environment Check

This step requires administrator privileges to install software.

If you do not have admin rights in your current environment:

  • Try running the tutorial on your personal machine where you have full access.
  • Use a preconfigured development environment (e.g. Posit Cloud).
  • Ask your system administrator to install the required software for you.

:::::::::::::

3. 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:

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

new_packages <- c(
  "socialmixr",
  "finalsize",
  "epiverse-trace/epidemics",
  "epiparameter",
  "scales",
  "tidyverse"
)

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 {epidemics}?

If you get an error message when installing {epidemics}, try this alternative code:

install.packages("epidemics", repos = c("https://epiverse-trace.r-universe.dev", "https://cloud.r-project.org"))

:::::::::::::::::::::::::::::

::::::::::::::::::::::::::: spoiler

Do you need a GitHub Personal access token (PAT)?

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:

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

# Generate a token
usethis::create_github_token()

# Configure your token 
gitcreds::gitcreds_set()

# Get a situational report
usethis::git_sitrep()

Try again installing {epiparameter}:

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

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.

4. Verify the installation

When the installation has finished, you can try to load the packages by pasting the following code into the console:

library(socialmixr)
library(finalsize)
library(epidemics)
library(epiparameter)
library(scales)
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 andree.valle-campos@lshtm.ac.uk