dlab-berkeley / r-fundamentals

D-Lab's 4 part, 8 hour introduction to R Fundamentals. Learn how to create variables and functions, manipulate data frames, make visualizations, use control flow structures, and more, using R in RStudio.

D-Lab's R Fundamentals Workshop

This repository contains the materials for D-Lab's R Fundamentals workshop.

Prerequisites

No prior experience with R is required.

Check D-Lab's Learning Pathways to figure out which of our workshops to take!

Workshop Goals

This interactive workshop series is your complete introduction to programming in R for people with little or no previous programming experience. It covers the basics of using RStudio, creating variables, working with data frames, and starting to analyse your data using summary statistics and data visualization.

Learning Objectives

After completing this workshop series you will be able to:

• Navigate R Studio
• Open data in R and work with it in data frames using tidyverse
• Distinguish between different variable types
• Visualize data using ggplot
• Inspect documentation to deal with error messages

This workshop does not cover the following:

• Advanced data manipulation and cleaning - this is covered in R Data Wrangling
• Extensive data visualization - this is covered in R Data Visualization

Workshop Structure

R Fundamentals has 4 parts. Each of the parts takes 2 hours, and is delivered in a lecture-style coding walk through interrupted by challenge problems and a break. Instructors and TAs are dedicated to engaging you in the classroom and answering questions in plain language.

1. Part 1: Introduction to R and R Studio
2. Part 2: Data frames and variable types
3. Part 3: Manipulating data frames
4. Part 4: Data visualizations and custom functions

Installation Instructions

NOTE: We will spend the first part of Workshop 1 installing R and downloading materials for the workshop series. You do not need to install R beforehand.

RStudio is a software commonly used by R practitioners to develop code in R. We will use RStudio to go through the workshop materials, which requires the installation of both the R language and the RStudio software. If you would like to run R on your own computer, complete the following steps prior to the workshop:

1. Download R: Follow the links according to the operating system you are running. You will first need to click on a link corresponding to your operating system, and then an additional link to select a specific version of R. Download the package, and install R onto your computer. You should install the most recent version (at least version 4.1).

   • If you are using a Mac, click "Download R for macOS" and then select the right version of R. You will need to select the version corresponding to your specific version of macOS, as well as whether you have an Intel or Apple Silicon Mac.
   • If you are using Windows, click "Download R for Windows", then click "base", and click the download link.
   • If you are using Linux, click on the link corresponding to your Linux distribution, and then follow the instructions.

2. Download RStudio: Install RStudio Desktop. This should be free. Do this after you have already installed R. The D-Lab strongly recommends an RStudio edition of 2022.02.0+443 "Prairie Trillium" or higher.

   • Some individuals with older operating systems may run into odd issues. If you are running into issues with the installation of RStudio, you may need to install a specific version of RStudio. Please check this link if this applies to you.

3. Download these R Fundamentals workshop materials:

   • Click the green "Code" button in the top right of the repository information.
   • Click "Download Zip".
   • Extract this file to a folder on your computer where you can easily access it (we recommend Desktop).

4. Optional: if you're familiar with git, you can instead clone this repository by opening a terminal and entering git clone [email protected]:dlab-berkeley/R-Fundamentals.git.

Is R not working on your laptop?

If you do not have R installed and the materials loaded on your workshop by the time it starts, we strongly recommend using the UC Berkeley DataHub to run the materials for these lessons. You can access the DataHub by clicking the following button:

Some users may have to click the link twice if the materials do not load initially.

The DataHub downloads this repository, along with any necessary packages, and allows you to run the materials in an RStudio instance on UC Berkeley's servers. No installation is needed from your end - you only need an internet browser and a CalNet ID to log in. By using the DataHub, you can save your work and come back to it at any time. When you want to return to your saved work, go straight to DataHub, sign in, and click on the R-Fundamentals folder.

If you don't have a Berkeley CalNet ID, you can still run these lessons in the cloud, by clicking this button:

If you are loading Binder with this repository for the first time, it may take a few minutes to set up. Binder operates similarly to the D-Lab DataHub, but on a different set of servers. By using Binder, however, you cannot save your work.

Run the Code

Now that you have all the required software and materials, you need to run the code.

1. Launch the RStudio software.

2. Use the file navigator to find the R-Fundamentals folder you downloaded from Github. Open R-Fundamentals.Rproj by double clicking on the file.

3. Open up the file corresponding to the part of the workshop you're attending (Part1.Rmd, Part2.Rmd, Part3.Rmd, Part4.Rmd) via the Files panel in RStudio.

4. Place your cursor on a given line and press Command + Enter (Mac) or Control + Enter (PC) to run an individual line of code.

5. The solutions folder contains the solutions to the challenge problems.

Additional Resources

Check out the following online resources to learn more about R:

• Software Carpentry
• Quick-R
• UCLA Institute for Digital Research and Education
• R-bloggers
• R Markdown: The Definitive Guide
• The tidyverse style guide

as well as the following books:

