Want to help out or contribute?

If you find any typos, errors, or places where the text may be improved, please let us know by providing feedback either in the feedback survey (given during class), by using GitLab, or directly in this document with hypothes.is annotations.

  • Open an issue or submitting a merge request on GitLab.
  • Hypothesis Add an annotation using hypothes.is. To add an annotation, select some text and then click the on the pop-up menu. To see the annotations of others, click the in the upper right-hand corner of the page.

5 Basic setup and workflow

5.1 Introduction to course

Introduction slides

For instructors: Click for details

The slides contain speaking notes that you can view by pressing ‘p’ on the keyboard.

5.2 Overview of workflow

Take 5 min to read over this section before we go over it together.

This section provides an bigger picture view of what we will be doing, how we will be going about doing it, and what it will look like in the end. Both the folder and file structures below as well as the Figure 5.1 show exactly what we will be doing and how it will look like at the file level (not at the R code level). Hopefully with this overview, you can better understand where we are and where we want to get to. A comment on naming: whenever folder names are given, they always end in /, for instance data/ or doc/.

Right now, everyone’s initial project structure should look like:

LearnR3
├── data/
│   └── README.md
├── doc/
│   ├── README.md
│   └── lesson.Rmd
├── R/
│   ├── fetch_data.R
│   ├── functions.R
│   ├── setup.R
│   └── README.md
├── .Rbuildignore
├── .gitignore
├── DESCRIPTION
├── LearnR3.Rproj
├── README.md
└── TODO.md

At the end of this workshop, it should look something like:

LearnR3
├── data/
│   ├── README.md
│   └── mmash.rda
├── data-raw/
│   ├── mmash-data.zip
│   ├── mmash/
│   │  ├── user_1
│   │  ├── ...
│   │  └── user_22
│   └── mmash.R
├── doc/
│   ├── README.md
│   ├── lesson.html
│   └── lesson.Rmd
├── R/
│   ├── README.md
│   └── functions.R
├── .Rbuildignore
├── .gitignore
├── DESCRIPTION
├── LearnR3.Rproj
└── README.md

Our workflow will generally look like Figure 5.1, with each block representing a session.

Figure 5.1: Overview of the workflow we will be using and covering.

Our workflow and process will be something like:

  • Make an R script (data-raw/mmash.R) to download the dataset (data-raw/mmash/).
  • Use R Markdown (doc/lesson.Rmd) to write and test out code, convert it into a function, test it, and then move it into R/functions.R.
  • We use RStudio’s built-in functionality to run everything in the R/ folder with Ctrl-Shift-L (only available when “Tools -> Project Options -> Build Tools” is set as “Package”).
  • Replace the old code with the new function in the R Markdown document (doc/lesson.Rmd).
  • Finish building functions that prepare the dataset, use them in the cleaning script (data-raw/mmash.R), run the script and save the data as an .rda file (data/mmash.rda).
  • Remove the old code from the R Markdown document (doc/lessons.Rmd).
  • Whenever we complete a task, we add and commit those file changes and save them into the Git history.

5.3 Setting up our project

Now that we’ve gone over the overview, let’s get our project ready for the next steps. First we have a bunch of files that we won’t need, so let’s delete them. We’ll be using the fs package, which means filesystem, throughout this course to work with files.

In the Console, type out:

fs::file_delete(c("R/setup.R", "R/fetch_data.R", "TODO.md"))

Then, let’s open up the README and fix some of the TODO items. After cleaning everything up, now we need to use Git to add and commit all the current files into the history. Open up the Git interface in RStudio with Ctrl-Alt-M or through the Git button at the top below either the “Build” or “Debug” menu items. The interface should open up and we’ll click the checkboxes on all the files, then write a message in the commit textbox saying “Initial setup done”. Now we’re ready for the next session!