5 R and GitHub Setup

Before we start

Non-Verbal Feedback

We’ll be using the Zoom “Non Verbal Feedback” buttons throughout this session. We will ask you to put a green check by your name when you’re all set and ready to move on, and a red x by your name if you’re stuck or need assistance. These buttons can be found in the Reaction menu on the toolbar. When you’re asked to answer using these buttons, please ensure that you select one so that the instructor has the feedback that they need to either continue the lesson or pause until everyone gets back on the same page.

Questions and Getting Help

When you need to ask a question, please do so in one of the following ways:

• Turn your mic on and ask. If you are uncomfortable interrupting the instructor, you may also raise your virtual hand (in the Reaction menu) and the instructor will pause at their convenience and address you to ask your question.
• Ask your question in the chat. The instructor might not see or address the questions ins the chat right away, but they will get to it whenever possible through out the lesson.

If you have an issue/error and get stuck, you can ask for help in the following ways:

• Turn your mic on and ask for help. See also above regarding the use of a virtual raised hand.
• Let one of the instructors know through the chat
• If prompted to do so, put a red X next to your name as your status in the participant window.
• If you have an issue that requires in-depth trouble shooting, please let us know and we will coordinate a time with you after this call.

5.1 R and RStudio Setup

Learning Objectives

• Practice creating an R Project
• Organize an R Project for effective project management
• Understand how to move in an R Project using paths and working directories

5.1.1 Intro to R and RStudio

RStudio is the main program we are going to be using today. We will access your computer’s terminal through RStudio to set up all the necessary Git configurations. Please make sure you have read and followed the instructions in Install R, RStudio and Git section so we can successfully go over the configuration steps below.

Artwork by Allison Horst

There is a vibrant community out there that is collectively developing increasingly easy to use and powerful open source programming tools. The changing landscape of programming is making learning how to code easier than it ever has been. Incorporating programming into analysis workflows not only makes science more efficient, but also more computationally reproducible. In this course, we will use the programming language R, and the accompanying integrated development environment (IDE) RStudio. R is a great language to learn for data-oriented programming because it is widely adopted, user-friendly, and (most importantly) open source!

So what is the difference between R and RStudio? Here is an analogy to start us off. If you were a chef, R is a knife. You have food to prepare, and the knife is one of the tools that you’ll use to accomplish your task.

And if R were a knife, RStudio is the kitchen. RStudio provides a place to do your work! Other tools, communication, community, it makes your life as a chef easier. RStudio makes your life as a researcher easier by bringing together other tools you need to do your work efficiently - like a file browser, data viewer, help pages, terminal, community, support, the list goes on. So it’s not just the infrastructure (the user interface or IDE), although it is a great way to learn and interact with your variables, files, and interact directly with git. It’s also data science philosophy, R packages, community, and more. Although you can prepare food without a kitchen and we could learn R without RStudio, that’s not what we’re going to do. We are going to take advantage of the great RStudio support, and learn R and RStudio together.

Something else to start us off is to mention that you are learning a new language here. It’s an ongoing process, it takes time, you’ll make mistakes, it can be frustrating, but it will be overwhelmingly awesome in the long run. We all speak at least one language; it’s a similar process, really. And no matter how fluent you are, you’ll always be learning, you’ll be trying things in new contexts, learning words that mean the same as others, etc, just like everybody else. And just like any form of communication, there will be miscommunication that can be frustrating, but hands down we are all better off because of it.

While language is a familiar concept, programming languages are in a different context from spoken languages and you will understand this context with time. For example: you have a concept that there is a first meal of the day, and there is a name for that: in English it’s “breakfast.” So if you’re learning Spanish, you could expect there is a word for this concept of a first meal. (And you’d be right: “desayuno”). We will get you to expect that programming languages also have words (called functions in R) for concepts as well. You’ll soon expect that there is a way to order values numerically. Or alphabetically. Or search for patterns in text. Or calculate the median. Or reorganize columns to rows. Or subset exactly what you want. We will get you to increase your expectations and learn to ask and find what you’re looking for.

5.1.2 RStudio IDE

Let’s take a tour of the RStudio interface.

Notice the default panes:

• Console (entire left)
• Environment/History (tabbed in upper right)
• Files/Plots/Packages/Help (tabbed in lower right)

Quick Tip

You can change the default location of the panes, among many other things, see Customizing RStudio.

5.1.3 Create an R Project

In this course, we are going to be using an R project to organize our work. An R project is tied to a directory on your local computer, and makes organizing your work and collaborating with others easier.

The Big Idea: using an R project is a reproducible research best practice because it bundles all your work within a working directory. Consider your current data analysis workflow. Where do you import you data? Where do you clean and wrangle it? Where do you create graphs, and ultimately, a final report? Are you going back and forth between multiple software tools like Microsoft Excel, JMP, and Google Docs? An R project and the tools in R that we will talk about today will consolidate this process because it can all be done (and updated) in using one software tool, RStudio, and within one R project.

R Project Setup

1. In the “File” menu, select “New Project”
2. Click “New Directory”
3. Click “New Project”
4. Under “Directory name” type: training_{USERNAME} (i.e. training_vargas)
5. Leave “Create Project as subdirectory of:” set to ~
6. Click “Create Project”

RStudio should open your new project automatically after creating it. One way to check this is by looking at the top right corner and checking for the project name.

5.1.4 Organizing an R Project

