4  Software

In this section, we discuss two pieces of software that you will need to install on your laptop computer: R (and R Studio) and Git. We will begin with the far easier of the two: R.

4.1 Installing R and R Studio (Class Prep)

If you had Professor Higham for STAT/DATA 234, you should already have R and R Studio installed on your laptop computer. You may also already have these installed from another course or an independent study. Even though you might already have these installed, it might be time for an update: if you have not reinstalled these in a year, updating would be a good idea.

The following videos provide instructions on how to install R and R Studio to your laptop computer. It will be easiest if you complete all of these steps consecutively in one sitting. So, you should ideally have about 45 minutes to an hour of your time blocked off to complete the “getting started” process using the videos below.

Watch and follow along with a video on installing R.

Watch and follow along with a video on installing R Studio.

Watch and follow along with a video on installing R packages and changing other options.

After you install R Studio, create a new Quarto file (File -> New File -> Quarto Document), and answer the following questions within the file. At the top of the file, you should change the YAML header to something like

---
title: "Your Title"
author: "Your Name"
format: 
  html:
    embed-resources: true
---

The embed-resources part of the YAML header says to embed all of the necessary code, tables, and graphs into one single file.

Render the file and submit the resulting .html file to Canvas.

  1. What is your name and what is your class year (first-year, sophomore, junior, senior)?

  2. What is/are your major(s) and minor(s), either actual or intended?

  3. Why did you decide to take this course?

  4. In what semester and year did you take STAT/DATA 234? STAT 213?

  5. Have you taken CS 140?

  6. Have you used Git before? If so, in what context?

  7. Before this course, did you use R Studio on your desktop?

  8. What is your hometown: city, state, country?

  9. Do you play a sport on campus? If so, what sport? If not, what is an activity that you do on or off-campus?

  10. What is your favorite TV show or movie or band/musical artist?

  11. Tell me something about yourself.

  12. What are your expectations for this class and/or what do you hope to gain from this class?

4.2 Installing Git and Using GitHub (Class Prep)

Important

Start this early, and, if you get stuck, try to troubleshoot for 5 minutes or so. If you are still stuck, to protect your own time, make an appointment for office hours so we can work through the issue.

The following links provide instructions on getting started with Git and GitHub for version control of projects (repositories). The videos assume that you already have R and R Studio installed on your laptop. It will be easiest if you complete all of these steps consecutively in one sitting. So, you should ideally have about 1.5 - 2 hours of your time blocked off to complete the “getting started” process using the videos below. It might also be helpful (but not necessary) to work through these with a partner or two in case either of you get stuck.

This section outlines the steps to get Git up, running, and connected to R Studio. There are accompanying videos at https://highamm.github.io/dataviz334/02-software.html#installing-git-and-using-github-class-prep, which may provide a little more guidance than the written steps below.

4.2.1 Pre-requisites

  1. Install both R and R Studio locally.

  2. Install Git, following https://happygitwithr.com/install-git.html. Note that most of the code in this section is code for the Terminal. You can access the Terminal within R Studio by going to “Tools -> Terminal -> New Terminal”

    • You may already have Git installed: type git --version in your Terminal window and hit Enter: if you see a version number get returned, you can jump to the next step!

    • Make sure to follow the directions with your associated operating system (likely either Windows or Mac).

    • After installation, in the Terminal, type git --version to verify that you get a version number

  3. Create a GitHub account at https://github.com/ with the “Sign Up” button.

4.2.2 Connect GitHub to R Studio

While the previous steps were completed in Terminal, the following steps use R code itself, so you can run the commands below like normal R code.

  1. Install the usethis package in R with install.packages("usethis").

  2. Give Git your credentials with the use_git_config function in the usethis package: usethis::use_git_config(user.name = "Matt Higham", user.email = "mhigham@stlawu.edu").

    • Note that the email provided must match your GitHub email address. The user.name need not match.

  3. Generate a Personal Access Token (PAT) with usethis::create_github_token()

    • You can change the recommended scopes if you want but you should at least leave “repo”, “user”, and “workflow” checked.
    • By default, the PAT will expire in 30 days. People have varying levels of comfort with security: I will somewhat shamefully admit that I always click the “No Expiration” option because I do not want to ever generate a new one.

  4. Install the gitcreds package with install.packages("gitcreds") and then, in R, run gitcreds::gitcreds_set() and paste in your PAT when prompted.

