Reproducible Analysis and Documentation

Jennifer Huck

10/13/23

Slides Usage Notes

• Press s to view Presenter Notes. You might have to allow pop-ups, and press s again to make this work.

• These slides are licensed as CC-BY.

Before we begin

• Open RStudio. For best participation results, make sure you have updated RStudio to v2022.07 (or higher). To double check your version, go to Help…About RStudio. The version number is in bold at the top.

• Be sure you can find the `penguins-quarto` demo project you downloaded.

Get Ready

• Before the first session, make sure you have installed or updated R and RStudio Installing and updating instructions are here. For best participation results, make sure you have updated RStudio to v2022.07 (or higher). To double check your version, go to Help…About RStudio. The version number is in bold at the top.

  Visit my GitHub Penguins repository and download the repository. This repository contains files for a demo project. Click on the big green “Code” button, then “Download ZIP,” and save it somewhere that you can find on the day of the workshop and unzip the folder.

Learning Objectives

In this workshop, you will learn:

• How to use RStudio Projects and why you would want to
• What R Markdown and Quarto documents are and why you would want to use them

Note: This is not a complete workshop on how to use the many options provided within R Markdown or Quarto documents. We will cover some details, but not all.

Why a project-oriented workflow?

Working with projects allows you to:

• Work on more than one project at a time
• Easily distribute and collaborate on projects
• Easily stop and pick up where you left off

(spaces for notes)

References: (Pileggi, Bryan, and Aja 2022)

How to do a project-oriented workflow?

Use:

• A dedicated directory
• RStudio Projects
• Git repo

We will get into the how of using a dedicated directory and RStudio Projects. We won’t get into Git/GitHub repositories today.

References: (Pileggi, Bryan, and Aja 2022)

Project-oriented workflow with RStudio Projects

What not to do: setwd() and rm(list = ls())

A lot of R scripts start off like this:

setwd("C:/Users/jah2ax.ESERVICES/Box Sync/_R/research/penguins")

You might also see:

rm(list = ls())

Fortunately, a project-oriented workflow designs this away.

The working directory is the place that R looks for your files. There is always one set. You can check with getwd().

A lot of R scripts start off like this:

setwd("C:/Users/jah2ax.ESERVICES/Box Sync/_R/research/penguins")

It uses the setwd() function to set the working directory. The problem with this is that there is a 0% chance that this will work on someone else’s computer, and will very likely break on your computer if (and when) you move your directory around. setwd() is fragile - it breaks! If you actually want this to work on someone else’s computer - like an advisor or a collaborator - then that line of code is not going to do it’s job (i.e., set the working directory to the proper folder) because the path won’t be any good on the other person’s computer. Same is true if you move your files around. This is annoying for everyone!

Similarly, you may have seen this line, often at the top of scripts: rm(list = ls()). That line is good at removing objects from your environment, but doesn’t give your a fresh R process, specifically, rm(list = ls()) does not detach libraries. There is a better way!

References: [Bryan and Hester (n.d.a)](Bryan and Hester, n.d.b)(Wickham and Grolemund, n.d.)

What persists after rm(list=ls())?

Option	Persists? (Y/N)
library(dplyr)
summary <- head
options(stringsAsFactors = FALSE)
Sys.setenv(LANGUAGE = “fr”)
x <- 1:5
attach(iris)

Examples taken from Pileggi 2022

(space for notes)

References: (Pileggi, Bryan, and Aja 2022)

What persists after rm(list=ls())?

Option	Persists?
library(dplyr)	Yes
summary <- head	No
options(stringsAsFactors = FALSE)	Yes
Sys.setenv(LANGUAGE = “fr”)	Yes
x <- 1:5	No
attach(iris)	Yes

Examples taken from Pileggi 2022

The objects go away, but libraries, options, and other settings all remain.

References: (Pileggi, Bryan, and Aja 2022)

Organize work into projects

AKA “little p projects”

1. Use a single directory for your research project
2. Set working directory in R to that main directory
3. Use relative paths

Aka “little p projects.”

First, let’s make sure we set up our work into projects.

Step 1: Organize your work into “projects.” That means, as much as possible, all the files in a project are in a single directory, aka folder. Each unique project gets its own directory. All the files associated with the project live in that directory. Files not associated with the project do not live in that directory. Check out UVA Library’s workshop Organize Your Files and Metadata for Transparent and Reproducible Research for a detailed discussion of how to set up “little p projects.” I will admit, there is an art as much as science to this. You might not always be able to have all files in one directory, for example your raw data files might necessarily live elsewhere. Being consistent about your practices across research projects is better than being nit-picky about the details of how your directories are set up.

Step 2: When working on a project, set your working directory to that project’s main directory. Be intentional about using that working directory. Use the tools that we will cover below, and avoid using setwd() and absolute paths

Step 3: Be disciplined about using relative file paths. The working directory is the main directory, and all other paths are relative to that directory.

