---
title: "Introduction to R and RStudio"
author: "Your Names Here"
output:
  html_document:
    highlight: pygments
    theme: cerulean
    toc: true
    toc_float: true
---

```{r global_options, include=FALSE}
knitr::opts_chunk$set(eval = TRUE)
library(dplyr)
library(ggplot2)
library(oilabs)
```


## The RStudio Interface

The goal of this lab is to introduce you to R and RStudio, which you'll be using
throughout the course both to learn the statistical concepts discussed in the 
course and to analyze real data and come to informed conclusions. To clarify
which is which: R is the name of the programming language itself and RStudio 
is a convenient interface.

As the labs progress, you are encouraged to explore beyond what the labs dictate;
a willingness to experiment will make you a much better programmer. Before we 
get to that stage, however, you need to build some basic fluency in R. Today we
begin with the fundamental building blocks of R and RStudio: the interface, 
reading in data, and basic commands.

Go ahead and launch RStudio. You should see a window that looks like the image 
shown below.

<br>


The panel on the lower left is where the action happens. It's called the *console*. 
Everytime you launch RStudio, it will have the same text at the top of the 
console telling you the version of R that you're running. Below that information
is the *prompt*. As its name suggests, this prompt is really a request: a 
request for a command. Initially, interacting with R is all about typing commands
and interpreting the output. These commands and their syntax have evolved over
decades (literally) and now provide what many users feel is a fairly natural way
to access data and organize, describe, and invoke statistical computations.

The panel in the upper right contains your *workspace* as well as a history of 
the commands that you've previously entered. 

Any plots that you generate will show up in the panel in the lower right corner. 
This is also where you can browse your files, access help, manage packages, etc.

### Loading This Lab Into RStudio

There are 5 steps to getting this lab loaded into R Studio:

1. Download the .Rmd file from the course website, and save it on your laptop in a place where you'll be able to find it.

2. In RStudio, go to the Files panel in the lower right (you may already be there).


3. Click the "New Folder" button to make a folder for this lab.  You could call it "lab1".  Then click on the folder name to go into it.

4. Click the "Upload" button to upload the .Rmd file you downloaded in step 1 from your laptop to the RStudio server.

5. Click on the file in the RStudio to open it.

### R Packages

R is an open-source programming language, meaning that users can contribute
packages that make our lives easier, and we can use them for free. For this lab,
and many others in the future, we will use the following R packages:

- *dplyr*: for data wrangling
- *ggplot2*: for data visualization
- *oilabs*: for data

In order to use the functions and data provided by these packages, you need to
load them in your working environment. We do this with the `library` function.
Run the following three lines:

```{r load-packages, message = FALSE, eval=TRUE}
library(dplyr)
library(ggplot2)
library(oilabs)
```
You can do this by

- putting your cursor on the line and clicking the **Run** button on the upper right 
corner of the pane, or
- typing the code in the console.

From now on, it's best to use the **Run** button to run code that is entered in
an R chunk in the R Markdown document.  That way, you'll always have a record of
everything you've done.

Note that dplyr and ggplot2 are part of a collection of R packages called
the *tidyverse*. These packages share common philosophies and are designed to 
work together. You can find more about the packages in the tidyverse at
http://tidyverse.org/ (but this is not critical reading for today's lab).


## Dr. Arbuthnot's Baptism Records

To get you started, run the following command to load the data.

```{r load-abrbuthnot-data, eval=TRUE}
data(arbuthnot)
```

This command instructs R to load some data: 
the Arbuthnot baptism counts for boys and girls (note that all babies were
classified as either a boy or a girl -- this is a limitation of the data). You should see that the
workspace area in the upper righthand corner of the RStudio window now lists a 
data set called `arbuthnot` that has 82 observations on 3 variables. As you 
interact with R, you will create a series of objects. Sometimes you load them as
we have done here, and sometimes you create them yourself as the byproduct of a 
computation or some analysis you have performed.

The Arbuthnot data set refers to Dr. John Arbuthnot, an 18<sup>th</sup> century 
physician, writer, and mathematician. He was interested in the ratio of newborn
boys to newborn girls, so he gathered the baptism records for children born in
London for every year from 1629 to 1710. We can view the data by 
typing its name into the console.

```{r view-data}
arbuthnot
```

However printing the whole dataset in the console is not that useful. 
One advantage of RStudio is that it comes with a built-in data viewer. Click on
the name `arbuthnot` in the *Environment* pane (upper right window) that lists 
the objects in your workspace. This will bring up an alternative display of the 
data set in the *Data Viewer* (upper left window). You can close the data viewer
by clicking on the `x` in the upper lefthand corner.

What you should see are four columns of numbers, each row representing a 
different year: the first entry in each row is simply the row number (an index 
we can use to access the data from individual years if we want), the second is 
the year, and the third and fourth are the numbers of boys and girls baptized 
that year, respectively. Use the scrollbar on the right side of the console 
window to examine the complete data set.

