From d6905100ba8b91879f98cdbd2a8f35497246784e Mon Sep 17 00:00:00 2001 From: hadley Date: Thu, 7 Jan 2016 08:33:03 -0600 Subject: [PATCH 1/2] Tweak figure sizing --- lists.Rmd | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/lists.Rmd b/lists.Rmd index 525988f..cfa0efa 100644 --- a/lists.Rmd +++ b/lists.Rmd @@ -80,7 +80,7 @@ x3 <- list(1, list(2, list(3))) I draw them as follows: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-structure.png") ``` @@ -129,7 +129,7 @@ a <- list(a = 1:3, b = "a string", c = pi, d = list(-1, -5)) Or visually: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-subsetting.png") ``` @@ -137,13 +137,13 @@ knitr::include_graphics("diagrams/lists-subsetting.png") It's easy to get confused between `[` and `[[`, but it's important to understand the difference. A few months ago I stayed at a hotel with a pretty interesting pepper shaker that I hope will help remember these differences: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "25%"} knitr::include_graphics("images/pepper.jpg") ``` If this pepper shaker is your list `x`, then, `x[1]` is a pepper shaker containing a single pepper packet: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "25%"} knitr::include_graphics("images/pepper-1.jpg") ``` @@ -151,13 +151,13 @@ knitr::include_graphics("images/pepper-1.jpg") `x[[1]]` is: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "25%"} knitr::include_graphics("images/pepper-2.jpg") ``` If you wanted to get the content of the pepper package, you'd need `x[[1]][[1]]`: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "25%"} knitr::include_graphics("images/pepper-3.jpg") ``` @@ -533,7 +533,7 @@ x %>% transpose() %>% str() Graphically, this looks like: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-transpose.png") ``` @@ -644,7 +644,7 @@ map2(mu, sigma, rnorm, n = 10) `map2()` generates this series of function calls: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-map2.png") ``` @@ -672,7 +672,7 @@ args1 %>% pmap(rnorm) %>% str() That looks like: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-pmap-unnamed.png") ``` @@ -685,7 +685,7 @@ args2 %>% pmap(rnorm) %>% str() That generates longer, but safer, calls: -```{r, echo = FALSE} +```{r, echo = FALSE, out.width = "75%"} knitr::include_graphics("diagrams/lists-pmap-named.png") ``` From 6982ec43eb9f63dce6c83cc5606602fc18ee34c4 Mon Sep 17 00:00:00 2001 From: hadley Date: Thu, 7 Jan 2016 10:20:29 -0600 Subject: [PATCH 2/2] Move two-table verbs out into new relational data chapter --- _includes/package-nav.html | 1 + diagrams/relational-nycflights.png | Bin 0 -> 46374 bytes diagrams/relational.graffle | Bin 0 -> 3207 bytes relational-data.Rmd | 401 +++++++++++++++++++++++++++++ transform.Rmd | 341 ------------------------ 5 files changed, 402 insertions(+), 341 deletions(-) create mode 100644 diagrams/relational-nycflights.png create mode 100644 diagrams/relational.graffle create mode 100644 relational-data.Rmd diff --git a/_includes/package-nav.html b/_includes/package-nav.html index b6f0236..e72508f 100644 --- a/_includes/package-nav.html +++ b/_includes/package-nav.html @@ -3,6 +3,7 @@
  • Data science essentials
  • Visualize
  • Transform
    • +
  • Relational data
  • Tidy
  • Model
  • Import
    • diff --git a/diagrams/relational-nycflights.png b/diagrams/relational-nycflights.png new file mode 100644 index 0000000000000000000000000000000000000000..a56a586d78043589d3647f86d5e758e07823ce1e GIT binary patch literal 46374 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ⅅ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∈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 literal 0 HcmV?d00001 diff --git a/diagrams/relational.graffle b/diagrams/relational.graffle new file mode 100644 index 0000000000000000000000000000000000000000..d9a3da08295777feb64d01b8d357bedb2b252aaf GIT binary patch literal 3207 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 literal 0 HcmV?d00001 diff --git a/relational-data.Rmd b/relational-data.Rmd new file mode 100644 index 0000000..ea10328 --- /dev/null +++ b/relational-data.Rmd @@ -0,0 +1,401 @@ +--- +layout: default +title: Relational data +--- + +# Relational data {#relation-data} + +```{r setup-transform, include = FALSE} +library(dplyr) +library(nycflights13) +library(ggplot2) +source("common.R") +options(dplyr.print_min = 6, dplyr.print_max = 6) +knitr::opts_chunk$set(fig.path = "figures/", cache = TRUE) +``` + +It's rare that a data analysis involves only a single table of data. You often have many tables that contribute to an analysis, and you need flexible tools to combine them. This type of data is called relational because it concerns the relations between multiple dataset. + +There are three families of verbs design to work with relational data: + +* Mutating joins, which add new variables to one data frame from matching rows + in another. + +* Filtering joins, which filter observations from one data frame based on + whether or not they match an observation in the other table. + +* Set operations, which treat observations like they were set elements. + +If you've used SQL before you're probably familiar with the mutating joins (these are the classic left join, right join, etc), but you might not know about the filtering joins (semi and anti joins) or the set operations. + +All two-table verbs work similarly. The first two arguments are the two data frames to combine, and the output is always a new data frame. If you don't specify the details of the join, dplyr will guess based on the common variables, and will print a message. If you want to suppress that message, supply more arguments. + +## nycflights13 {#nycflights13-relational} + +We're going to continue to work with the nycflights13 package. We start by selecting just some of the variables. This will make it easier to see what's going on when we join on other tables. Like mutating, joins tend to add on variables to the right-hand side, so you might not see them if you have a lot of variables. + +```{r} +# Drop unimportant variables so it's easier to understand the join results. +flights2 <- flights %>% select(year:day, hour, origin, dest, tailnum, carrier) +flights2 +``` + +There are four additional data frames that contain useful additional metadata about the `flights`: + +* `airlines` lets you look up the full carrier name from its abbreviated + code. + + ```{r} + airlines + ``` + +* `planes` gives information about each plane, identified by its `tailnum`. + + ```{r} + planes + ``` + +* `airports` gives information about each airport, identified by the `faa` + airport code. + + ```{r} + airports + ``` + +* `weather` gives the weather at each airport at each hour. + + ```{r} + weather + ``` + +We could illustrate this with a diagram: + +```{r, echo = FALSE, out.width = "75%"} +knitr::include_graphics("diagrams/relational-nycflights.png") +``` + +This diagram is a little overwhelming, but the key to understanding it is to reminder it's pairs of tables that are related. All join operations only ever work a pair of tables. Don't try and understand the whole thing, just use it as a reference when you want to understand how a pair of tables are related; you're unlikely to ever need to join together all of the tables simultaneously. + +The diagram shows how each pair of tables is connected. + +* `flights` connects to `planes` and `airlines` via single variable, `tailnum`, + and `carrier` respectively. + +* `flights` connects to `airports` in two ways: via the `origin` or the + `dest` variable. + +* `flights` connects to `weather` via `origin` (the location), and + `year`, `month`, `day` and `hour` (the time). + +The variables used to connect each pair of tables are called the __keys__. The __primary keys__ are the refer to the set of variables that uniquely identify an observation in a data frame. Each plane has a single variable that identifies it, it's tail number (`tailnum`). Weather is more complicated: it needs five variables to uniquely identify each observation: `year`, `month`, `day`, `hour`, and `origin`. Primary keys are coloured grey. + +Arrows define a __relation__ between a pair of tables. A relation connects the primary key from one table to a __foreign key__ (or keys) in another table. Relations are almost always 1-to-many. For example, each airport, plane, and airline has multiple correspond flights. In other data, you'll occassionaly see a 1-to-1 relationship. You can think of this as a special case of 1-to-many. + +It's possible to model many-to-many relations with a n-1 relation and a 1-n relation. Unfortunately, that's beyond the scope of this book. If you do encountered in practice, remember it can always be broken down into pairs. + +## Mutating joins {#mutating-joins} + +Mutating joins allow you to combine variables from multiple tables. For example, imagine you want to add the full airline name to the `flights` data. You can join the `airlines` and `carrier` data frames: + +```{r} + +flights2 %>% + inner_join(airlines) +``` + +The result of joining airlines on to flights is an additional variable: carrier. This is why I call this type of join a mutating join. + +There are three important things you need to understand about how joins work: + +* The different types of matches (1-to-1, 1-to-many, many-to-many). + +* What happens when a row doesn't match. + +* How you control what variables used to generate the match. + +These are described in the following sections using a visual abstraction and code. The following diagram shows a schematic of a data frame. The coloured column represents the "key" variable: these are used to match the rows between the tables. The labelled column represents the "value" columns that are carried along for the ride. + +```{r, echo = FALSE, out.width = "10%"} +knitr::include_graphics("diagrams/join-setup.png") +``` +```{r} +data_frame(key = 1:5, value = paste0("x", 1:5)) +``` + +## Matches {#join-matches} + +There are three ways that the keys might match: one-to-one, one-to-many, and many-to-many. + +* In a one-to-one match, each key in `x` matches one key in `y`. This sort of + match is useful when you two tables that have data about the same thing and + you want to align the rows. + + ```{r, echo = FALSE, out.width = "100%"} + knitr::include_graphics("diagrams/join-one-to-one.png") + ``` + + ```{r} + x <- data_frame(key = 1:5, val_x = paste0("x", 1:5)) + y <- data_frame(key = c(3, 5, 2, 4, 1), val_y = paste0("y", 1:5)) + inner_join(x, y, by = "key") + ``` + +* In a one-to-many match, each key in `x` matches multiple keys in `y`. This + is useful when you want to add in additional information. + + ```{r, echo = FALSE, out.width = "100%"} + knitr::include_graphics("diagrams/join-one-to-many.png") + ``` + + ```{r} + x <- data_frame(key = c(3, 3, 1, 4, 4), val_x = paste0("x", 1:5)) + y <- data_frame(key = 1:4, val_y = paste0("y", 1:4)) + inner_join(x, y, by = "key") + ``` + +* Finally, you can have a many-to-many match, where there are duplicated + keys in `x` and duplicate keys in `y`. When this happens, every possible + combination is created in the output. + + ```{r, echo = FALSE, out.width = "100%"} + knitr::include_graphics("diagrams/join-many-to-many.png") + ``` + ```{r} + x <- data_frame(key = c(1, 2, 2, 4), val_x = paste0("x", 1:4)) + y <- data_frame(key = c(1, 2, 2, 4), val_y = paste0("y", 1:4)) + inner_join(x, y, by = "key") + ``` + +### Missing matches {#join-types} + +You might also wonder what happens when there isn't a match. This is controlled by the type of "join": inner, left, right, or outer. I'll show each type of join with a picture, and the corresponding R code. Here are the tables we will use: + +```{r, echo = FALSE, out.width = "25%"} +knitr::include_graphics("diagrams/join-setup2.png") +``` +```{r} +(x <- data_frame(key = c(1, 2, 3), val_x = c("x1", "x2", "x3"))) +(y <- data_frame(key = c(1, 2, 4), val_y = c("y1", "y2", "y3"))) +``` + +* In an inner join, only rows that have matching keys are retained: + + ```{r, echo = FALSE, out.width = "50%"} + knitr::include_graphics("diagrams/join-inner.png") + ``` + + ```{r} + x %>% inner_join(y, by = "key") + ``` + +* In a left join, every row in `x` is kept. A left join effectively works + by adding a "default" match: if a row in `x` doesn't match a row in `y`, + it falls back to matching a row that contains only missing values. + + ```{r, echo = FALSE, out.width = "50%"} + knitr::include_graphics("diagrams/join-left.png") + ``` + ```{r} + x %>% left_join(y, by = "key") + ``` + + This is the most commonly used join because it ensures that you don't lose + observations from your primary table. + +* A right join is the complement of a left join: every row in `y` is kept. + + ```{r, echo = FALSE, out.width = "50%"} + knitr::include_graphics("diagrams/join-right.png") + ``` + ```{r} + x %>% right_join(y, by = "key") + ``` + +* A full join is combines a left join and a right join, keeping every + row in both `x` and `y`. + + ```{r, echo = FALSE, out.width = "50%"} + knitr::include_graphics("diagrams/join-full.png") + ``` + ```{r} + x %>% full_join(y, by = "key") + ``` + +The left, right and full joins are collectively known as __outer joins__. When a row doesn't match in an outer join, the new variables are filled in with missing values. You can also think about joins heuristically as set operations on the rows of the tables: + +```{r, echo = FALSE} +knitr::include_graphics("diagrams/join-venn.png") +``` + +-------------------------------------------------------------------------------- + +`base::merge()` can perform all four types of mutating join: + +dplyr | merge +-------------------|------------------------------------------- +`inner_join(x, y)` | `merge(x, y)` +`left_join(x, y)` | `merge(x, y, all.x = TRUE)` +`right_join(x, y)` | `merge(x, y, all.y = TRUE)`, +`full_join(x, y)` | `merge(x, y, all.x = TRUE), all.y = TRUE)` + +The advantages of the specific dplyr verbs is that they more clearly convey the intent of your code: the difference between the joins is really important but concealed in the arguments of `merge()`. dplyr's joins are considerably faster and don't mess with the order of the rows. + +-------------------------------------------------------------------------------- + +### Controlling how the tables are matched {#join-by} + +When joining multiple tables of data, it's useful to think about the "key", the combination of variables that uniquely identifies each observation. Sometimes that's a single variable. For example each airport is uniquely identified by a three letter `faa` code, each carrier is uniquely identified by its two letter abbreviation, and each plane by its `tailnum`. `weather` is more complex: to uniquely identify an observation you need to know when (`year`, `month`, `day`, `hour`) and where it happened (`origin`). + +When you combine two tables of data, you do so by matching the keys in each table. You can control the matching behaviour using the `by` argument: + + * The default, `by = NULL`, uses all variables that appear in both tables, + the so called __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"`. This is like a natural join, but uses only + some of the common variables. For example, `flights` and `planes` have + `year` variables, but they mean different things so we only want to join by + `tailnum`. + + ```{r} + flights2 %>% left_join(planes, by = "tailnum") + ``` + + Note that the `year` variables (which appear in both input data frames, + but are not constrained to be equal) are disambiguated in the output with + a suffix. + + * A named character vector: `by = c("a" = "b")`. This will + match variable `a` in table `x` to variable `y` in table `b`. The + variables from `x` will be used in the output. + + For example, if we want to draw a map we need to combine the flights data + with the airports data which contains the location (`lat` and `long`) of + each airport. 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")) + ``` + +### Exercises + +1. Compute the average delay by destination, then join on the `airports` + data frame so you can show the spatial distribution of delays. Here's an + easy way to draw a map of the United States: + + ```{r, include = FALSE} + airports %>% + semi_join(flights, c("faa" = "dest")) %>% + ggplot(aes(lon, lat)) + + borders("state") + + geom_point() + + coord_quickmap() + ``` + + You might want to use the `size` or `colour` of the points to display + the average delay for each airport. + +1. Is there a relationship between the age of a plane and its delays? + +1. What weather conditions make it more likely to see a delay? + +1. What happened on June 13 2013? Display the spatial pattern of delays, + and then use google to cross-reference with the weather. + + ```{r, eval = FALSE, include = FALSE} + worst <- filter(not_cancelled, month == 6, day == 13) + worst %>% + group_by(dest) %>% + summarise(delay = mean(arr_delay), n = n()) %>% + filter(n > 5) %>% + inner_join(airports, by = c("dest" = "faa")) %>% + ggplot(aes(lon, lat)) + + borders("state") + + geom_point(aes(size = n, colour = delay)) + + coord_quickmap() + ``` + +## Filtering joins {#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`. + +Semi joins are useful for matching filtered summary tables back to the original rows. For example, imagine you've found the top ten most popular destinations: + +```{r} +top_dest <- flights %>% + count(dest, sort = TRUE) %>% + head(10) +top_dest +``` + +Now you want to find each flight that went to one of those destinations. You could construct a filter yourself: + +```{r} +flights %>% filter(dest %in% top_dest$dest) +``` + +But it's difficult to extend that approach to multiple variables. For example, imagine that you'd found the 10 days with highest average delays. How would you construct the filter statement that used `year`, `month`, and `day` to match it back to `flights`? + +Instead you can use a semi join, which connects the two tables like a mutating join, but instead of adding new columns, only keeps the rows in `x` that have a match in `y`: + +```{r} +flights %>% semi_join(top_dest) +``` + +The inverse of a semi join is an anti join. An anti join keeps the rows that _don't_ have a match, and are useful for diagnosing join mismatches. For example, when connecting `flights` and `planes`, you might be interested to know that there are many `flights` that don't have a match in `planes`: + +```{r} +flights %>% + anti_join(planes, by = "tailnum") %>% + count(tailnum, sort = TRUE) +``` + +### Exercises + +1. What does it mean for a flight to have a missing `tailnum`? What do the + tail numbers that don't have a matching record in `planes` have in common? + (Hint: one variable explains ~90% of the problem.) + +1. Find the 48 hours (over the course of the whole year) that have the worst + delays. Cross-reference it with the `weather` data. Can you see any + patterns? + +1. What does `anti_join(flights, airports, by = c("dest" = "faa"))` tell you? + What does `anti_join(airports, flights, by = c("dest" = "faa"))` tell you? + +## Set operations {#set-operations} + +The final type of two-table verb is set operations. Generally, I use these the least frequnetly, but they are occassionally useful when you want to break a single complex filter into simpler pieces that you then combine. + +All these operations work with a complete row, comparing the values of every variable. 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) +``` diff --git a/transform.Rmd b/transform.Rmd index 44f239a..950c9f5 100644 --- a/transform.Rmd +++ b/transform.Rmd @@ -934,344 +934,3 @@ Functions that work most naturally in grouped mutates and filters are known as 1. Find all destinations that are flown by at least two carriers. Use that information to rank the carriers. - -## Multiple tables of data - -It's rare that a data analysis involves only a single table of data. You often have many tables that contribute to an analysis, and you need flexible tools to combine them. For example, the nycflights13 package has four additional data frames that contain useful additional metadata about `flights`: - -* `airlines` lets you look up the full carrier name from its abbreviated code. - -* `planes` gives information about each plane, identified by its `tailnum`. - -* `airports` gives information about each airport, identified by the `faa` - airport code. - -* `weather` gives the weather at each airport at each hour. - -There are three families of verbs that let you combine two data frames: - -* Mutating joins, which add new variables to one data frame from matching rows - in another. - -* Filtering joins, which filter observations from one data frame based on - whether or not they match an observation in the other table. - -* Set operations, which treat observations like they were set elements. - -If you've used SQL before you're probably familiar with the mutating joins (these are the classic left join, right join, etc), but you might not know about the filtering joins (semi and anti joins) or the set operations. - -All two-table verbs work similarly. The first two arguments are the two data frames to combine, and the output is always a new data frame. If you don't specify the details of the join, dplyr will guess based on the common variables, and will print a message. If you want to suppress that message, supply more arguments. - -### Mutating joins {#mutating-joins} - -Mutating joins allow you to combine variables from multiple tables. For example, imagine you want to add the full airline name to the `flights` data. You can join the `airlines` and `carrier` data frames: - -```{r} -# Drop unimportant variables so it's easier to understand the join results. -flights2 <- flights %>% select(year:day, hour, origin, dest, tailnum, carrier) - -flights2 -airlines - -flights2 %>% - inner_join(airlines) -``` - -The result of joining airlines on to flights is an additional variable: carrier. This is why I call this type of join a mutating join. - -There are three important things you need to understand about how joins work: - -* The different types of matches (1-to-1, 1-to-many, many-to-many). - -* What happens when a row doesn't match. - -* How you control what variables used to generate the match. - -These are described in the following sections using a visual abstraction and code. The following diagram shows a schematic of a data frame. The coloured column represents the "key" variable: these are used to match the rows between the tables. The labelled column represents the "value" columns that are carried along for the ride. - -```{r, echo = FALSE, out.width = "10%"} -knitr::include_graphics("diagrams/join-setup.png") -``` -```{r} -data_frame(key = 1:5, x = paste0("x", 1:5)) -``` - -### Matches {#join-matches} - -There are three ways that the keys might match: one-to-one, one-to-many, and many-to-many. - -* In a one-to-one match, each key in `x` matches one key in `y`. This sort of - match is useful when you two tables that have data about the same thing and - you want to align the rows. - - ```{r, echo = FALSE, out.width = "100%"} - knitr::include_graphics("diagrams/join-one-to-one.png") - ``` - - ```{r} - x <- data_frame(key = 1:5, x = paste0("x", 1:5)) - y <- data_frame(key = c(3, 5, 2, 4, 1), y = paste0("y", 1:5)) - inner_join(x, y, by = "key") - ``` - -* In a one-to-many match, each key in `x` matches multiple keys in `y`. This - is useful when you want to add in additional information. - - ```{r, echo = FALSE, out.width = "100%"} - knitr::include_graphics("diagrams/join-one-to-many.png") - ``` - - ```{r} - x <- data_frame(key = c(3, 3, 1, 4, 4), x = paste0("x", 1:5)) - y <- data_frame(key = 1:4, y = paste0("y", 1:4)) - inner_join(x, y, by = "key") - ``` - -* Finally, you can have a many-to-many match, where there are duplicated - keys in `x` and duplicate keys in `y`. When this happens, every possible - combination is created in the output. - - ```{r, echo = FALSE, out.width = "100%"} - knitr::include_graphics("diagrams/join-many-to-many.png") - ``` - ```{r} - x <- data_frame(key = c(1, 2, 2, 4), x = paste0("x", 1:4)) - y <- data_frame(key = c(1, 2, 2, 4), y = paste0("y", 1:4)) - inner_join(x, y, by = "key") - ``` - -#### Missing matches {#join-types} - -You might also wonder what happens when there isn't a match. This is controlled by the type of "join": inner, left, right, or outer. I'll show each type of join with a picture, and the corresponding R code. Here are the tables we will use: - -```{r, echo = FALSE, out.width = "25%"} -knitr::include_graphics("diagrams/join-setup2.png") -``` -```{r} -(x <- data_frame(key = c(1, 2, 3), x = c("x1", "x2", "x3"))) -(y <- data_frame(key = c(1, 2, 4), y = c("y1", "y2", "y3"))) -``` - -* In an inner join, only rows that have matching keys are retained: - - ```{r, echo = FALSE, out.width = "50%"} - knitr::include_graphics("diagrams/join-inner.png") - ``` - - ```{r} - x %>% inner_join(y, by = "key") - ``` - -* In a left join, every row in `x` is kept. A left join effectively works - by adding a "default" match: if a row in `x` doesn't match a row in `y`, - it falls back to matching a row that contains only missing values. - - ```{r, echo = FALSE, out.width = "50%"} - knitr::include_graphics("diagrams/join-left.png") - ``` - ```{r} - x %>% left_join(y, by = "key") - ``` - - This is the most commonly used join because it ensures that you don't lose - observations from your primary table. - -* A right join is the complement of a left join: every row in `y` is kept. - - ```{r, echo = FALSE, out.width = "50%"} - knitr::include_graphics("diagrams/join-right.png") - ``` - ```{r} - x %>% right_join(y, by = "key") - ``` - -* A full join is combines a left join and a right join, keeping every - row in both `x` and `y`. - - ```{r, echo = FALSE, out.width = "50%"} - knitr::include_graphics("diagrams/join-full.png") - ``` - ```{r} - x %>% full_join(y, by = "key") - ``` - -The left, right and full joins are collectively known as __outer joins__. When a row doesn't match in an outer join, the new variables are filled in with missing values. You can also think about joins heuristically as set operations on the rows of the tables: - -```{r, echo = FALSE} -knitr::include_graphics("diagrams/join-venn.png") -``` - --------------------------------------------------------------------------------- - -`base::merge()` can mimic all four types of mutating join. The advantages of the specific dplyr verbs is that they more clearly convey the intent of your code (the difference between the joins is really important but concealed in the arguments of `merge()`), and are considerably faster. dplyr's joins also don't mess with the order of the rows. - --------------------------------------------------------------------------------- - -#### Controlling how the tables are matched {#join-by} - -When joining multiple tables of data, it's useful to think about the "key", the combination of variables that uniquely identifies each observation. Sometimes that's a single variable. For example each airport is uniquely identified by a three letter `faa` code, each carrier is uniquely identified by its two letter abbreviation, and each plane by its `tailnum`. `weather` is more complex: to uniquely identify an observation you need to know when (`year`, `month`, `day`, `hour`) and where it happened (`origin`). - -When you combine two tables of data, you do so by matching the keys in each table. You can control the matching behaviour using the `by` argument: - - * The default, `by = NULL`, uses all variables that appear in both tables, - the so called __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"`. This is like a natural join, but uses only - some of the common variables. For example, `flights` and `planes` have - `year` variables, but they mean different things so we only want to join by - `tailnum`. - - ```{r} - flights2 %>% left_join(planes, by = "tailnum") - ``` - - Note that the `year` variables (which appear in both input data frames, - but are not constrained to be equal) are disambiguated in the output with - a suffix. - - * A named character vector: `by = c("a" = "b")`. This will - match variable `a` in table `x` to variable `y` in table `b`. The - variables from `x` will be used in the output. - - For example, if we want to draw a map we need to combine the flights data - with the airports data which contains the location (`lat` and `long`) of - each airport. 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")) - ``` - -#### New observations - -The mutating joins are primarily used to add new variables, but 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) -``` - -#### Exercises - -1. Compute the average delay by destination, then join on the `airports` - data frame so you can show the spatial distribution of delays. Here's an - easy way to draw a map of the United States: - - ```{r, include = FALSE} - airports %>% - semi_join(flights, c("faa" = "dest")) %>% - ggplot(aes(lon, lat)) + - borders("state") + - geom_point() + - coord_quickmap() - ``` - - You might want to use the `size` or `colour` of the points to display - the average delay for each airport. - -1. Is there a relationship between the age of a plane and its delays? - -1. What weather conditions make it more likely to see a delay? - -1. What happened on June 13 2013? Display the spatial pattern of delays, - and then use google to cross-reference with the weather. - - ```{r, eval = FALSE, include = FALSE} - worst <- filter(not_cancelled, month == 6, day == 13) - worst %>% - group_by(dest) %>% - summarise(delay = mean(arr_delay), n = n()) %>% - filter(n > 5) %>% - inner_join(airports, by = c("dest" = "faa")) %>% - ggplot(aes(lon, lat)) + - borders("state") + - geom_point(aes(size = n, colour = delay)) + - coord_quickmap() - ``` - -### 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`. - -Semi joins are useful for matching filtered summary tables back to the original rows. For example, imagine you've found the top ten most popular destinations: - -```{r} -top_dest <- flights %>% - count(dest, sort = TRUE) %>% - head(10) -top_dest -``` - -Now you want to find each flight that went to one of those destinations. You could construct a filter yourself: - -```{r} -flights %>% filter(dest %in% top_dest$dest) -``` - -But it's difficult to extend that approach to multiple variables. For example, imagine that you'd found the 10 days with highest average delays. How would you construct the filter statement that used `year`, `month`, and `day` to match it back to `flights`? - -Instead you can use a semi join, which connects the two tables like a mutating join, but instead of adding new columns, only keeps the rows in `x` that have a match in `y`: - -```{r} -flights %>% semi_join(top_dest) -``` - -The inverse of a semi join is an anti join. An anti join keeps the rows that _don't_ have a match, and are useful for diagnosing join mismatches. For example, when connecting `flights` and `planes`, you might be interested to know that there are many `flights` that don't have a match in `planes`: - -```{r} -flights %>% - anti_join(planes, by = "tailnum") %>% - count(tailnum, sort = TRUE) -``` - -#### Exercises - -1. What does it mean for a flight to have a missing `tailnum`? What do the - tail numbers that don't have a matching record in `planes` have in common? - (Hint: one variable explains ~90% of the problem.) - -1. Find the 48 hours (over the course of the whole year) that have the worst - delays. Cross-reference it with the `weather` data. Can you see any - patterns? - -1. What does `anti_join(flights, airports, by = c("dest" = "faa"))` tell you? - What does `anti_join(airports, flights, by = c("dest" = "faa"))` tell you? - -### Set operations - -The final type of two-table verb is set operations. Generally, I use these the least frequnetly, but they are occassionally useful when you want to break a single complex filter into simpler pieces that you then combine. - -All these operations work with a complete row, comparing the values of every variable. 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) -```