Organize work into projects

Example of a simple file structure for a project

from https://reproducible-science-curriculum.github.io/organization-RR-Jupyter/slides/02_slideshow_organization.slides.html#/1

What RStudio Projects can do for you

AKA “Capital P Projects”

When you launch an RStudio Project, RStudio will:

1. Launch R/RStudio.
2. Set the working directory to the project’s folder.
3. Provide you with a fresh environment. That means there are no libraries loaded and no objects saved in your environment.

Aka “capital P Projects.”

RStudio can help you solve all of these problems with RStudio Projects. When you launch an RStudio Project, RStudio will:

• Launch R/RStudio.
• Set the working directory to the project’s folder.
• Provide you with a fresh environment. That means there are no libraries loaded and no objects saved in your environment.

This solves the problems posed by both setwd() and rm(list = ls())!

Let’s say you are working on one project, and you want to switch to another project. When you want to open a new Project, RStudio will:

• Restart R.
• Set the working directory again.

If you want to run multiple projects at the same time, you can do that!

• Each project gets its own R process (environment), and the working directory is set correctly in each.
• Bonus: multiple projects feel like multiple instances of R and you can use whatever mode you like to switch between them, e.g. Command+Tab (Mac OS) or Alt+Tab (Windows)

Your Turn: RStudio Projects

As an example, we will imagine you are working on two projects: polar-bears and penguins.

You can designate a new or existing folder as an RStudio Project. All that means is that RStudio leaves behind a helper file, e.g., polar-bears.Rproj. This file stores specific settings for that project.

–

In RStudio, use File…New Project…New Directory or click on the R cube in the upper right to get started. Create a fresh project called polar-bears.

Now click on the little down arrow next to the R cube in the upper right, click Open Project, and open the penguins-quarto project you downloaded.

Notice that you get a fresh environment when you switch back and forth.

Using Windows Explorer or Mac Finder, go to where you saved the polar-bears project. Double click on the polar-bears.rproj file. RStudio will launch your project, and you can run multiple instances of R at the same time. You should have both polar-bears and penguins-quarto projects open at the same time, using two RStudio instances. They are running in completely separate environments.

Dynamic Documents with Quarto: No more cut and paste!

With Quarto, you can:

• Compile a single R Markdown document to a report in different formats, such as PDF, HTML, or Word.
• Create notebooks in which you can directly run code chunks interactively.
• Make slides for presentations (like this one!).
• Produce dashboards with flexible, interactive, and attractive layouts.
• Build interactive applications based on Shiny.
• Write journal articles.
• Author books of multiple chapters.
• Generate websites and blogs.

You might be used to cutting tables or plots from your statistical package, and pasting them into a Word document. Now, imagine that your advisor suggests you make changes to your analysis. Did you remember to update the table correctly in Word? What code generated that table in the first place?

Manual copy-and-paste is a huge opportunity for errors and confusion. It’s super tedious and no one wants to spend their time doing it or figuring out what code made what table. R Markdown solves that problem for you. R Markdown allows you to embed R code into narrative text, and then format that text into PDF, HTML, Word, and so on. Now when you need to make changes, you can make changes directly to the code embedded in the R Markdown document. No more cutting and pasting! This is better for reproducibility and transparency, and more simply, makes your life easier.

Citation: R Markdown: The Definitive Guide.

Demo Quarto

We are going to use the penguins-quarto demo project to explore R Markdown documents. penguins-quarto has the following structure:

