ENV 872 - Configure RStudio

ENV 872 - EDA | Spring 2024 | Instructors: Luana Lima, John Fay |

Now that you have your GitHub account set up, have successfully created your personal class repository by forking the main class repository, and have a computing environment set up with R, RStudio, and Git installed, you are ready to create your local RStudio project. This document outlines the steps to do just that. Again, what you are doing may not make sense as you do them, but once complete, we’ll explain how everything fits together.

Recorded instructions:

1. Open RStudio

(either by accessing your container or by opening the app on your personal machine)

RStudio is organized as a series of “panes”. When you open R for the very first time, you’ll see three panes.

Filling the left half of the screen is the **Console Pane**. which has three tabs:

The Console tab has the command prompt of “>”.

You can enter R commands here. The Terminal tab has the command prompt of “$”. You enter operating system commands (including Git commands) here.

The Background Jobs allows you to view the status of background jobs. (You won’t likely use this one much.)

The upper right portion contains the **Environment Pane**, with several tabs:

The Environment tab displays any variables declared in your current session.

The History tab reveals all commands that you’ve run in the console.

The Connections tab is for connecting directly to data services. (You won’t likely use this one much.)

The Tutorial tab contains links to a number of tutorials, which you are welcome to browse through, but that’s certainly not required.

The lower right portion contains the **Output Pane** with the following tabs:

The Files tab reveals a file manager built into RStudio

The Plots tab provides space where plots generated by your code can be viewed.

The Packages tab opens RStudio’s package manager. (We’ll discuss packages soon.)

The Help tab opens help documentation

The Viewer tab provides space where more complex outputs can be viewed.

The Presentation tab provides space where more slide decks can be viewed.

2. Install TinyTex

TinyTex is an R utility required to publish or “knit” our code documents into spiffy looking PDF files. (See this link for more information.) We will install it using a command run in the Console window.

Activate the Console window in RStudio.
At the > prompt, type the following and then hit enter.
```
tinytex::install_tinytex()
```

3. Set your Git username and email on your local machine

Git is designed, among other things, to send files back and forth between your local machine and your GitHub account in the cloud. To enable communication between local machine and GitHub, we first need to tell your local machine about your GitHub account. This is done by storing your GitHub username and email locally as Git global variables. (A more in-depth discussion on this is available here in the Happy Git with R site.) Here’s how we do this:

Activate the Terminal window in RStudio.
At the $ prompt type type the following to ensure it is working properly:
```
git --version
```
This should return the version of Git installed on your machine, e.g. git version 2.39.0.
If you get an error here, contact an instructor as your Git software is not operational.
Again, at the $ prompt type (replacing your own Git username and email with the placeholders below:
```
git config --global user.name "Your Name"
git config --global user.email "your.name@duke.edu"
git config --global --list
```
That last line reports what you saved as your global user name and user email variables. If you entered them incorrectly, just run the command again with the corrected info.

4. Store your personal access token on your machine

Git now knows about your GitHub account in the cloud, but it still lacks the authority to write to your GitHub account. We previously created our personal access token (PAT) in GitHub. and in these steps we use that PAT to authenticate our local Git account to upload (push) and download (pull) files to our remote GitHub repositories. Here are the steps involved in this procedure, again discussed in greater detail on the Happy Git with R site (here).

Note that if ever you are asked for a username and password for your GitHub account within RStudio, always provide your Git username and your personal access token, NOT your GitHub password. If you do, your password won’t be compromised; it simply won’t work or you’ll get an authentication error.

Activate the Console window in RStudio.
Install the “usethis” package with the following command:
```
install.packages("usethis")
```
Then run following command to save your PAT as a Git credential:
```
gitcreds::gitcreds_set()
```
This will start a set of prompts asking you to save your PAT as an encrypted file on the local machine.

Particularly on the containers, the stored PAT will eventually expire and you’ll be asked to re-enter it. Simply run the gitcreds::gitcreds_set() command again. You may be able to extend the period between PAT expirations with the following command issued at the Terminal:
git config --global credential.helper "cache --timeout=10000000"
For more information see: https://happygitwithr.com/https-pat.html#pat-doesnt-persist-on-linux

5. Set your default knit directory

This setting will solve an issue that tends to plague users later on, having to do with relative paths…

From the Tool menu, select Global Options
Select the RMarkdown section
In the “Evaluate chunks in directory”, set the option to “Project” (If you don’t see this option, try restarting RStudio.)

Your local RStudio software is now properly configured for the class! As always, be sure to follow up if you run into any issues and ask about any topics you are curious about in class.