4.2.3 Create a Repository

  1. On your GitHub account site, click the “+” sign in the upper-right corner and select “New Repository.”

    • Give the repository a title and make sure to have the option to create the README file checked.

    • If your repository will eventually contain data or other code that cannot be made public, you should select the “Private” option for the repository.

  2. Back in R Studio, go to “File -> New Project”, select “Version Control” from the options, and then select “Git”. Then, copy and paste the GitHub repository web URL address, give the folder that will be created a name (giving it the same name as the repository is not required but is something that I find convenient), select where that folder will live on your local computer, and click “Create Project”.

    • If all goes well, you should have a new project with a “Git” pane in the upper-right window. If all does not go well, it may be that R Studio cannot locate Git on your local computer and that we need to do a bit of troubleshooting.

4.2.4 Commit, Push, and Pull

After you are able to commit, push, and see that push show up on your remote GitHub site, you know that you have successfully set up this version control system!

4.3 Using Git and GitHub

In class, we will discuss how to use Git and GitHub with R Studio as well as how we will use these tools to submit assignments in this course. By the end of the class in which we discuss Git and GitHub, at minimum you should be able to (1) locally commit a change to your files with a commit message, (2) push that local change to your remote GitHub repository, and (3) pull a change that someone else made to the remote GitHub repository.

4.4 Creating a Quarto Blog/Website

The following site gives more detailed information about starting up a Quarto blog: https://quarto.org/docs/websites/website-blog.html.

4.4.1 Creating the Blog

To create a Quarto Blog in R Studio, go to File -> New Project -> New Directory -> Quarto Blog

Check the “Create a Git repository” checkbox, give the project a name (without spaces), and select a directory for the project to be created in.

Before moving on, make sure that you can Render the blog, by clicking the “Render Website” button in the “Build” tab in the upper-right window of R Studio.

4.4.2 Connecting to GitHub

As long as you checked the “Create a Git repository” checkbox, you should see a Git pane in your top-right window. However, we have not yet connected this Git repository to your GitHub account. To do so,

  1. Commit the files to your local Git repository by clicking “Commit” and writing a commit message.

  2. In the R console, type usethis::use_github(). If done correctly, a web browser should open with your repository on your GitHub account.

4.4.3 Publishing through GitHub Pages

To publish your website, we can use GitHub pages. Before going to your GitHub account site, navigate to the _quarto.yml file in R Studio that stores information on how to build your blog. Below type: website, add output-dir: docs, keeping the same indentation that type: website has. Then, re-render your blog in the “Build” tab of R Studio. Specifying output-dir to docs says to output the blog to a new folder called docs, which will allow us to publish the blog more easily in GitHub pages.

Then, on your GitHub account site, navigate to the repository you just created. Go to Settings -> Pages. Under Build and Deployment, make sure Source is set to Deploy from a branch. Under Brand, select either master or main and under folder, select /docs, which corresponds to the folder we have the blog rendered to locally. After giving it a couple of minutes to build, you should be able to click the “Visit Site” button to see your blog, which is now published on the web.

4.4.4 Creating a New Post

To create a new post, first create a new Folder in within the “Posts” folder of your Project. Then, create a new Quarto .qmd file (HTML), type some code into the file, and save the file as index.qmd within your new folder.

Render the blog by again clicking the “Render Website” button in the “Build” tab to verify that your new post appears.

4.4.5 Unfreezing Output

By default, this post is now “Frozen.” Changing code within a code chunk will not change the output. To change this behaviour, navigate to the “Posts” folder and click on the _metadata.yml file. In the file, change freeze: true to freeze: false, which will unfreeze the code in all of the posts in the “Posts” folder.

We will change this option back in the future, after we discuss the benefits of freeze: true.