When starting a new research project, step 1 is to create an R Project for it (just like we have here!). The next step is to then populate that project with relevant directories. There are many tools out there that can do this automatically. Some examples are rrtools or usethis::create_package(). The goal is to organize your project so that it is a compendium of your research. This means that the project has all of the digital parts needed to replicate your analysis, like code, figures, the manuscript, and data access.

Some common directories are:

• data: where we store our data (often contains subdirectories for raw, processed, and metadata data)
• R: contains scripts for cleaning or wrangling, etc. (some find this name misleading if their work has other scripts beyond the R programming language, in which case they call this directory scripts)
• plots or figs: generated plots, graphs, and figures
• docs: summaries or reports of analysis or other relevant project information

Directory organization will vary from project to project, but the ultimate goal is to create a well organized project for both reproducibility and collaboration.

5.1.5 Moving in an R Project using Paths & Working Directories

Now that we have your project created (and notice we know it’s an R Project because we see a .Rproj file in our Files pane), let’s learn how to move in a project. We do this using paths.

There are two types of paths in computing: absolute paths and relative paths.

• An absolute path always starts with the root of your file system and locates files from there. The absolute path to my project directory is: /home/vargas-poulsen/training_vargas

• Relative paths start from some location in your file system that is below the root. Relative paths are combined with the path of that location to locate files on your system. R (and some other languages like MATLAB) refer to the location where the relative path starts as our working directory.

RStudio projects automatically set the working directory to the directory of the project. This means that you can reference files from within the project without worrying about where the project directory itself is. If I want to read in a file from the data directory within my project, the code to do this would be read.csv("data/samples.csv") (path relative to my R project) as opposed to read.csv("/home/vargas-poulsen/training_vargas/data/samples.csv") (absolute path of my home directory).

This is not only convenient for you, but also when working collaboratively. For example if Matt makes a copy of my R project that I have published on GitHub, and I am using relative paths, he can run my code exactly as I have written it, without going back and changing /home/vargas-poulsen/training_vargas/data/samples.csv to /home/jones/training_jones/data/samples.csv.

Note that once you start working in projects you should basically never need to run the setwd() command. If you are in the habit of doing this, stop and take a look at where and why you do it. Could leveraging the working directory concept of R projects eliminate this need? Almost definitely!

setwd() sets your working directory to specified file path (aka directory).

Similarly, think about how you work with absolute paths. Could you leverage the working directory of your R project to replace these with relative paths and make your code more portable? Probably!

5.2 Git and GitHub Setup

Learning Objectives

• Set global options in your .gitconfig file
• Practice how to set up GitHub Authentication using a Personal Access Token (PAT)

5.2.1 Set up global options in Git

Before using Git, you need to tell it who you are, also known as setting the global options. To do this, we will be setting the global options in the Terminal.

What’s the Terminal?

Technically, the Terminal is an interface for the shell, a computer program. To put that simply, we use the Terminal to tell a computer what to do. This is different from the Console in RStudio, which interprets R code and returns a value.

To get started, let’s open a new Terminal window in RStudio. Do this by clicking Tools > Terminal > New Terminal.

A Terminal tab should now be open where your Console usually is.

Don’t be afraid to dip your toes in the Terminal

Most of our git operations will be done in RStudio, but there are some situations where you must work in the Terminal and use command line. It may be daunting to code in the Terminal, but as your comfort increases over time, you might find you prefer it. Either way, it’s beneficial to learn enough command line and to feel comfortable in the Terminal.

Let’s start by adding your user name to the global options. Type the following into the command prompt, with your exact GitHub username, and press enter:

git config --global user.name "my_user_name"

Note that if it ran successfully, it will look like nothing happened. We will check at the end to make sure it worked.

Next, enter the following line, with the email address you used when you created your account on github.com:

git config --global user.email "my_email@nceas.ucsb.edu"

Case and spelling matters!

When you add your username and email to the global options you must use the exact same spelling and case that you used on GitHub otherwise, Git won’t be able to sync to your account.

Next, we will set the default branch name to main for any new repositories that are created moving forward. Why are we doing this? Previously, the default branch name was master and this racist terminology for git branches motivates us to update our default branch to main instead.

git config --global init.defaultBranch main

Finally, check to make sure everything looks correct by entering this command, which will return the global options you have set.

git config --global --list

5.2.2 GitHub Authentication

GitHub recently deprecated password authentication for accessing repositories, so we need to set up a secure way to authenticate.

The book Happy Git and GitHub for the useR has a wealth of information related to working with Git in R, and these instructions are based off of Chapter 9 Personal access token for HTTPS.

We will be using a Personal Access Token (PAT) in this course. For better security and long term use, we recommend taking the extra steps to set up SSH keys (check out Chapter 10 Set up Keys for SSH).

Setting up your PAT

1. Run usethis::create_github_token() in the Console.
2. A new browser window should open up to GitHub, showing all the scopes options. You can review the scopes, but you don’t need to worry about which ones to select this time. Using this function automatically pre-selects some recommended scopes. Go ahead and scroll to the bottom and click “Generate Token”.
3. Copy the generated token.
4. Back in RStudio, run gitcreds::gitcreds_set() in the Console.
5. Paste your PAT when the prompt asks for it.
6. Last thing, run usethis::git_sitrep() in the Console to check your Git configuration and that you’ve successful stored your PAT.

Congrats! Now you’ve setup your authentication you should be able to work with GitHub in RStudio now.