Reproducible Analysis and Documentation

Fall 2022

Slides Usage Notes

Recommended to press w for widescreen view.
Also recommended to press f for fullscreen view.
Press p for Presenter Notes.
These slides are licensed as CC-BY.

Before we begin

Open RStudio. Make sure updated to v 1.4 if using Visual Editor
Be sure you can find the penguins demo project you downloaded

Learning Objectives

In this workshop, you will learn:

How to use RStudio Projects and why you would want to
What R Markdown 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 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

How to do a project-oriented workflow?

Use:

A dedicated directory
RStudio Projects
Git repo

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

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

Organize work into projects

AKA “little p projects”

Use a single directory for your research project
Set working directory in R to that main directory
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:

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.

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 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 projects open at the same time, using two RStudio instances. They are running in completely separate environments.

Dynamic Documents with R Markdown: No more cut and paste!

With R Markdown, 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.

As noted in R Markdown: The Definitive Guide, with R Markdown, 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 (HTML5, LaTeX Beamer, or PowerPoint).
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.

R Markdown Visual Editor

R Markdown Visual Editor brings some of the features and ease-of-use that GUIs provide, while still always maintaining the source code that is the .Rmd file (R Markdown file).

Bonus: `here` package

Paths created relative to the top level directory.

The here package enables easy file referencing with project-oriented workflows. Paths are created relative to the top-level directory. It is most useful when you work with R Markdown documents a lot, as it smoothes out some of the idiosyncrasies of how R Markdown looks for files.

The here package always points to the root directory, which is typically where we set the working directory with our RStudio Project.

## here() starts at C:/Users/jah2ax/OneDrive - University of Virginia/Documents/GitHub/reproAnalysis/slides

References: [Barrett (2018)](Richmond, n.d.)[Müller and Bryan (n.d.a)](Müller and Bryan, n.d.b)

Demo R Markdown

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

## C:/Users/jah2ax/OneDrive - University of Virginia/Documents/GitHub/penguins
## ├── data
## │   └── empty.csv
## ├── documents
## │   ├── apa.csl
## │   ├── references.bib
## │   ├── report.html
## │   └── report.Rmd
## ├── penguins.Rproj
## ├── 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 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.

References

Barrett, Malcolm. 2018. “Why Should I Use the Here Package When I’m Already Using Projects?” Malcolm Barrett. https://malco.io/2018/11/05/why-should-i-use-the-here-package-when-i-m-already-using-projects/.

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.

Grolemund, Garrett, J. J. Allaire. n.d. R Markdown: The Definitive Guide.

Müller, Kirill, and Jennifer Bryan. n.d.a. “Here Vignette.” https://cran.r-project.org/web/packages/here/vignettes/here.html.

———. n.d.b. “Using Here with Rmarkdown Vignette.” https://cran.r-project.org/web/packages/here/vignettes/rmarkdown.html.

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.

Richmond, Jenny. n.d. “How to Use the ‘Here‘ Package.” http://jenrichmond.rbind.io/post/how-to-use-the-here-package/.

RStudio. n.d.a. “R Markdown: Introduction.” https://rmarkdown.rstudio.com/lesson-1.html.

RStudio. n.d.b. “Visual R Markdown.” https://rstudio.github.io/visual-markdown-editing/#/.

RStudio. n.d.c. “Visual R Markdown: Citations.” https://rstudio.github.io/visual-markdown-editing/#/citations.

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

Slides Usage Notes

Before we begin

Learning Objectives

Why a project-oriented workflow?

How to do a project-oriented workflow?

Project-oriented workflow with RStudio Projects

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

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

Organize work into projects

Organize work into projects

What RStudio Projects can do for you

Your Turn: RStudio Projects

Dynamic Documents with R Markdown: No more cut and paste!

R Markdown Visual Editor

Bonus: here package

Demo R Markdown

Recommended for further learning

References

Bonus: `here` package