• Bookdown Featured Books
• Introduction to Probability and Statistics in R by G. Jay Kearns.
• Advanced R by Hadley Wickham.
• R for Data Science by Hadley Wickham and Garrett Grolemund.
• R for Everyone by Jared Lander.
• Art of R Programming by Norman Matloff.

About the UC Berkeley D-Lab

D-Lab works with Berkeley faculty, research staff, and students to advance data-intensive social science and humanities research. Our goal at D-Lab is to provide practical training, staff support, resources, and space to enable you to use R for your own research applications. Our services cater to all skill levels and no programming, statistical, or computer science backgrounds are necessary. We offer these services in the form of workshops, one-to-one consulting, and working groups that cover a variety of research topics, digital tools, and programming languages.

Visit the D-Lab homepage to learn more about us. You can view our calendar for upcoming events, learn about how to utilize our consulting and data services, and check out upcoming workshops.

Other D-Lab [Language] Workshops

D-Lab offers a variety of R workshops, catered toward different levels of expertise.

Basic Competency

• R Data Wrangling
• R Data Visualization
• R Census Data

Intermediate/Advanced Competency

• R Geospatial Fundamentals
• R Machine Learning
• R Deep Learning

Contributors

Provide a list of contributors here, with links to their webpages (D-Lab or private).

r-fundamentals's Issues

Part 3: Small grammatical issues here and there

There are a smattering of very small grammatical issues/typos in Part 3. It's worth going through it to try and get all of them.

Here are a couple examples:

"Before we get started, lets load in the..."
"In Part 2 we learned to read in a csv file and assign it to a data frame called gap. Lets do that again."

Update "Insert Code Chunk" text

Instructions for inserting a code chunk (Part 1, lines 56-62) appear out of date.

Option 1 should be Code > Insert Chunk.

Part 2 - potentially add data frame indexing example

Line 317: notebook currently mentions that you can use numeric indexing with the [row,column] format to subset a dataframe, but doesn't show any examples of what this looks like. Recommend adding in a code chunk that gives a few examples, which could look something like:

# extract the first value of the first column
gap[1,1]

# extract the entire first row
gap[1,]

# extract the entire third column
gap[,3]

R Proj file

The R Proj file is still called pilot and needs to be renamed

input vs. arguments explainer in Lesson 2

line 71-75

1. input - the object that the function is operating on.
2. arguments - modifications we make to the function (the first argument is usually the input).

this explainer may not be needed since they are essentially the same thing

Add tidyverse

Part 2-- Please add a line to load tidyverse along with the other packages.

Cut down time on factors in Part 3

• its a long time just talking about factors - cut this down or intersperse a challenge/poll in it
• factors() questions is confusing for people - they thought we should factorize pop not continent b/c I mentioned pop, also people tried to change the pop table code → make this an easier question
  → could cut factors down a lot (or at least ordered)

Minor typos in lesson 3

In lesson 3, "# return all rows in Asia with a GSP per capita above or equal to 30K"
GSP should be GDP

Part 2 - spell check

Check for spelling errors

Part 2- typo

There is a typo in the R Fun 2-1: seq() poll for option 3.

Minor Typo in Lesson 2

1. line 53:
   Instead of 🥊 Challenge 1: Manipulating vVectors should this just be 🥊 Challenge 1: Manipulating Vectors (removing the v)

Part 4 - missing text

Lines 52-53 currently read as follows:

In Part 3 we used `summary()`, `table()`, and `mean()` to learn some things about our data. For example:
CLEAN UP

Examples appear to be missing, and it moves straight on to the challenge.

Part 3 - install rtools

We ran into the issue of installing rtools during the workshop today. (Jose & Mingyu)

Make a note in Part 3 (also possibly in the end of Part 2) that rtools need to be installed for PC users to install tidyverse properly.

It is worth mentioning this at the end of Part 2 to leave folks more time to figure this out so as to avoid spending time on this during Part 3.

Part 1 - get rid of list for running chunks

In Part 1 - writing and running code chunk section is awkward b/c you can’t insert chunks within a list - make it not a list

Part 3 - gap_subset

gap_subset gets introduced during the select() function portion but then gets re-written in challenge 3. This is a bit awkward and perhaps a more informative name in challenge 3 would be helpful.

Clarify instructions in Part 4 Challenge 4

Clarify in Challenge 4 instructions that people should avoid using country for grouping category, as it makes the legend too large and the plot unreadable

Part 1 - Run code chunk

Lines 64-70: Possibly add that people can use the "Run" button in the top right of the notebook panel.

The text could be revised to the following (additions in bold).

1.  Click the small green play button at the top right of the chunk - this will run all the code inside the chunk.

2.  Use the keyboard shortcut **Shift + Ctrl + Enter** (windows) or **Shift + Cmd + Enter** (mac) - this will run all the code inside the chunk. **Alternatively, click the "Run" button in the top right corner of the notebook panel and select "Run Current Chunk" from the dropdown list.**

3.  Use the keyboard shortcut **Ctrl + Enter** (windows) or **Cmd + Enter** (mac) - this will run the single line of code your cursor is on. **Alternatively, click the "Run" button in the top right corner of the notebook panel and select "Run Selected Line(s)" from the dropdown list.**

