transform.Rmd

---
layout: default
title: Transform
---

# Data transformation {#transform}

```{r setup-transform, include = FALSE}
library(dplyr)
library(nycflights13)
library(ggplot2)
source("common.R")
options(dplyr.print_min = 6)
```

Visualisation is an important tool for insight generation, but it is rare that you get the data in exactly the right form you need for visualisation. Often you'll need to create some new variables or summaries, or maybe you just want to rename the variables or reorder the observations in order to make the data a little easier to work with. You'll learn how to do all that (and more!) in this chapter which will teach you how to transform your data using the dplyr package.

When working with data you must:

1. Figure out what you want to do.

1. Precisely describe what you want to do in such a way that the
   compute can understand it (i.e. program it).

1. Execute the program.

The dplyr package makes these steps fast and easy:

* By constraining your options, it simplifies how you can think about 
  common data manipulation tasks.

* It provides simple "verbs", functions that correspond to the most 
  common data manipulation tasks, to help you translate those thoughts 
  into code.

* It uses efficient data storage backends, so you spend less time 
  waiting for the computer.

In this chapter you'll learn the key verbs of dplyr in the context of a new dataset on flights departing New York City in 2013.

## Data: nycflights13

To explore the basic data manipulation verbs of dplyr, we'll start with the built in
`nycflights13` data frame. This dataset contains all `r format(nrow(nycflights13::flights), big.mark = ",")` flights that departed from New York City in 2013. The data comes from the US [Bureau of Transportation Statistics](http://www.transtats.bts.gov/DatabaseInfo.asp?DB_ID=120&Link=0), and is documented in `?nycflights13`.

```{r}
library(dplyr)
library(nycflights13)
flights
```

The first important thing to notice about this dataset is that it prints a little differently to most data frames: it only shows the first ten rows and all the columns that fit on one screen. If you want to see the whole dataset, use `View()` which will open the dataset in the RStudio viewer.

It also prints an abbreviated description of the column type:

* int: integer
* dbl: double (real)
* chr: character
* lgl: logical
* date: dates
* time: times

It prints differently because it has a different "class" to usual data frames:

```{r}
class(flights)
```

This is called a `tbl_df` (prounced tibble diff) or a `data_frame` (pronunced "data underscore frame"; cf. `data dot frame`)

You'll learn more about how that works in data structures. If you want to convert your own data frames to this special case, use `as.data_frame()`. I recommend it for large data frames as it makes interactive exploration much less painful.

To create your own new tbl\_df from individual vectors, use `data_frame()`:

```{r}
data_frame(x = 1:3, y = c("a", "b", "c"))
```

--------------------------------------------------------------------------------

There are two other important differences between tbl_dfs and data.frames:

*   When you subset a tbl\_df with `[`, it always returns another tbl\_df. 
    Contrast this with a data frame: sometimes `[` returns a data frame and
    sometimes it just returns a single column:
    
    ```{r}
    df1 <- data.frame(x = 1:3, y = 3:1)
    class(df1[, 1:2])
    class(df1[, 1])
    
    df2 <- data_frame(x = 1:3, y = 3:1)
    class(df2[, 1:2])
    class(df2[, 1])
    ```
    
    To extract a single column use `[[` or `$`:
    
    ```{r}
    class(df2[[1]])
    class(df2$x)
    ```

*   When you extract a variable with `$`, tbl\_dfs never do partial 
    matching. They'll throw an error if the column doesn't exist:
    
    ```{r, error = TRUE}
    df <- data.frame(abc = 1)
    df$a
    
    df2 <- data_frame(abc = 1)
    df2$a
    ```

--------------------------------------------------------------------------------
    
## Dplyr verbs

At the most basic level, you can only alter a tidy data frame in five useful ways: 

* reorder the rows (`arrange()`), 
* pick observations by their values (`filter()`),
* pick variables by their names (`select()`), 
* create new variables with functions of existing variables (`mutate()`), or
* collapse many values down to a single summary (`summarise()`).

These can all be used in conjunction with `group_by()` which changes the scope of each function from operating on the entire dataset to operating on it group-by-group. These six functions verbs for a language of data manipulation.

All verbs work similarly: 

1.  The first argument is a data frame.

1.  The subsequent arguments describe what to do with the data frame. 
    You can refer to columns in the data frame directly without using `$`.

1.  The result is a new data frame.

Together these properties make it easy to chain together multiple simple steps to achieve a complex result.

## Filter rows with `filter()`

`filter()` allows you to subset observations. The first argument is the name of the data frame. The second and subsequent arguments are the expressions that filter the data frame. For example, we can select all flights on January 1st with:

```{r}
filter(flights, month == 1, day == 1)
```

When you run this line of code, dplyr executes the filtering operation and returns a new data frame. dplyr functions never modify their inputs, so if you want to save the results, you'll need to use the assignment operator `<-`:

```{r}
jan1 <- filter(flights, month == 1, day == 1)
```

--------------------------------------------------------------------------------

This is equivalent to the more verbose base code:

```{r, eval = FALSE}
flights[flights$month == 1 & flights$day == 1, , drop = FALSE]
```

(Although `filter()` will also drop missings). `filter()` works similarly to `subset()` except that you can give it any number of filtering conditions, which are joined together with `&`. 

--------------------------------------------------------------------------------

### Comparisons

R provides the standard suite of numeric comparison operators: `>`, `>=`, `<`, `<=`, `!=` (not equal), and `==` (equal). When you're starting out with R, the easiest mistake to make is to use `=` instead of `==` when testing for equality. When this happens you'll get a somewhat uninformative error:

```{r, error = TRUE}
filter(flights, month = 1)
```

But beware using `==` with floating point numbers:

```{r}
sqrt(2) ^ 2 == 2
1/49 * 49 == 1
```

It's better to check that you're close:

```{r}
abs(sqrt(2) ^ 2 - 2) < 1e-6
abs(1/49 * 49 - 1) < 1e-6
```

### Logical operators

Multiple arguments to `filter()` are combined with "and". To get more complicated expressions, you can use boolean operators yourself:

```{r, eval = FALSE}
filter(flights, month == 1 | month == 2)
```

Note the order isn't like English. This doesn't do what you expect:

```{r, eval = FALSE}
filter(flights, month == 1 | 2)
```

Instead you can use the helpful `%in%` shortcut:

```{r}
filter(flights, month %in% c(1, 2))
```

The following figure shows the complete set of boolean operations:

```{r bool-ops, echo = FALSE, fig.cap = "Complete set of boolean operations",  out.width = "75%"}
knitr::include_graphics("diagrams/transform-logical.png")
```

Sometimes you can simplify complicated subsetting by remembering De Morgan's law: `!(x & y)` is the same as `!x | !y`, and `!(x | y)` is the same as `!x & !y`. For example, if you wanted to find flights that weren't delayed (on arrival or departure) by more than two hours, you could use either of the following two filters:

```{r, eval = FALSE}
filter(flights, !(arr_delay > 120 | dep_delay > 120))
filter(flights, arr_delay <= 120, dep_delay <= 120)
```

Note that R has both `&` and `|` and `&&` and `||`. `&` and `|` are vectorised: you give them two vectors of logical values and they return a vector of logical values. `&&` and `||` are scalar operators: you give them individual `TRUE`s or `FALSE`s. They're used if `if` statements when programming. You'll learn about that later on.

Sometimes you want to find all rows after the first `TRUE`, or all rows until the first `FALSE`. The cumulative functions `cumany()` and `cumall()` allow you to find these values:

```{r}
df <- data_frame(
  x = c(FALSE, TRUE, FALSE), 
  y = c(TRUE, FALSE, TRUE)
)

filter(df, cumany(x)) # all rows after first TRUE
filter(df, cumall(y)) # all rows until first FALSE
```

Whenever you start using multipart expressions in your `filter()`, it's typically a good idea to make them explicit variables with `mutate()` so that you can more easily check your work. You'll learn about `mutate()` in the next section.

### Missing values

One important feature of R that can make comparison tricky is the missing value, `NA`. `NA` represents an unknown value so missing values are "infectious": any operation involving an unknown value will also be unknown.

```{r}
NA > 5
10 == NA
NA + 10
NA / 2
```

The most confusing result is this one:

```{r}
NA == NA
```

It's easiest to understand why this is true with a bit more context:

```{r}
# Let x be Mary's age. We don't know how old she is.
x <- NA

# Let y be John's age. We don't know how old he is.
y <- NA

# Are John and Mary the same age?
x == y
# We don't know!
```

If you want to determine if a value is missing, use `is.na()`. (This is such a common mistake RStudio will remind you whenever you use `x == NA`)

`filter()` only includes rows where the condition is `TRUE`; it excludes both `FALSE` and `NA` values. If you want to preserve missing values, ask for them explicitly:

```{r}
df <- data_frame(x = c(1, NA, 3))
filter(df, x > 1)
filter(df, is.na(x) | x > 1)
```

### Exercises

1.  Find all the flights that:

    * Departed in summer.
    * That flew to Houston (`IAH` or `HOU`).
    * There were operated by United, American, or Delta.
    * That were delayed by more two hours.
    * That arrived more than two hours late, but didn't leave late.
    * We delayed by at least an hour, but made up over 30 minutes in flight.
    * Departed between midnight and 6am.

1.  How many flights have a missing `dep_time`? What other variables are 
    missing? What might these rows represent?

## Arrange rows with `arrange()`

`arrange()` works similarly to `filter()` except that instead of filtering or selecting rows, it reorders them. It takes a data frame, and a set of column names (or more complicated expressions) to order by. If you provide more than one column name, each additional column will be used to break ties in the values of preceding columns:

```{r}
arrange(flights, year, month, day)
```

Use `desc()` to order a column in descending order:

```{r}
arrange(flights, desc(arr_delay))
```

Missing values always come at the end:

```{r}
df <- data_frame(x = c(5, 2, NA))
arrange(df, x)
arrange(df, desc(x))
```

--------------------------------------------------------------------------------

You can accomplish the same thing in base R using subsetting and `order()`:

```{r}
flights[order(flights$year, flights$month, flights$day), , drop = FALSE]
```

`arrange()` provides a more convenient way of sorting one variable in descending order with the `desc()` helper function.

--------------------------------------------------------------------------------

### Exercises

1.  How could use `arrange()` to sort all missing values to the start?
    (Hint: use `is.na()`).
    
1.  Sort `flights` to find the most delayed flights. Find the flights that
    left earliest.

## Select columns with `select()`

It's not uncommon to get datasets with hundreds or even thousands of variables. In this case, the first challenge is often narrowing in on the variables you're actually interested in. `select()` allows you to rapidly zoom in on a useful subset using operations based on the names of the variables:

```{r}
# Select columns by name
select(flights, year, month, day)
# Select all columns between year and day (inclusive)
select(flights, year:day)
# Select all columns except those from year to day (inclusive)
select(flights, -(year:day))
```

There are a number of helper functions you can use within `select()`:

* `starts_with("abc")`: matches names that begin with "abc".

* `ends_with("xyz")`: matches names that end with "xyz".

* `contains("ijk")`: matches name that contain "ijk".

* `matches("(.)\\1")`: selects variables that match a regular expression.  
   This one matches any variables that contain repeated characters. You'll 
   learn more about regular expressions in Chapter XYZ.
   
*  `num_range("x", 1:3)` matches `x1`, `x2` and `x3`.
   
See `?select` for more details.

It's possible to use `select()` to rename variables:

```{r}
select(flights, tail_num = tailnum)
```

But because `select()` drops all the variables not explicitly mentioned, it's not that useful. Instead, use `rename()`, which is a variant of `select()` that keeps variables by default:

```{r}
rename(flights, tail_num = tailnum)
```

--------------------------------------------------------------------------------

This function works similarly to the `select` argument in `base::subset()`. Because the dplyr philosophy is to have small functions that do one thing well, it's its own function in dplyr.

--------------------------------------------------------------------------------

### Exericses

1.  Brainstorm as many ways as possible to select `dep_time`, `dep_delay`,
    `arr_time`, and `arr_delay`.

## Add new variable with `mutate()`

Besides selecting sets of existing columns, it's often useful to add new columns that are functions of existing columns. This is the job of `mutate()`. 

`mutate()` always adds new columns at the end so we'll start by creating a narrower dataset so we can see the new variables. Remember that when you're in RStudio, the easiest way to see all the columns is `View()`

```{r}
flights_sml <- select(flights, 
  year:day, 
  ends_with("delay"), 
  distance, 
  air_time
)
mutate(flights_sml,
  gain = arr_delay - dep_delay,
  speed = distance / air_time * 60
)
```

Note that you can refer to columns that you've just created:

```{r}
mutate(flights_sml,
  gain = arr_delay - dep_delay,
  gain_per_hour = gain / (air_time / 60)
)
```

If you only want to keep the new variables, use `transmute()`:

```{r}
transmute(flights,
  gain = arr_delay - dep_delay,
  gain_per_hour = gain / (air_time / 60)
)
```

--------------------------------------------------------------------------------

`mutate()` is similar to `transform()` in base R, but in `mutate()` you can refer to variables you've just created; in `transform()` you can not.

--------------------------------------------------------------------------------

### Useful functions

There are many functions for creating new variables. The key property is that the function must be vectorised: it needs to return the same number of outputs as inputs. There's no way to list every possible function that you might use, but here's a selection of the functions that I use most often:

*   Arithmetic operators: `+`, `-`, `*`, `/`, `^`. These are all vectorised, so 
    you can work with multiple columns. These operations use "recycling rules"
    so if one parameter is shorter than the other, it will be automatically
    extended to be the same length. This is most useful when one of the 
    arguments is a single number: `airtime / 60`, `hours * 60 + minute`, etc.
    
    This is also useful in conjunction with the aggregate functions you'll 
    learn about later: `x / sum(x)` calculates a proportion, `y - mean(y)` the
    difference from the mean, ...
    
*   Modular arithmetic: `%/%` (integer divison) and `%%` (remainder).
    `x == y * (x %/% y) + (x %% y)`. Modular arithmetic is a handy tool because 
    it allows you to break integers up into pieces. For example, in the 
    flights dataset, you can compute `hour` and `minute` from `dep_time` with:
    
    ```{r}
    transmute(flights,
      dep_time,
      hour = dep_time %/% 100,
      minute = dep_time %% 100
    )
    ```
  
*   Logs: `log()`, `log2()`, `log10()`. Logarithms are an incredibly useful
    transformation for dealing with data that ranges over multiple orders of
    magnitude. They also convert multiplicative relationships to additive, a
    feature we'll come back to in modelling.
    
    All else being equal, I recommend using `log2()` because it's easy to
    interpret: an difference of 1 on the log scale corresponds to doubling on
    the original scale and a difference of -1 corresponds to halving.
  
*   Cumulative and rolling aggregates: R provides functions for running sums,
    products, mins and maxes: `cumsum()`, `cumprod()`, `cummin()`, `cummax()`.
    dplyr provides `cummean()` for cumulative means. If you need rolling
    aggregates, try `RcppRoll`.
  
*   Logical comparisons, which you learned about earlier. If you're doing
    a complex sequence of logical operations it's often a good idea to 
    store the interim values in new variables so you can check that each
    step is doing what you expect.

*   Offsets: `lead()` and `lag()` allow you to refer to leading or lagging 
    values. This allows you to compute running differences (e.g. `x - lag(x)`) 
    or find when values change (`x != lag(x))`. They are most useful in 
    conjunction with `group_by()`, which you'll learn about shortly.

*   Ranking: start with `min_rank()`. It does the most usual type of ranking 
    (e.g. 1st, 2nd, 2nd, 4th). The default gives smallest values the small
    ranks; use `desc(x)` to give the largest values the smallest ranks. 
    
    If `min_rank()` doesn't do what you need, look at the variants 
    `row_number()`, `dense_rank()`, `cume_dist()`, `percent_rank()`, 
    `ntile()`.

### Exercises

```{r, eval = FALSE, echo = FALSE}
flights <- flights %>% mutate(
  dep_time = hour * 60 + minute,
  arr_time = (arr_time %/% 100) * 60 + (arr_time %% 100),
  airtime2 = arr_time - dep_time,
  dep_sched = dep_time + dep_delay
)

ggplot(flights, aes(dep_sched)) + geom_histogram(binwidth = 60)
ggplot(flights, aes(dep_sched %% 60)) + geom_histogram(binwidth = 1)
ggplot(flights, aes(air_time - airtime2)) + geom_histogram()
```

1.  Currently `dep_time()` and `arr_time()` are convenient to look at, but
    hard to compute with because they're not really continuous numbers. 
    Convert them to a more convenient represention of number of minutes
    since midnight.
    
1.  Compute the scheduled time by adding `dep_delay` to `dep_time`. Plot
    the distribution of departure times. What do you think causes the 
    interesting pattern?
  
1.  Compare `airtime` with `arr_time - dep_time`. What do you expect to see?
    What do you see? Why?

## Grouped summaries with `summarise()`

The last verb is `summarise()`. It collapses a data frame to a single row:

```{r}
summarise(flights, delay = mean(dep_delay, na.rm = TRUE))
```

However, that's not terribly useful until we pair it with `group_by()`. This changes the unit of analysis from the complete dataset to individual groups. When you the dplyr verbs on a grouped data frame they'll be automatically applied "by group".

Grouping lets us compute average delay per day:

```{r}
by_day <- group_by(flights, year, month, day)
summarise(by_day, delay = mean(dep_delay, na.rm = TRUE))
```

### Useful summaries

You use `summarise()` with __aggregate functions__, which take a vector of values and return a single number. 

* Location of "middle": `mean(x)`, `median(x)`. The mean is the sum divided
  by the length; the median is a value where 50% of `x` is above, and 50% is
  below.

* Measure of spread: `sd(x)`, `IQR(x)`, `mad(x)`. The mean squared deviation,
  or standard deviation or sd for short, is the standard measure of spread.
  The interquartile range (`IQR()`) and median absolute deviation `mad(x)`
  are robust equivalents that maybe more useful if you have outliers.

* By rank: `min(x)`, `quantile(x, 0.25)`, `max(x)`.

* By position: `first(x)`, `nth(x, 2)`, `last(x)`. These work similarly to 
  `x[1]`, `x[length(x)]`, and `x[n]` but let you set a default value if that
  position does not exist (i.e. you're trying to get the 3rd element from a 
  group that only has two elements).

* Counts: `n()`. This takes no arguments, and refers to the current group size.
  To count the number of non-missing values, use `sum(!is.na(x))`. To count
  the number of distinct (unique) values, use `n_distinct(x)`.

* Counts and proportions of logical values: `sum(x > 10)`, `mean(y == 0)`
  When used with numeric functions, `TRUE` is converted to 1 and `FALSE` to 0. 
  This makes `sum()` and `mean()` particularly useful: `sum(x)` gives the number 
  of `TRUE`s in `x`, and `mean(x)` gives the proportion.

Aggregation functions generally obey the usual rules of missing values:

```{r}
mean(c(1, 5, 10, NA))
```

(`quantile()` is an exception - it throws an error if there are any missing values present). 

To make life easier, all aggregation functions have an `na.rm` argument which removes the missing values prior to computation:

```{r}
mean(c(1, 5, 10, NA), na.rm = TRUE)
```

### Exercises

## Multiple operations

Imagine we want to explore the relationship between the distance and average delay for each location. Using what you already know about dplyr, you might write code like this:

```{r, fig.width = 6}
by_dest <- group_by(flights, dest)
delay <- summarise(by_dest,
  count = n(),
  dist = mean(distance, na.rm = TRUE),
  delay = mean(arr_delay, na.rm = TRUE))
delay <- filter(delay, count > 20, dest != "HNL")

# Interesting it looks like delays increase with distance up to 
# ~750 miles and then decrease. Maybe as flights get longer there's
# more ability to make up delays in the air?
ggplot(delay, aes(dist, delay)) +
  geom_point(aes(size = count), alpha = 1/3) +
  geom_smooth(se = FALSE)
```

There are three steps:

* Group flights by destination

* Summarise to compute distance, average delay, and number of flights.

* Filter to remove noisy points and Honolulu airport which is almost
  twice as far away as the next closest airport.

This code is a little frustraing to write because we have to give each intermediate data frame a name, even though we don't care about it. Naming things well is hard, so this slows us down. There's another way to tackle the same problem with the pipe, `%>%`:

```{r}
delays <- flights %>% 
  group_by(dest) %>% 
  summarise(
    count = n(),
    dist = mean(distance, na.rm = TRUE),
    delay = mean(arr_delay, na.rm = TRUE)
  ) %>% 
  filter(delay, count > 20, dest != "HNL")
```

This focuses on the transformations, not what's being transformed, which makes the code easier to read. You can read it as a series of imperative statements: group, then summarise, then filter. As suggested by this reading, a good way to pronounce `%>%` when reading code is "then".

Behind the scenes, `x %>% f(y)` turns into `f(x, y)` so you can use it to rewrite multiple operations that you can read left-to-right, top-to-bottom. We'll use piping frequently from now on because it considerably improves the readability of code, and we'll come back to it in more detail in Chapter XYZ.

The pipe makes it easier to solve complex problems by joining together simple pieces. Each dplyr function does one thing well, helping you advance to your goal with one small step. You can check your work frequently, and if you get stuck, you just need to think: "what's one small thing I could do to advance towards a solution".

The rest of this section explores some practical uses of the pipe when combining multiple dplyr operations to solve real problems.

### Counts

Whenever you do any aggregation, it's always a good idea to include either a count (`n()`), or a count of non-missing values (`sum(!is.na(x))`). That way you can check that you're not drawing conclusions based on very small amounts of data amount of non-missing data.

For example, let's look at the flights that have the highest average delays:

```{r}
delays <- flights %>% 
  group_by(flight) %>% 
  summarise(
    delay = mean(arr_delay, na.rm = TRUE)
  )

ggplot(delays, aes(delay)) + 
  geom_histogram(binwidth = 10)
```

Wow, there are some flight with massive average delays. I sure wouldn't want to fly on one of those! 

Actually, the story is a little more nuanced. If we also compute the number of non-missing delays for each flight and draw a scatterplot:

```{r}
delays <- flights %>% 
  group_by(flight) %>% 
  summarise(
    delay = mean(arr_delay, na.rm = TRUE),
    n = sum(!is.na(arr_delay))
  )

ggplot(delays, aes(n, delay)) + 
  geom_point()
```

You'll see that most of the very delayed flight numbers happen very rarely. The shape of this plot is very characteristic: whenever you plot a mean (or many other summaries) vs number of observations, you'll see that the variation decreases as the sample size increases.

There's another variation on this type of plot as shown below. Here I use the Lahman package to compute the batting average (number of hits / number of attempts) of every major league baseball player.  When I plot the skill of the batter against the number of times batted, you see two patterns:

1.  As above, the variation in our aggregate decreases as we get more 
    data points.
    
2.  There's a correlation between skill and n. This is because baseball
    teams controls who gets to try and hit the ball, and obviously they'll
    pick their best players.

```{r}
batting <- tbl_df(Lahman::Batting)

batters <- batting %>% 
  group_by(playerID) %>% 
  summarise(
    ba = sum(H) / sum(AB),
    ab = sum(AB)
  ) %>% 
  filter(ab > 100)

ggplot(batters, aes(ab, ba)) +
  geom_point() + 
  geom_smooth(se = FALSE)
```

### Grouping by multiple variables

When you group by multiple variables, each summary peels off one level of the grouping. That makes it easy to progressively roll-up a dataset:

```{r}
daily <- group_by(flights, year, month, day)
(per_day   <- summarise(daily, flights = n()))
(per_month <- summarise(per_day, flights = sum(flights)))
(per_year  <- summarise(per_month, flights = sum(flights)))
```

However you need to be careful when progressively rolling up summaries like this: it's ok for sums and counts, but you need to think about weighting for means and variances, and it's not possible to do it exactly for medians.

### Grouped mutates (and filters)

* `mutate()` and `filter()` are most useful in conjunction with window 
  functions (like `rank()`, or `min(x) == x`). They are described in detail in 
  the windows function vignette `vignette("window-functions")`.

A grouped filter is basically like a grouped mutate followed by a regular filter. I generally avoid them except for quick and dirty manipulations. Otherwise it's too hard to check that you've done the manipulation correctly.

## Multiple tables of data

It's rare that a data analysis involves only a single table of data. In practice, you'll normally have many tables that contribute to an analysis, and you need flexible tools to combine them. In dplyr, there are three families of verbs that work with two tables at a time:

* Mutating joins, which add new variables to one table from matching rows in 
  another.

* Filtering joins, which filter observations from one table based on whether or 
  not they match an observation in the other table.

* Set operations, which combine the observations in the data sets as if they 
  were set elements.

(This discussion assumes that you have [tidy data](http://www.jstatsoft.org/v59/i10/), where the rows are observations and the columns are variables. If you're not familiar with that framework, I'd recommend reading up on it first.)

All two-table verbs work similarly. The first two arguments are `x` and `y`, and provide the tables to combine. The output is always a new table with the same type as `x`.

### Mutating joins

Mutating joins allow you to combine variables from multiple tables. For example, take the nycflights13 data. In one table we have flight information with an abbreviation for carrier, and in another we have a mapping between abbreviations and full names. You can use a join to add the carrier names to the flight data:

```{r, warning = FALSE}
library("nycflights13")
# Drop unimportant variables so it's easier to understand the join results.
flights2 <- flights %>% select(year:day, hour, origin, dest, tailnum, carrier)

flights2 %>% 
  left_join(airlines)
```

#### Controlling how the tables are matched

As well as `x` and `y`, each mutating join takes an argument `by` that controls which variables are used to match observations in the two tables. There are a few ways to specify it, as I illustrate below with various tables from nycflights13:

  * `NULL`, the default. dplyr will will use all variables that appear in 
    both tables, a __natural__ join. For example, the flights and 
    weather tables match on their common variables: year, month, day, hour and 
    origin.
    
    ```{r}
    flights2 %>% left_join(weather)
    ```

  * A character vector, `by = "x"`. Like a natural join, but uses only 
    some of the common variables. For example, `flights` and `planes` have 
    `year` columns, but they mean different things so we only want to join by 
    `tailnum`.
    
    ```{r}
    flights2 %>% left_join(planes, by = "tailnum")
    ```
    
    Note that the year columns in the output are disambiguated with a suffix.

  * A named character vector: `by = c("x" = "a")`. This will
    match variable `x` in table `x` to variable `a` in table `b`. The 
    variables from use will be used in the output.
    
    Each flight has an origin and destination `airport`, so we need to specify
    which one we want to join to:
    
    ```{r}
    flights2 %>% left_join(airports, c("dest" = "faa"))
    flights2 %>% left_join(airports, c("origin" = "faa"))
    ```

#### Types of join

There are four types of mutating join, which differ in their behaviour when a match is not found. We'll illustrate each with a simple example:

```{r}
(df1 <- data_frame(x = c(1, 2), y = 2:1))
(df2 <- data_frame(x = c(1, 3), a = 10, b = "a"))
```

  * `inner_join(x, y)` only includes observations that match in both `x` and `y`.
    
    ```{r}
    df1 %>% inner_join(df2) %>% knitr::kable()
    ```
    
  * `left_join(x, y)` includes all observations in `x`, regardless of whether
    they match or not. This is the most commonly used join because it ensures 
    that you don't lose observations from your primary table.
  
    ```{r}
    df1 %>% left_join(df2)
    ```
  
  * `right_join(x, y)` includes all observations in `y`. It's equivalent to 
    `left_join(y, x)`, but the columns will be ordered differently.
  
    ```{r}
    df1 %>% right_join(df2)
    df2 %>% left_join(df1)
    ```

* `full_join()` includes all observations from `x` and `y`.

    ```{r}
    df1 %>% full_join(df2)
    ```

The left, right and full joins are collectively know as __outer joins__. When a row doesn't match in an outer join, the new variables are filled in with missing values.

#### Observations

While mutating joins are primarily used to add new variables, they can also generate new observations. If a match is not unique, a join will add all possible combinations (the Cartesian product) of the matching observations:

```{r}
df1 <- data_frame(x = c(1, 1, 2), y = 1:3)
df2 <- data_frame(x = c(1, 1, 2), z = c("a", "b", "a"))

df1 %>% left_join(df2)
```

### Filtering joins

Filtering joins match obserations in the same way as mutating joins, but affect the observations, not the variables. There are two types:

* `semi_join(x, y)` __keeps__ all observations in `x` that have a match in `y`.
* `anti_join(x, y)` __drops__ all observations in `x` that have a match in `y`.

These are most useful for diagnosing join mismatches. For example, there are many flights in the nycflights13 dataset that don't have a matching tail number in the planes table:

```{r}
library("nycflights13")
flights %>% 
  anti_join(planes, by = "tailnum") %>% 
  count(tailnum, sort = TRUE)
```

If you're worried about what observations your joins will match, start with a `semi_join()` or `anti_join()`. `semi_join()` and `anti_join()` never duplicate; they only ever remove observations. 

```{r}
df1 <- data_frame(x = c(1, 1, 3, 4), y = 1:4)
df2 <- data_frame(x = c(1, 1, 2), z = c("a", "b", "a"))

# Four rows to start with:
df1 %>% nrow()
# And we get four rows after the join
df1 %>% inner_join(df2, by = "x") %>% nrow()
# But only two rows actually match
df1 %>% semi_join(df2, by = "x") %>% nrow()
```

### Set operations

The final type of two-table verb is set operations. These expect the `x` and `y` inputs to have the same variables, and treat the observations like sets:

* `intersect(x, y)`: return only observations in both `x` and `y`
* `union(x, y)`: return unique observations in `x` and `y`
* `setdiff(x, y)`: return observations in `x`, but not in `y`.

Given this simple data:

```{r}
(df1 <- data_frame(x = 1:2, y = c(1L, 1L)))
(df2 <- data_frame(x = 1:2, y = 1:2))
```

The four possibilities are:

```{r}
intersect(df1, df2)
# Note that we get 3 rows, not 4
union(df1, df2)
setdiff(df1, df2)
setdiff(df2, df1)
```

### Databases

Each two-table verb has a straightforward SQL equivalent:

| R                | SQL
|------------------|--------
| `inner_join()`   | `SELECT * FROM x JOIN y ON x.a = y.a`
| `left_join()`    | `SELECT * FROM x LEFT JOIN y ON x.a = y.a`
| `right_join()`   | `SELECT * FROM x RIGHT JOIN y ON x.a = y.a`
| `full_join()`    | `SELECT * FROM x FULL JOIN y ON x.a = y.a`
| `semi_join()`    | `SELECT * FROM x WHERE EXISTS (SELECT 1 FROM y WHERE x.a = y.a)`
| `anti_join()`    | `SELECT * FROM x WHERE NOT EXISTS (SELECT 1 FROM y WHERE x.a = y.a)`
| `intersect(x, y)`| `SELECT * FROM x INTERSECT SELECT * FROM y`
| `union(x, y)`    | `SELECT * FROM x UNION SELECT * FROM y`
| `setdiff(x, y)`  | `SELECT * FROM x EXCEPT SELECT * FROM y`

`x` and `y` don't have to be tables in the same database. If you specify `copy = TRUE`, dplyr will copy the `y` table into the same location as the `x` variable. This is useful if you've downloaded a summarised dataset and determined a subset of interest that you now want the full data for. You can use `semi_join(x, y, copy = TRUE)` to upload the indices of interest to a temporary table in the same database as `x`, and then perform a efficient semi join in the database. 

If you're working with large data, it maybe also be helpful to set `auto_index = TRUE`. That will automatically add an index on the join variables to the temporary table.

### Coercion rules

When joining tables, dplyr is a little more conservative than base R about the types of variable that it considers equivalent. This is mostly likely to surprise if you're working factors:

  * Factors with different levels are coerced to character with a warning:
    
    ```{r}
    df1 <- data_frame(x = 1, y = factor("a"))
    df2 <- data_frame(x = 2, y = factor("b"))
    full_join(df1, df2) %>% str()
    ```

  * Factors with the same levels in a different order are coerced to character 
    with a warning:
  
    ```{r}
    df1 <- data_frame(x = 1, y = factor("a", levels = c("a", "b")))
    df2 <- data_frame(x = 2, y = factor("b", levels = c("b", "a")))
    full_join(df1, df2) %>% str()
    ```

  * Factors are preserved only if the levels match exactly:
    
    ```{r}
    df1 <- data_frame(x = 1, y = factor("a", levels = c("a", "b")))
    df2 <- data_frame(x = 2, y = factor("b", levels = c("a", "b")))
    full_join(df1, df2) %>% str()
    ```    

  * A factor and a character are coerced to character with a warning:
    
    ```{r}
    df1 <- data_frame(x = 1, y = "a")
    df2 <- data_frame(x = 2, y = factor("a"))
    full_join(df1, df2) %>% str()
    ```
    
Otherwise logicals will be silently upcast to integer, and integer to numeric, but coercing to character will raise an error:

```{r, error = TRUE, purl = FALSE}
df1 <- data_frame(x = 1, y = 1L)
df2 <- data_frame(x = 2, y = 1.5)
full_join(df1, df2) %>% str()

df1 <- data_frame(x = 1, y = 1L)
df2 <- data_frame(x = 2, y = "a")
full_join(df1, df2) %>% str()
```