Note that the row numbers in the first column are not part of Arbuthnot's data. 
R adds them as part of its printout to help you make visual comparisons. You can
think of them as the index that you see on the left side of a spreadsheet. In 
fact, the comparison to a spreadsheet will generally be helpful. R has stored 
Arbuthnot's data in a kind of spreadsheet or table called a *data frame*.

You can see the dimensions of this data frame as well as the names of the variables 
and the first few observations by running the following command:

```{r glimpse-data}
str(arbuthnot)
```

We can see that there are 82 observations and 3 variables in this dataset. The
variable names are `year`, `boys`, and `girls`. At this point, you might notice 
that many of the commands in R look a  lot like functions from math class; that 
is, invoking R commands means supplying a function with some number of arguments. 
The `str` command, for example, took a single argument, the name of a data frame. 

## Some Exploration

Let's start to examine the data a little more closely. We can access the data in
a single column of a data frame separately using a command like

```{r view-boys}
arbuthnot$boys
```

This command will only show the number of boys baptized each year. The dollar
sign basically says "go to the data frame that comes before me, and find the 
variable that comes after me".

#### EXERCISE 1. What command would you use to extract just the counts of girls baptized? Try it!

SOLUTION: Enter your R code in the chunk below, then run the code.

```{r view-girls}

```
    
Notice that the way R has printed these data is different. When we looked at the
complete data frame, we saw 82 rows, one on each line of the display. These data
are no longer structured in a table with other variables, so they are displayed 
one right after another. Objects that print out in this way are called *vectors*; 
they represent a set of numbers. R has added numbers in [brackets] along the left
side of the printout to indicate locations within the vector. For example, 5218 
follows [1], indicating that 5218 is the first entry in the vector. And if [43] 
starts a line, then that would mean the first number on that line would represent
the 43rd entry in the vector.


### Data visualization

R has some powerful functions for making graphics. We can create a simple plot 
of the number of girls baptized per year with the command

```{r plot-girls-vs-year}
ggplot() +
  geom_line(mapping = aes(x = year, y = girls), data = arbuthnot)
```

The plot should appear under the *Plots* tab of the lower right panel of RStudio.
We're going to really dive into understanding how to make plots next week.
For now, notice four things about the command to make the plot:

 1. We use `ggplot() +` to start a new plot.  The `+` at the end of the line
 signals that we're going to add a layer to the plot.
 
 2. We use the `geom_line()` function to plot the data using a line
 
 3. The first argument to `geom_line()` tells `R` to map the year variable to
 the horizontal (x) axis and the girls variable to the vertical (y) axis.
 
 4. The second argument to `geom_line()` tells `R` that it can find those
 variables in the `arbuthnot` data frame.



#### EXERCISE 2. Is there an apparent trend in the number of girls baptized over the years? How would you describe it?

SOLUTION:  (Type your answer here)

### R as a big calculator

Now, suppose we want to plot the total number of baptisms. To compute this, we 
could use the fact that R is really just a big calculator. We can type in 
mathematical expressions like

```{r calc-total-bapt-numbers}
5218 + 4683
```

to see the total number of baptisms in 1629. We could repeat this once for each 
year, but there is a faster way. If we add the vector for baptisms for boys to 
that of girls, R will compute all sums simultaneously.

```{r calc-total-bapt-vars}
arbuthnot$boys + arbuthnot$girls
```

What you will see are 82 numbers (in that packed display, because we aren’t 
looking at a data frame here), each one representing the sum we’re after. Take a
look at a few of them and verify that they are right.

### Adding a new variable to the data frame

We'll be using this new vector to generate some plots, so we'll want to save it 
as a permanent column in our data frame.

```{r calc-total-bapt-vars-save}
arbuthnot <- arbuthnot %>%
  mutate(total = boys + girls)
```

The `%>%` operator is called the **piping** 
operator. It takes the output of the previous expression and pipes it into 
the first argument of the function in the following one. 
To continue our analogy with mathematical functions, `x %>% f(y)` is 
equivalent to `f(x, y)`.

**A note on piping: ** Note that we can read these three lines of code as the following: 

*"Take the `arbuthnot` dataset and **pipe** it into the `mutate` function. 
Mutate the `arbuthnot` data set by creating a new variable called `total` that is the sum of the variables
called `boys` and `girls`. Then assign the resulting dataset to the object
called `arbuthnot`, i.e. overwrite the old `arbuthnot` dataset with the new one
containing the new variable."*

This is equivalent to going through each row and adding up the `boys` 
and `girls` counts for that year and recording that value in a new column called
`total`.

**Where is the new variable? ** When you make changes to variables in your dataset, 
click on the name of the dataset again to update it in the data viewer.

You'll see that there is now a new column called `total` that has been tacked on
to the data frame. The special symbol `<-` performs an *assignment*, taking the 
output of one line of code and saving it into an object in your workspace. In 
this case, you already have an object called `arbuthnot`, so this command updates
that data set with the new mutated column.

We can make a plot of the total number of baptisms per year with the command

```{r plot-total-vs-year}
ggplot() +
  geom_line(mapping = aes(x = year, y = total), data = arbuthnot)
```