Variable not created

Part 1, Line 151: rm(name) is run before a "name" variable is created. Either create a name variable, or input a different variable to remove.

Add to input warning in Lesson 2

line 84

⚠️ Warning: Not all functions have inputs or arguments - for example, the ls() function doesn't require an input but still gives us an output.

should also include a warning for not all function has an output (with example)

Commas no longer needed in base R indexing

In indexing - do we not need data.frame[ , “pop”] anymore? Why do we not need to comma anymore?

Part 3: Consider removing summary()

Part 3 still felt a little tight today (8/16). We could consider removing summary() and just jumping right into missing values.

Update solutions now that some challenges have moved lessons

Also is.na() poll has become a challenge now

Part 2 - demo

Need to load in tidyverse package before running the demo because uses filter() and select()
Also add in text explaining that we will be subsetting rows in Part 3 (b/c Part 2 only subsets columns)

Day 2

Poll 2-1 is missing from the R zoom meeting template. It needs to be added in. @aculich What is the default SPA zoom account for R workshops.

Move material to Parts 3 and 4 where there is more time

Part 1 - Got through everything except Challenge 4, using length() and the demo
Part 2 - Didn’t do challenge 1 b/c it felt like we had too much from having just done the end of Part 1 → generally feels like a bit much on vectors. Got through to just before Challenge 4
Part 3 - Got through to challenge 4
Part 4 - Didn't do custom functions

Part 4 - incorrect text

Lines 196-197:

Commented lines within function say that the continent argument is now named cont, while the function argument is still continent_name

  # every time we would have written the continent, we now write 'cont'
  # limit to continent cont

Bring in functions to Part 1

seq() poll gets us into questions about the arguments of functions and we haven’t talked about functions yet → need a place in Part 1 where we talk about functions high level

README - disclaimer about not needing to download stuff beforehand

Add information to the README (and maybe to the calendar invite) that participants do not need to download material in advance - instead we will spend the first half an hour of the workshop going over how to do this and making sure everyone is on the same page

confusing naming variable in Lesson 2

line 305:
naming a variable called "variables" is confusing and should be changed
variables <- c("pop" , "year", "lifeExp") gap[variables]

Key for lesson 3 needs to be updated (typo)

fill in a conditional statement in filter to keep only rows with non-missing values of gdpPercap

gap_nomissing <- gap %>%
filter(!is.na(gdpPercapita))

gdpPercapita should be gdpPercap

So updated should be:

gap_nomissing <- gap %>%
filter(!is.na(gdpPercap))

tidyverse repeat in Part 3

unclear if this chunk of code should be run

# install the tidyverse package - note the name of the package needs to be in quotes
install.packages("tidyverse")

# load the package into the current R session - note the name of the package doesn't need to be in quotes (!) and you can use tab complete to see a list of installed packages
library(tidyverse)

# check that tidyverse has been loaded
?tidyverse

solution in Part 3

insteadd of gap <- read.csv("./data/gapminder.csv") should be gap <- read.csv("../data/gapminder.csv")

Run code chunk shortcut

Introduce "Shift-Command-Enter" / "Shift-Control-Enter" as shortcut for running code chunks

mean function comment in Part 4

majority of the lesson uses the pipe operator
not sure if we want to use the pull function for the mean function or summarize to make it more in sync

Part 4 - typo

Line 107:

Text reads summary(gap_africa$lifeExp) when it should read summary(gap_europe$lifeExp)

Part 2 - poll and demo

1. Poll 2-1 has a typo where the third option should say seq(from= ...) and not seq(from- ...)
2. Maybe the demo should not introduce tidyverse and we should use indexing to choose rows. Students don't know what tidyverse is and haven't installed it so they may be quite confused seeing it out of the blue!

Part 4 - reorganization

Notes from Mingyu after teaching R Fundamentals:
In Part 4, we feel it makes more sense to introduce R functions first, and then move forward to ggplot. Start with an even simpler function, perhaps referring to the functions that have been introduced to participants in previous sessions. The syntax/grammar of ggplot may look intimidating to folks; leave it to the end and link it to the R data viz workshop.

Suggestions from discussion with Mingyu and Hero

• Move custom functions section to first half of Part 4
• Need to change motivating example from ggplot example to one about workflow (eg. say you want to print out the mean and percent missing for different variables. You write out the same line of code 6 times but you make a typo with one of them --> this is a good time to make a function that takes variable name as input and prints out the mean and percent missing as output)
• Move ggplot to after custom functions
• Final demo shows ggplot inside a function --> motivates going to R Data Wrangling and R Data Vis

Part 4 - solutions

In challenge 4 we reference logging one of the variables but do not provide information about what logging is. Should provide a link to what it means to log a variable (can also consider providing link to longer more detailed discussing on StackOverflow about when to log a variable: https://stats.stackexchange.com/questions/298/in-linear-regression-when-is-it-appropriate-to-use-the-log-of-an-independent-va)