Summary and Setup

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

Motivation

Have you ever wondered how cool would it be if you would be able to successfully:

  • Reuse an analysis months or years later each time you need to revisit it?
  • Redo the analyses, figures or tables after correcting an error in the data or following a reviewer’s recommendations?
  • Reuse data from other authors for a secondary analysis thanks to informative metadata on the primary study?

Sadly, most of the time, this isn’t easy because:

  • We do not remember how we did the analysis,
  • Redoing figures and tables is time-consuming,
  • Data is not readily available or unreadable today.

In this lesson, you will learn how to improve your code’s reliability, usability and sustainability for epidemic analysis with R packages. You will learn how to add specific features to your R project to keep it as Open, Reproducible, and Sustainable as possible!

A puzzle of three hexagon pieces, only showing the pieces, each with one of these words: OPEN, SUSTAINABLE, REPRODUCIBLE
Open science, Sustainable software, and Reproducible analysis: Different and Complementary. Image by Bing, 2023, CC BY 4.0, created with Bing Image Creator powered by DALL·E 3

Prerequisite

In this lesson, we will use R, Git, and GitHub. Some previous experience using RStudio projects is expected, but isn’t mandatory.

For an introductory lesson on Git, please go to the Version Control with Git in Rstudio lesson.

Software Setup

Install Rstudio

Install R and Rstudio https://posit.co/download/rstudio-desktop/

Create a GitHub account

Create a GitHub account https://github.com/

Install Git

Follow software specific suggestions

Follow happygitwithr recommendation for each Operating system.

For Windows

For MacOS

For Linux

Install R packages

These installation steps could ask you ? Do you want to continue (Y/n) write y and press ENTER. It can take up to 3 minutes to complete.

First, we strongly suggest to install the development versions of the rcompendium and {rrtools} packages:

R 

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

remotes::install_github("FRBCesab/rcompendium")
remotes::install_github("benmarwick/rrtools")

Then, install all these packages:

R 

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

new <- c("gh",
         "usethis",
         "tidyverse",
         "here",
         "yaml",
         "renv")

pak::pak(new)

Configure Git and GitHub

Follow all these steps

In these steps, we will verify that you have:

  • a correctly configured token, and
  • a clean output when running usethis::git_sitrep().

1. Verify your git configuration

Use gh::gh_whoami() to check if your local git configuration recognizes:

  • your name
  • your GitHub account
  • your token

R 

gh::gh_whoami()

OUTPUT 

{
  "name": "Andree Valle Campos",
  "login": "avallecam",
  "html_url": "https://github.com/avallecam",
  "scopes": "gist, repo, workflow",
  "token": "gho_...AlAn"
}

If there is no name, login, or html_url, then you need to run:

R 

gert::git_config_global_set(name = "user.name",   value = "John Doe")
gert::git_config_global_set(name = "user.email",  value = "john.doe@domain.com")
gert::git_config_global_set(name = "github.user", value = "jdoe")

If you do not have a token, follow step number 3.

2. Get a situational report on your current Git/GitHub status:

Use usethis::git_sitrep() to check if there is no ✖ ... line in the output with an error message.

An example with two errors is below:

R 

usethis::git_sitrep()

ERROR 

✖ Token lacks recommended scopes:
  - 'user:email': needed to read user's email addresses
  Consider re-creating your PAT with the missing scopes.
  `create_github_token()` defaults to the recommended scopes.
✖ Can't retrieve registered email addresses from GitHub.
  Consider re-creating your PAT with the 'user' or at least 'user:email' scope.

The output shows that I had a token but must fix its configuration. If you do not have a token or get a similar error message, follow the next step.

If you have an error message unrelated to creating a token, copy and paste this output in your issue report to the email at the end of this page.

3. Create your GitHub token:

Do this with usethis::create_github_token(). This function should redirect you to GitHub on your browser. Once there, check all the options in the figure below.

R 

usethis::create_github_token()

Check all of the following options:

4. Configure your token

To complete the configuration of your token use gitcreds::gitcreds_set() (Bryan, 2023), then accept that you want to 2: Replace these credentials. Do this by writing the number 2 and press ENTER.

R 

gitcreds::gitcreds_set()

OUTPUT 

-> What would you like to do?

1: Abort update with error, and keep the existing credentials
2: Replace these credentials
3: See the password / token

Selection: 2

Paste your token to save it and complete this step.

5. Run again the situational report:

Verify again that there is no ✖ ... line in the output with an error message. The expected outcome should look like this:

R 

usethis::git_sitrep()

OUTPUT 

Git config (global)
• Name: 'Andree Valle'
• Email: 'avallecam@gmail.com'
• Global (user-level) gitignore file: <unset>
• Vaccinated: FALSE
ℹ See `?git_vaccinate` to learn more
• Default Git protocol: 'https'
• Default initial branch name: 'master'
GitHub
• Default GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': '<discovered>'
• GitHub user: 'avallecam'
• Token scopes: 'delete_repo, gist, repo, user, workflow'
• Email(s): 'avallecam@gmail.com (primary)', 'andree.valle-campos@lshtm.ac.uk'
Git repo for current project
ℹ No active usethis project

If you still have an error, close Rstudio and open it again for changes to take effect.

If the error persist, copy and paste this output in your issue report to the email at the end of this page.

6. Two-factor authentication

If you have an error message related to Two-factor authentication, follow the steps in this GitHub guide.

Configure your R environment

Follow all these steps

1. Set the default Git branch name

Run the code chunk below:

R 

usethis::git_default_branch_configure(name = "main")

This step will homogenize the name of the default branch in our computers. We need this to make some auto-generated links work downstream.

2. Add {rcompendium} credentials

Use rcompendium::set_credentials() to paste your name and personal information to the .Rprofile configuration file.

Adapt the code chunk below to your name, family name, email, and ORCID. Adding your ORCID is optional.

R 

rcompendium::set_credentials(
  given = "Andree",
  family = "Valle-Campos",
  email = "avallecam@gmail.com",
  orcid = "0000-0002-7779-481X"
)

This function will automatically copy a line of code to the clipboard that starts with options(..., and open a file called .Rprofile. Paste the line of code in the file. After this, close Rstudio and open it again for changes to take effect.

You can access the content of the .Rprofile file at any time with usethis::edit_r_profile().

Your Questions

If you need any assistance installing the software, configuring Git and GitHub, or have any other questions about the workshop, please send an email to