C:/Users/jah2ax/OneDrive - University of Virginia/Documents/GitHub/penguins-quarto
├── data
│   └── empty.csv
├── penguins-quarto.Rproj
├── presentation
│   ├── images
│   │   ├── figures_for_slides-01.png
│   │   └── visual_mode_2x.png
│   ├── repro_analysis_R_RStudio.bib
│   ├── repro_analysis_R_RStudio_quarto.html
│   ├── repro_analysis_R_RStudio_quarto.qmd
│   ├── repro_analysis_R_RStudio_quarto.rmarkdown
│   └── repro_analysis_R_RStudio_quarto_files
│       └── libs
│           ├── clipboard
│           │   └── clipboard.min.js
│           ├── quarto-html
│           │   ├── popper.min.js
│           │   ├── quarto-html.min.css
│           │   ├── quarto-syntax-highlighting-dark.css
│           │   ├── quarto-syntax-highlighting.css
│           │   ├── tabby.min.js
│           │   ├── tippy.css
│           │   └── tippy.umd.min.js
│           └── revealjs
│               ├── dist
│               │   ├── reset.css
│               │   ├── reveal.css
│               │   ├── reveal.esm.js
│               │   ├── reveal.esm.js.map
│               │   ├── reveal.js
│               │   ├── reveal.js.map
│               │   └── theme
│               │       ├── fonts
│               │       │   ├── league-gothic
│               │       │   │   ├── league-gothic.css
│               │       │   │   ├── league-gothic.eot
│               │       │   │   ├── league-gothic.ttf
│               │       │   │   ├── league-gothic.woff
│               │       │   │   └── LICENSE
│               │       │   └── source-sans-pro
│               │       │       ├── LICENSE
│               │       │       ├── source-sans-pro-italic.eot
│               │       │       ├── source-sans-pro-italic.ttf
│               │       │       ├── source-sans-pro-italic.woff
│               │       │       ├── source-sans-pro-regular.eot
│               │       │       ├── source-sans-pro-regular.ttf
│               │       │       ├── source-sans-pro-regular.woff
│               │       │       ├── source-sans-pro-semibold.eot
│               │       │       ├── source-sans-pro-semibold.ttf
│               │       │       ├── source-sans-pro-semibold.woff
│               │       │       ├── source-sans-pro-semibolditalic.eot
│               │       │       ├── source-sans-pro-semibolditalic.ttf
│               │       │       ├── source-sans-pro-semibolditalic.woff
│               │       │       └── source-sans-pro.css
│               │       └── quarto.css
│               └── plugin
│                   ├── highlight
│                   │   ├── highlight.esm.js
│                   │   ├── highlight.js
│                   │   ├── monokai.css
│                   │   ├── plugin.js
│                   │   └── zenburn.css
│                   ├── markdown
│                   │   ├── markdown.esm.js
│                   │   ├── markdown.js
│                   │   └── plugin.js
│                   ├── math
│                   │   ├── katex.js
│                   │   ├── math.esm.js
│                   │   ├── math.js
│                   │   ├── mathjax2.js
│                   │   ├── mathjax3.js
│                   │   └── plugin.js
│                   ├── notes
│                   │   ├── notes.esm.js
│                   │   ├── notes.js
│                   │   ├── plugin.js
│                   │   └── speaker-view.html
│                   ├── pdf-export
│                   │   ├── pdfexport.js
│                   │   └── plugin.yml
│                   ├── quarto-line-highlight
│                   │   ├── line-highlight.css
│                   │   ├── line-highlight.js
│                   │   └── plugin.yml
│                   ├── quarto-support
│                   │   ├── footer.css
│                   │   ├── plugin.yml
│                   │   └── support.js
│                   ├── reveal-menu
│                   │   ├── menu.css
│                   │   ├── menu.js
│                   │   ├── plugin.yml
│                   │   ├── quarto-menu.css
│                   │   └── quarto-menu.js
│                   ├── search
│                   │   ├── plugin.js
│                   │   ├── search.esm.js
│                   │   └── search.js
│                   └── zoom
│                       ├── plugin.js
│                       ├── zoom.esm.js
│                       └── zoom.js
├── quarto
│   ├── 01_basics.qmd
│   └── 02_computations.qmd
├── README.md
└── scripts
    └── 01-penguins.R

Note that this implements the essential “little p” project structure, by separating content into clear sub-directories.

Let’s take a look at the penguins-quarto project now. The instructions for downloading the project are in the “Before we begin” section.

Recommended for further learning

Reach out to our statistical consultants! statlab@virginia.edu

General Reproducible Research in R and RStudio:

• Gandrud, Christopher. Reproducible Research With R and RStudio.

RStudio Projects:

• Jennifer Bryan and Jim Hester. What they Forgot to Teach about R. Project Oriented Workflow and Practice Safe Paths.
• Hadley Wickham and Garrett Grolemund. R for Data Science. Chapter 8: Workflow: projects.

R Markdown:

• Yihui Xie, J. J. Allaire, Garrett Grolemund. R Markdown: The Definitive Guide.
• RStudio. R Markdown by RStudio: Introduction.
• RStudio. Visual R Markdown.
• RStudio. Visual R Markdown: Citations.

R Markdown Cheat Sheets:

• RStudio. R Markdown: Cheat Sheet.
• RStudio. R Markdown: Reference Guide.

Bonus: here package:

• Malcolm Barrett. Why should I use the here package when I’m already using projects?
• Jenny Richmond. how to use the `here` package.
• Kirill Müller and Jennifer Bryan. Here package vignettes: here and Using here with R Markdown.

Bryan, Jennifer, and Jim Hester. n.d.a. “Chapter 2: Project-Oriented Workflow.” In What They Forgot to Teach You About R.

———. n.d.b. “Chapter 3: Practice Safe Paths.” In What They Forgot to Teach You About R.

Pileggi, Shannon, Jenny Bryan, and E. David Aja. 2022. “What They Forgot to Teach You About R - Rstudio::conf(2022) Workshop - Wtf-Opening.” What They Forgot to Teach You About R. https://rstats-wtf.github.io/wtf-2022-rsc/materials/wtf-opening-2022.pdf.

Wickham, Hadley, and Garrett Grolemund. n.d. “8 Workflow: Projects.” In R for Data Science.