Similarly to how we computed the total number of births, we can compute the ratio 
of the number of boys to the number of girls baptized in 1629 with

```{r calc-prop-boys-to-girls-numbers}
5218 / 4683
```

or we can act on the complete columns with the expression

```{r calc-prop-boys-to-girls-vars}
arbuthnot <- arbuthnot %>%
  mutate(boy_to_girl_ratio = boys / girls)
```

We can also compute the proportion of newborns that are boys in 1629

```{r calc-prop-boys-numbers}
5218 / (5218 + 4683)
```

or this may also be computed for all years simultaneously and append it to the dataset:

```{r calc-prop-boys-vars}
arbuthnot <- arbuthnot %>%
  mutate(boy_ratio = boys / total)
```

Note that we are using the new `total` variable we created earlier in our calculations.

#### EXERCISE 3. Now, generate a plot of the proportion of boys born over time. What do you see? 

SOLUTION: Enter your R code in the chunk below, then run the code, and describe in words the trend you see.

```{r plot-boy-ratio}

```

Finally, in addition to simple mathematical operators like subtraction and 
division, you can ask R to make comparisons like greater than, `>`, less than,
`<`, and equality, `==`. For example, we can ask if boys outnumber girls in each 
year with the expression

```{r boys-more-than-girls}
arbuthnot <- arbuthnot %>%
  mutate(more_boys = boys > girls)
```

This command add a new variable to the `arbuthnot` dataframe containing the values
of either `TRUE` if that year had more boys than girls, or `FALSE` if that year 
did not (the answer may surprise you). This variable contains a different kind of 
data than we have encountered so far. All other columns in the `arbuthnot` data 
frame have values that are numerical (the year, the number of boys and girls). Here, 
we've asked R to create *logical* data, data where the values are either `TRUE` 
or `FALSE`. In general, data analysis will involve many different kinds of data 
types, and one reason for using R is that it is able to represent and compute 
with many of them.

* * *

## More Practice

In the previous few pages, you recreated some of the displays and preliminary 
analysis of Arbuthnot's baptism data. Your assignment involves repeating these 
steps, but for present day birth records in the United States. Load the 
present day data with the following command.

```{r load-present-data}
data(present)
```

The data are stored in a data frame called `present`.

#### EXERCISE 4.  What years are included in this data set? What are the dimensions of the data frame? What are the variable (column) names?

SOLUTION: (Type your answer here)

#### EXERCISE 5.  How do these counts compare to Arbuthnot's? Are they of a similar magnitude?

SOLUTION: (Type your answer here)

#### EXERCISE 6.  In what year did we see the most total number of births in the U.S.?

*Hint:* First calculate the totals and save it as a new variable. You can do
this by copying the code we used to calculate the totals for Arbuthnot's data
above, and modifying the data frame that is used in the calculation.  Then,
sort your dataset in descending order based on the total column. You can do this
interactively in the data viewer by clicking on the arrows next to the 
variable names. To include the sorted result in your report you will need 
to use two new functions: `arrange` (for sorting). We can arrange the data 
in a descending order with another function: `desc` (for descending order).
Sample code for this second step is provided below.

```{r sample-arrange, eval=FALSE}
present %>%
  arrange(desc(total))
```

SOLUTION: 

```{r most-births}

```

#### EXERCISE 7.  Make a plot that displays the proportion of boys born over time. What do you see? Does Arbuthnot's observation about boys being born in greater proportion than girls hold up in the U.S.? Include the plot in your response.

*Hint:* You can base your code on the code above that calculated the boy_ratio
variable.  Copy the code above that we used to perform these calculations for
the `arbuthnot` data set. Then, replace the dataframe name.  Similarly, you
should be able to modify the code you used for Exercise 3 to make the plot.

SOLUTION:

```{r plot-boy-ratio-present}

```


## Resources for learning R and working in RStudio

That was a short introduction to R and RStudio, but we will provide you with more
functions and a more complete sense of the language as the course progresses. 

In this course we will be using R packages called dplyr for data wrangling 
and ggplot2 for data visualization. If you are googling for R code, make sure
to also include these package names in your search query. For example, instead
of googling "scatterplot in R", google "scatterplot in R with ggplot2".

These cheatsheets may come in handy throughout the semester:

- [RMarkdown cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)
- [Data transformation cheatsheet](https://github.com/rstudio/cheatsheets/raw/master/source/pdfs/data-transformation-cheatsheet.pdf)
- [Data visualization cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/11/ggplot2-cheatsheet-2.1.pdf)

Note that some of the code on these cheatsheets may be too advanced for this course,
however the majority of it will become useful throughout the semester.


<div id="license">
This is a product of OpenIntro that is released under a 
[Creative Commons Attribution-ShareAlike 3.0 Unported](http://creativecommons.org/licenses/by-sa/3.0). 
This lab was adapted for OpenIntro by Andrew Bray and Mine &Ccedil;etinkaya-Rundel
from a lab written by Mark Hansen of UCLA Statistics.  It was then further modified by Evan Ray.
</div>
