Prerequisites

In this chapter, we’ll explore the five related datasets from nycflights13 using the join functions from dplyr.

library(tidyverse)
library(nycflights13)

Primary and foreign keys

Every join involves a pair of keys: a primary key and a foreign key. A primary key is a variable or set of variables that uniquely identifies each observation. When more than one variable is needed, the key is called a compound key. For example, in nycfights13:

• airlines records two pieces of data about each airline: its carrier code and its full name. You can identify an airline with its two letter carrier code, making carrier the primary key.

  airlines
  #> # A tibble: 16 × 2
  #>   carrier name                    
  #>   <chr>   <chr>                   
  #> 1 9E      Endeavor Air Inc.       
  #> 2 AA      American Airlines Inc.  
  #> 3 AS      Alaska Airlines Inc.    
  #> 4 B6      JetBlue Airways         
  #> 5 DL      Delta Air Lines Inc.    
  #> 6 EV      ExpressJet Airlines Inc.
  #> # … with 10 more rows

• airports records data about each airport. You can identify each airport by its three letter airport code, making faa the primary key.

  airports
  #> # A tibble: 1,458 × 8
  #>   faa   name                             lat   lon   alt    tz dst   tzone   
  #>   <chr> <chr>                          <dbl> <dbl> <dbl> <dbl> <chr> <chr>   
  #> 1 04G   Lansdowne Airport               41.1 -80.6  1044    -5 A     America…
  #> 2 06A   Moton Field Municipal Airport   32.5 -85.7   264    -6 A     America…
  #> 3 06C   Schaumburg Regional             42.0 -88.1   801    -6 A     America…
  #> 4 06N   Randall Airport                 41.4 -74.4   523    -5 A     America…
  #> 5 09J   Jekyll Island Airport           31.1 -81.4    11    -5 A     America…
  #> 6 0A9   Elizabethton Municipal Airport  36.4 -82.2  1593    -5 A     America…
  #> # … with 1,452 more rows

• planes records data about each plane. You can identify a plane by its tail number, making tailnum the primary key.

  planes
  #> # A tibble: 3,322 × 9
  #>   tailnum  year type            manufacturer model engines seats speed engine
  #>   <chr>   <int> <chr>           <chr>        <chr>   <int> <int> <int> <chr> 
  #> 1 N10156   2004 Fixed wing mul… EMBRAER      EMB-…       2    55    NA Turbo…
  #> 2 N102UW   1998 Fixed wing mul… AIRBUS INDU… A320…       2   182    NA Turbo…
  #> 3 N103US   1999 Fixed wing mul… AIRBUS INDU… A320…       2   182    NA Turbo…
  #> 4 N104UW   1999 Fixed wing mul… AIRBUS INDU… A320…       2   182    NA Turbo…
  #> 5 N10575   2002 Fixed wing mul… EMBRAER      EMB-…       2    55    NA Turbo…
  #> 6 N105UW   1999 Fixed wing mul… AIRBUS INDU… A320…       2   182    NA Turbo…
  #> # … with 3,316 more rows

• weather records data about the weather at the origin airports. You can identify each observation by the combination of location and time, making origin and time_hour the compound primary key.

  weather
  #> # A tibble: 26,115 × 15
  #>   origin  year month   day  hour  temp  dewp humid wind_dir wind_speed
  #>   <chr>  <int> <int> <int> <int> <dbl> <dbl> <dbl>    <dbl>      <dbl>
  #> 1 EWR     2013     1     1     1  39.0  26.1  59.4      270      10.4 
  #> 2 EWR     2013     1     1     2  39.0  27.0  61.6      250       8.06
  #> 3 EWR     2013     1     1     3  39.0  28.0  64.4      240      11.5 
  #> 4 EWR     2013     1     1     4  39.9  28.0  62.2      250      12.7 
  #> 5 EWR     2013     1     1     5  39.0  28.0  64.4      260      12.7 
  #> 6 EWR     2013     1     1     6  37.9  28.0  67.2      240      11.5 
  #> # … with 26,109 more rows, and 5 more variables: wind_gust <dbl>,
  #> #   precip <dbl>, pressure <dbl>, visib <dbl>, time_hour <dttm>

A foreign key is a variable (or set of variables) that corresponds to a primary key in another table. For example:

• flights$tailnum is a foreign key that corresponds to the primary key planes$tailnum.
• flights$carrier is a foreign key that corresponds to the primary key airlines$carrier.
• flights$origin is a foreign key that corresponds to the primary key airports$faa.
• flights$dest is a foreign key that corresponds to the primary key airports$faa.
• flights$origin-flights$time_hour is a compound foreign key that corresponds to the compound primary key weather$origin-weather$time_hour.

These relationships are summarized visually in #fig-flights-relationships.

You’ll notice a nice feature in the design of these keys: the primary and foreign keys almost always have the same names, which, as you’ll see shortly, will make your joining life much easier. It’s also worth noting the opposite relationship: almost every variable name used in multiple tables has the same meaning in each place. There’s only one exception: year means year of departure in flights and year of manufacturer in planes. This will become important when we start actually joining tables together.

Checking primary keys

Now that that we’ve identified the primary keys in each table, it’s good practice to verify that they do indeed uniquely identify each observation. One way to do that is to count() the primary keys and look for entries where n is greater than one. This reveals that planes and weather both look good:

planes |> 
  count(tailnum) |> 
  filter(n > 1)
#> # A tibble: 0 × 2
#> # … with 2 variables: tailnum <chr>, n <int>

weather |> 
  count(time_hour, origin) |> 
  filter(n > 1)
#> # A tibble: 0 × 3
#> # … with 3 variables: time_hour <dttm>, origin <chr>, n <int>

You should also check for missing values in your primary keys — if a value is missing then it can’t identify an observation!

planes |> 
  filter(is.na(tailnum))
#> # A tibble: 0 × 9
#> # … with 9 variables: tailnum <chr>, year <int>, type <chr>,
#> #   manufacturer <chr>, model <chr>, engines <int>, seats <int>,
#> #   speed <int>, engine <chr>

weather |> 
  filter(is.na(time_hour) | is.na(origin))
#> # A tibble: 0 × 15
#> # … with 15 variables: origin <chr>, year <int>, month <int>, day <int>,
#> #   hour <int>, temp <dbl>, dewp <dbl>, humid <dbl>, wind_dir <dbl>,
#> #   wind_speed <dbl>, wind_gust <dbl>, precip <dbl>, pressure <dbl>,
#> #   visib <dbl>, time_hour <dttm>

Surrogate keys

So far we haven’t talked about the primary key for flights. It’s not super important here, because there are no data frames that use it as a foreign key, but it’s still useful to consider because it’s easier to work with observations if have some way to describe them to others.

After a little thinking and experimentation, we determined that there are three variables that together uniquely identify each flight:

flights |> 
  count(time_hour, carrier, flight) |> 
  filter(n > 1)
#> # A tibble: 0 × 4
#> # … with 4 variables: time_hour <dttm>, carrier <chr>, flight <int>, n <int>

Does the absence of duplicates automatically make time_hour-carrier-flight a primary key? It’s certainly a good start, but it doesn’t guarantee it. For example, are altitude and latitude a good primary key for airports?

airports |>
  count(alt, lat) |> 
  filter(n > 1)
#> # A tibble: 1 × 3
#>     alt   lat     n
#>   <dbl> <dbl> <int>
#> 1    13  40.6     2

Identifying an airport by it’s altitude and latitude is clearly a bad idea, and in general it’s not possible to know from the data alone whether or not a combination of variables makes a good a primary key. But for flights, the combination of time_hour, carrier, and flight seems reasonable because it would be really confusing for an airline and its customers if there were multiple flights with the same flight number in the air at the same time.

That said, we might be better off introducing a simple numeric surrogate key using the row number:

flights2 <- flights |> 
  mutate(id = row_number(), .before = 1)
flights2
#> # A tibble: 336,776 × 20
#>      id  year month   day dep_time sched_dep_time dep_delay arr_time
#>   <int> <int> <int> <int>    <int>          <int>     <dbl>    <int>
#> 1     1  2013     1     1      517            515         2      830
#> 2     2  2013     1     1      533            529         4      850
#> 3     3  2013     1     1      542            540         2      923
#> 4     4  2013     1     1      544            545        -1     1004
#> 5     5  2013     1     1      554            600        -6      812
#> 6     6  2013     1     1      554            558        -4      740
#> # … with 336,770 more rows, and 12 more variables: sched_arr_time <int>,
#> #   arr_delay <dbl>, carrier <chr>, flight <int>, tailnum <chr>,
#> #   origin <chr>, dest <chr>, air_time <dbl>, distance <dbl>, hour <dbl>,
#> #   minute <dbl>, time_hour <dttm>

Surrogate keys can be particular useful when communicating to other humans: it’s much easier to tell someone to take a look at flight 2001 than to say look at UA430 which departed 9am 2013-01-03.

Exercises

1. We forgot to draw the relationship between weather and airports in #fig-flights-relationships. What is the relationship and how should it appear in the diagram?

2. weather only contains information for the three origin airports in NYC. If it contained weather records for all airports in the USA, what additional connection would it make to flights?

3. The year, month, day, hour, and origin variables almost form a compound key for weather, but there’s one hour that has duplicate observations. Can you figure out what’s special about that hour?

4. We know that some days of the year are special and fewer people than usual fly on them (e.g. Christmas eve and Christmas day). How might you represent that data as a data frame? What would be the primary key? How would it connect to the existing data frames?

5. Draw a diagram illustrating the connections between the Batting, People, and Salaries data frames in the Lahman package. Draw another diagram that shows the relationship between People, Managers, AwardsManagers. How would you characterise the relationship between the Batting, Pitching, and Fielding data frames?

Mutating joins

A mutating join allows you to combine variables from two data frames: it first matches observations by their keys, then copies across variables from one data frame to the other. Like mutate(), the join functions add variables to the right, so if your dataset has many variables, you won’t see the new ones. For these examples, we’ll make it easier to see what’s going on by creating a narrower dataset with just six variablesRemember that in RStudio you can also use View() to avoid this problem.:

flights2 <- flights |> 
  select(year, time_hour, origin, dest, tailnum, carrier)
flights2
#> # A tibble: 336,776 × 6
#>    year time_hour           origin dest  tailnum carrier
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>  
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA     
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA     
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA     
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6     
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL     
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA     
#> # … with 336,770 more rows

There are four types of mutating join, but there’s one that you’ll use almost all of the time: left_join(). It’s special because the output will always have the same rows as xThat’s not 100% true, but you’ll get a warning whenever it isn’t.. The primary use of left_join() is to add in additional metadata. For example, we can use left_join() to add the full airline name to the flights2 data:

flights2 |>
  left_join(airlines)
#> Joining with `by = join_by(carrier)`
#> # A tibble: 336,776 × 7
#>    year time_hour           origin dest  tailnum carrier name                
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr>               
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA      United Air Lines In…
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA      United Air Lines In…
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA      American Airlines I…
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6      JetBlue Airways     
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL      Delta Air Lines Inc.
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA      United Air Lines In…
#> # … with 336,770 more rows

Or we could find out the temperature and wind speed when each plane departed:

flights2 |> 
  left_join(weather |> select(origin, time_hour, temp, wind_speed))
#> Joining with `by = join_by(time_hour, origin)`
#> # A tibble: 336,776 × 8
#>    year time_hour           origin dest  tailnum carrier  temp wind_speed
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <dbl>      <dbl>
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA       39.0       12.7
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA       39.9       15.0
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA       39.0       15.0
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6       39.0       15.0
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL       39.9       16.1
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA       39.0       12.7
#> # … with 336,770 more rows

Or what size of plane was flying:

flights2 |> 
  left_join(planes |> select(tailnum, type, engines, seats))
#> Joining with `by = join_by(tailnum)`
#> # A tibble: 336,776 × 9
#>    year time_hour           origin dest  tailnum carrier type   engines seats
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr>    <int> <int>
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA      Fixed…       2   149
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA      Fixed…       2   149
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA      Fixed…       2   178
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6      Fixed…       2   200
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL      Fixed…       2   178
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA      Fixed…       2   191
#> # … with 336,770 more rows

When left_join() fails to find a match for a row in x, it fills in the new variables with missing values. For example, there’s no information about the plane with tail number N3ALAA so the type, engines, and seats will be missing:

flights2 |> 
  filter(tailnum == "N3ALAA") |> 
  left_join(planes |> select(tailnum, type, engines, seats))
#> Joining with `by = join_by(tailnum)`
#> # A tibble: 63 × 9
#>    year time_hour           origin dest  tailnum carrier type  engines seats
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr>   <int> <int>
#> 1  2013 2013-01-01 06:00:00 LGA    ORD   N3ALAA  AA      <NA>       NA    NA
#> 2  2013 2013-01-02 18:00:00 LGA    ORD   N3ALAA  AA      <NA>       NA    NA
#> 3  2013 2013-01-03 06:00:00 LGA    ORD   N3ALAA  AA      <NA>       NA    NA
#> 4  2013 2013-01-07 19:00:00 LGA    ORD   N3ALAA  AA      <NA>       NA    NA
#> 5  2013 2013-01-08 17:00:00 JFK    ORD   N3ALAA  AA      <NA>       NA    NA
#> 6  2013 2013-01-16 06:00:00 LGA    ORD   N3ALAA  AA      <NA>       NA    NA
#> # … with 57 more rows

We’ll come back to this problem a few times in the rest of the chapter.

Specifying join keys

By default, left_join() will use all variables that appear in both data frames as the join key, the so called natural join. This is a useful heuristic, but it doesn’t always work. For example, what happens if we try to join flights2 with the complete planes dataset?

flights2 |> 
  left_join(planes)
#> Joining with `by = join_by(year, tailnum)`
#> # A tibble: 336,776 × 13
#>    year time_hour           origin dest  tailnum carrier type  manufacturer
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr> <chr>       
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA      <NA>  <NA>        
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA      <NA>  <NA>        
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA      <NA>  <NA>        
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6      <NA>  <NA>        
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL      <NA>  <NA>        
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA      <NA>  <NA>        
#> # … with 336,770 more rows, and 5 more variables: model <chr>,
#> #   engines <int>, seats <int>, speed <int>, engine <chr>

We get a lot of missing matches because our join is trying to use tailnum and year as a compound key. Both flights and planes have a year column but they mean different things: flights$year is year the flight occurred and planes$year is the year the plane was built. We only want to join on tailnum so we need to provide an explicit specification with join_by():

flights2 |> 
  left_join(planes, join_by(tailnum))
#> # A tibble: 336,776 × 14
#>   year.x time_hour           origin dest  tailnum carrier year.y type        
#>    <int> <dttm>              <chr>  <chr> <chr>   <chr>    <int> <chr>       
#> 1   2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA        1999 Fixed wing …
#> 2   2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA        1998 Fixed wing …
#> 3   2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA        1990 Fixed wing …
#> 4   2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6        2012 Fixed wing …
#> 5   2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL        1991 Fixed wing …
#> 6   2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA        2012 Fixed wing …
#> # … with 336,770 more rows, and 6 more variables: manufacturer <chr>,
#> #   model <chr>, engines <int>, seats <int>, speed <int>, engine <chr>

Note that the year variables are disambiguated in the output with a suffix (year.x and year.y), which tells you whether the variable came from the x or y argument. You can override the default suffixes with the suffix argument.

join_by(tailnum) is short for join_by(tailnum == tailnum). It’s important to know about this fuller form for two reasons. Firstly, it describes the relationship between the two tables: the keys must be equal. That’s why this type of join is often called an equi-join. You’ll learn about non-equi-joins in #sec-non-equi-joins.

Secondly, it’s how you specify different join keys in each table. For example, there are two ways to join the flight2 and airports table: either by dest or origin:

flights2 |> 
  left_join(airports, join_by(dest == faa))
#> # A tibble: 336,776 × 13
#>    year time_hour           origin dest  tailnum carrier name       lat   lon
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr>    <dbl> <dbl>
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA      George …  30.0 -95.3
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA      George …  30.0 -95.3
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA      Miami I…  25.8 -80.3
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6      <NA>      NA    NA  
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL      Hartsfi…  33.6 -84.4
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA      Chicago…  42.0 -87.9
#> # … with 336,770 more rows, and 4 more variables: alt <dbl>, tz <dbl>,
#> #   dst <chr>, tzone <chr>

flights2 |> 
  left_join(airports, join_by(origin == faa))
#> # A tibble: 336,776 × 13
#>    year time_hour           origin dest  tailnum carrier name       lat   lon
#>   <int> <dttm>              <chr>  <chr> <chr>   <chr>   <chr>    <dbl> <dbl>
#> 1  2013 2013-01-01 05:00:00 EWR    IAH   N14228  UA      Newark …  40.7 -74.2
#> 2  2013 2013-01-01 05:00:00 LGA    IAH   N24211  UA      La Guar…  40.8 -73.9
#> 3  2013 2013-01-01 05:00:00 JFK    MIA   N619AA  AA      John F …  40.6 -73.8
#> 4  2013 2013-01-01 05:00:00 JFK    BQN   N804JB  B6      John F …  40.6 -73.8
#> 5  2013 2013-01-01 06:00:00 LGA    ATL   N668DN  DL      La Guar…  40.8 -73.9
#> 6  2013 2013-01-01 05:00:00 EWR    ORD   N39463  UA      Newark …  40.7 -74.2
#> # … with 336,770 more rows, and 4 more variables: alt <dbl>, tz <dbl>,
#> #   dst <chr>, tzone <chr>

In older code you might see a different way of specifying the join keys, using a character vector:

• by = "x" corresponds to join_by(x).
• by = c("a" = "x") corresponds to join_by(a == x).

Now that it exists, we prefer join_by() since it provides a clearer and more flexible specification.

Filtering joins

As you might guess the primary action of a filtering join is to filter the rows. There are two types: semi-joins and anti-joins. Semi-joins keep all rows in x that have a match in y. For example, we could use a semi-join to filter the airports dataset to show just the origin airports:

airports |> 
  semi_join(flights2, join_by(faa == origin))
#> # A tibble: 3 × 8
#>   faa   name                  lat   lon   alt    tz dst   tzone           
#>   <chr> <chr>               <dbl> <dbl> <dbl> <dbl> <chr> <chr>           
#> 1 EWR   Newark Liberty Intl  40.7 -74.2    18    -5 A     America/New_York
#> 2 JFK   John F Kennedy Intl  40.6 -73.8    13    -5 A     America/New_York
#> 3 LGA   La Guardia           40.8 -73.9    22    -5 A     America/New_York

Or just the destinations:

airports |> 
  semi_join(flights2, join_by(faa == dest))
#> # A tibble: 101 × 8
#>   faa   name                               lat    lon   alt    tz dst   tzone
#>   <chr> <chr>                            <dbl>  <dbl> <dbl> <dbl> <chr> <chr>
#> 1 ABQ   Albuquerque International Sunpo…  35.0 -107.   5355    -7 A     Amer…
#> 2 ACK   Nantucket Mem                     41.3  -70.1    48    -5 A     Amer…
#> 3 ALB   Albany Intl                       42.7  -73.8   285    -5 A     Amer…
#> 4 ANC   Ted Stevens Anchorage Intl        61.2 -150.    152    -9 A     Amer…
#> 5 ATL   Hartsfield Jackson Atlanta Intl   33.6  -84.4  1026    -5 A     Amer…
#> 6 AUS   Austin Bergstrom Intl             30.2  -97.7   542    -6 A     Amer…
#> # … with 95 more rows

Anti-joins are the opposite: they return all rows in x that don’t have a match in y. They’re useful for finding missing values that are implicit in the data, the topic of #sec-missing-implicit. Implicitly missing values don’t show up as NAs but instead only exist as an absence. For example, we can find rows that as missing from airports by looking for flights that don’t have a matching destination airport:

flights2 |> 
  anti_join(airports, join_by(dest == faa)) |> 
  distinct(dest)
#> # A tibble: 4 × 1
#>   dest 
#>   <chr>
#> 1 BQN  
#> 2 SJU  
#> 3 STT  
#> 4 PSE

Or we can find which tailnums are missing from planes:

flights2 |>
  anti_join(planes, join_by(tailnum)) |> 
  distinct(tailnum)
#> # A tibble: 722 × 1
#>   tailnum
#>   <chr>  
#> 1 N3ALAA 
#> 2 N3DUAA 
#> 3 N542MQ 
#> 4 N730MQ 
#> 5 N9EAMQ 
#> 6 N532UA 
#> # … with 716 more rows

Exercises

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?

2. Imagine you’ve found the top 10 most popular destinations using this code:

   top_dest <- flights2 |>
     count(dest, sort = TRUE) |>
     head(10)

   How can you find all flights to those destinations?

3. Does every departing flight have corresponding weather data for that hour?

4. What do the tail numbers that don’t have a matching record in planes have in common? (Hint: one variable explains ~90% of the problems.)

5. Add a column to planes that lists every carrier that has flown that plane. You might expect that there’s an implicit relationship between plane and airline, because each plane is flown by a single airline. Confirm or reject this hypothesis using the tools you’ve learned in previous chapters.

6. Add the latitude and the longitude of the origin and destination airport to flights. Is it easier to rename the columns before or after the join?

7. 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:

   airports |>
     semi_join(flights, join_by(faa == dest)) |>
     ggplot(aes(x = lon, y = lat)) +
       borders("state") +
       geom_point() +
       coord_quickmap()

   You might want to use the size or color of the points to display the average delay for each airport.

8. What happened on June 13 2013? Draw a map of the delays, and then use Google to cross-reference with the weather.

Row matching

So far we’ve explored what happens if a row in x matches zero or one rows in y. What happens if it matches more than one row? To understand what’s going let’s first narrow our focus to the inner_join() and then draw a picture, #fig-join-match-types.

There are three possible outcomes for a row in x:

• If it doesn’t match anything, it’s dropped.
• If it matches 1 row in y, it’s preserved.
• If it matches more than 1 row in y, it’s duplicated once for each match.

In principle, this means that there’s no guaranteed correspondence between the rows in the output and the rows in the x:

• There might be fewer rows if some rows in x don’t match any rows in y.
• There might be more rows if some rows in x match multiple rows in y.
• There might be the same number of rows if every row in x matches one row in y.
• There might be the same number of rows if some rows don’t match any rows, and exactly the same number of rows match two rows in y!!

Row expansion is a fundamental property of joins, but it’s dangerous because it might happen without you realizing it. To avoid this problem, dplyr will warn whenever there are multiple matches:

df1 <- tibble(key = c(1, 2, 3), val_x = c("x1", "x2", "x3"))
df2 <- tibble(key = c(1, 2, 2), val_y = c("y1", "y2", "y3"))

df1 |> 
  inner_join(df2, join_by(key))
#> Warning in inner_join(df1, df2, join_by(key)): Each row in `x` is expected to match at most 1 row in `y`.
#> ℹ Row 2 of `x` matches multiple rows.
#> ℹ If multiple matches are expected, set `multiple = "all"` to silence this
#>   warning.
#> # A tibble: 3 × 3
#>     key val_x val_y
#>   <dbl> <chr> <chr>
#> 1     1 x1    y1   
#> 2     2 x2    y2   
#> 3     2 x2    y3

This is one reason we like left_join() — if it runs without warning, you know that each row of the output matches the row in the same position in x.

You can gain further control over row matching with two arguments:

• unmatched controls what happens when a row in x fails to match any rows in y. It defaults to "drop" which will silently drop any unmatched rows.
• multiple controls what happens when a row in x matches more than one row in y. For equi-joins, it defaults to "warn" which emits a warning message if any rows have multiple matches.

There are two common cases in which you might want to override these defaults: enforcing a one-to-one mapping or deliberately allowing the rows to increase.

One-to-one mapping

Both unmatched and multiple can take value "error" which means that the join will fail unless each row in x matches exactly one row in y:

df1 <- tibble(x = 1)
df2 <- tibble(x = c(1, 1))
df3 <- tibble(x = 3)

df1 |> 
  inner_join(df2, join_by(x), unmatched = "error", multiple = "error")
#> Error in `inner_join()`:
#> ! Each row in `x` must match at most 1 row in `y`.
#> ℹ Row 1 of `x` matches multiple rows.
df1 |> 
  inner_join(df3, join_by(x), unmatched = "error", multiple = "error")
#> Error in `inner_join()`:
#> ! Each row of `x` must have a match in `y`.
#> ℹ Row 1 of `x` does not have a match.

Note that unmatched = "error" is not useful with left_join() because, as described above, every row in x has a fallback match to a virtual row in y.

Allow multiple rows

Sometimes it’s useful to deliberately expand the number of rows in the output. This can come about naturally if you “flip” the direction of the question you’re asking. For example, as we’ve seen above, it’s natural to supplement the flights data with information about the plane that flew each flight:

flights2 |> 
  left_join(planes, by = "tailnum")

But it’s also reasonable to ask what flights did each plane fly:

plane_flights <- planes |> 
  select(tailnum, type, engines, seats) |> 
  left_join(flights2, by = "tailnum")
#> Warning in left_join(select(planes, tailnum, type, engines, seats), flights2, : Each row in `x` is expected to match at most 1 row in `y`.
#> ℹ Row 1 of `x` matches multiple rows.
#> ℹ If multiple matches are expected, set `multiple = "all"` to silence this
#>   warning.

Since this duplicates rows in x (the planes), we need to explicitly say that we’re ok with the multiple matches by setting multiple = "all":

plane_flights <- planes |> 
  select(tailnum, type, engines, seats) |> 
  left_join(flights2, by = "tailnum", multiple = "all")

plane_flights
#> # A tibble: 284,170 × 9
#>   tailnum type   engines seats  year time_hour           origin dest  carrier
#>   <chr>   <chr>    <int> <int> <int> <dttm>              <chr>  <chr> <chr>  
#> 1 N10156  Fixed…       2    55  2013 2013-01-10 06:00:00 EWR    PIT   EV     
#> 2 N10156  Fixed…       2    55  2013 2013-01-10 10:00:00 EWR    CHS   EV     
#> 3 N10156  Fixed…       2    55  2013 2013-01-10 15:00:00 EWR    MSP   EV     
#> 4 N10156  Fixed…       2    55  2013 2013-01-11 06:00:00 EWR    CMH   EV     
#> 5 N10156  Fixed…       2    55  2013 2013-01-11 11:00:00 EWR    MCI   EV     
#> 6 N10156  Fixed…       2    55  2013 2013-01-11 18:00:00 EWR    PWM   EV     
#> # … with 284,164 more rows

Filtering joins

The number of matches also determines the behavior of the filtering joins. The semi-join keeps rows in x that have one or more matches in y, as in #fig-join-semi. The anti-join keeps rows in x that match zero rows in y, as in #fig-join-anti. In both cases, only the existence of a match is important; it doesn’t matter how many times it matches. This means that filtering joins never duplicate rows like mutating joins do.

Cross joins

A cross join matches everything, as in #fig-join-cross, generating the Cartesian product of rows. This means the output will have nrow(x) * nrow(y) rows.

Cross joins are useful when generating permutations. For example, the code below generates every possible pair of names. Since we’re joining df to itself, this is sometimes called a self-join. Cross joins use a different join function because there’s no distinction between inner/left/right/full when you’re matching every row.

df <- tibble(name = c("John", "Simon", "Tracy", "Max"))
df |> cross_join(df)
#> # A tibble: 16 × 2
#>   name.x name.y
#>   <chr>  <chr> 
#> 1 John   John  
#> 2 John   Simon 
#> 3 John   Tracy 
#> 4 John   Max   
#> 5 Simon  John  
#> 6 Simon  Simon 
#> # … with 10 more rows

Inequality joins

Inequality joins use <, <=, >=, or > to restrict the set of possible matches, as in #fig-join-gte and #fig-join-lt.

Inequality joins are extremely general, so general that it’s hard to come up with meaningful specific use cases. One small useful technique is to use them to restrict the cross join so that instead of generating all permutations, we generate all combinations:

df <- tibble(id = 1:4, name = c("John", "Simon", "Tracy", "Max"))

df |> left_join(df, join_by(id < id))
#> # A tibble: 7 × 4
#>    id.x name.x  id.y name.y
#>   <int> <chr>  <int> <chr> 
#> 1     1 John       2 Simon 
#> 2     1 John       3 Tracy 
#> 3     1 John       4 Max   
#> 4     2 Simon      3 Tracy 
#> 5     2 Simon      4 Max   
#> 6     3 Tracy      4 Max   
#> # … with 1 more row

Rolling joins

Rolling joins are a special type of inequality join where instead of getting every row that satisfies the inequality, you get just the closest row, as in #fig-join-closest. You can turn any inequality join into a rolling join by adding closest(). For example join_by(closest(x <= y)) matches the smallest y that’s greater than or equal to x, and join_by(closest(x > y)) matches the biggest y that’s less than x.

Rolling joins are particularly useful when you have two tables of dates that don’t perfectly line up and you want to find (e.g.) the closest date in table 1 that comes before (or after) some date in table 2.

For example, imagine that you’re in charge of the party planning commission for your office. Your company is rather cheap so instead of having individual parties, you only have a party once each quarter. The rules for determining when a party will be held are a little complex: parties are always on a Monday, you skip the first week of January since a lot of people are on holiday, and the first Monday of Q3 2022 is July 4, so that has to be pushed back a week. That leads to the following party days:

parties <- tibble(
  q = 1:4,
  party = lubridate::ymd(c("2022-01-10", "2022-04-04", "2022-07-11", "2022-10-03"))
)

Now imagine that you have a table of employee birthdays:

employees <- tibble(
  name = wakefield::name(100),
  birthday = lubridate::ymd("2022-01-01") + (sample(365, 100, replace = TRUE) - 1)
)
employees
#> # A tibble: 100 × 2
#>   name       birthday  
#>   <variable> <date>    
#> 1 Lindzy     2022-08-11
#> 2 Santania   2022-03-01
#> 3 Gardell    2022-03-04
#> 4 Cyrille    2022-11-15
#> 5 Kynli      2022-07-09
#> 6 Sever      2022-02-03
#> # … with 94 more rows

And for each employee we want to find the first party date that comes after (or on) their birthday. We can express that with a rolling join:

employees |> 
  left_join(parties, join_by(closest(birthday >= party)))
#> # A tibble: 100 × 4
#>   name       birthday       q party     
#>   <variable> <date>     <int> <date>    
#> 1 Lindzy     2022-08-11     3 2022-07-11
#> 2 Santania   2022-03-01     1 2022-01-10
#> 3 Gardell    2022-03-04     1 2022-01-10
#> 4 Cyrille    2022-11-15     4 2022-10-03
#> 5 Kynli      2022-07-09     2 2022-04-04
#> 6 Sever      2022-02-03     1 2022-01-10
#> # … with 94 more rows

There is, however, one problem with this approach: the folks with birthdays before January 10 don’t get a party:

employees |> 
  anti_join(parties, join_by(closest(birthday >= party)))
#> # A tibble: 4 × 2
#>   name       birthday  
#>   <variable> <date>    
#> 1 Janeida    2022-01-04
#> 2 Aires      2022-01-07
#> 3 Mikalya    2022-01-06
#> 4 Carlynn    2022-01-08

To resolve that issue we’ll need to tackle the problem a different way, with overlap joins.

Overlap joins

Overlap joins provide three helpers that use inequality joins to make it easier to work with intervals:

• between(x, y_lower, y_upper) is short for x >= y_lower, x <= y_upper.
• within(x_lower, x_upper, y_lower, y_upper) is short for x_lower >= y_lower, x_upper <= y_upper.
• overlaps(x_lower, x_upper, y_lower, y_upper) is short for x_lower <= y_upper, x_upper >= y_lower.

Let’s continue the birthday example to see how you might use them. There’s one problem with the strategy we used above: there’s no party preceding the birthdays Jan 1-9. So it might be better to to be explicit about the date ranges that each party spans, and make a special case for those early birthdays:

parties <- tibble(
  q = 1:4,
  party = lubridate::ymd(c("2022-01-10", "2022-04-04", "2022-07-11", "2022-10-03")),
  start = lubridate::ymd(c("2022-01-01", "2022-04-04", "2022-07-11", "2022-10-03")),
  end = lubridate::ymd(c("2022-04-03", "2022-07-11", "2022-10-02", "2022-12-31"))
)
parties
#> # A tibble: 4 × 4
#>       q party      start      end       
#>   <int> <date>     <date>     <date>    
#> 1     1 2022-01-10 2022-01-01 2022-04-03
#> 2     2 2022-04-04 2022-04-04 2022-07-11
#> 3     3 2022-07-11 2022-07-11 2022-10-02
#> 4     4 2022-10-03 2022-10-03 2022-12-31

Hadley is hopelessly bad at data entry so he also wanted to check that the party periods don’t overlap. One way to do this is by using a self-join to check to if any start-end interval overlap with another:

parties |> 
  inner_join(parties, join_by(overlaps(start, end, start, end), q < q)) |> 
  select(start.x, end.x, start.y, end.y)
#> # A tibble: 1 × 4
#>   start.x    end.x      start.y    end.y     
#>   <date>     <date>     <date>     <date>    
#> 1 2022-04-04 2022-07-11 2022-07-11 2022-10-02

Ooops, there is an overlap, so let’s fix that problem and continue:

parties <- tibble(
  q = 1:4,
  party = lubridate::ymd(c("2022-01-10", "2022-04-04", "2022-07-11", "2022-10-03")),
  start = lubridate::ymd(c("2022-01-01", "2022-04-04", "2022-07-11", "2022-10-03")),
  end = lubridate::ymd(c("2022-04-03", "2022-07-10", "2022-10-02", "2022-12-31"))
)

Now we can match each employee to their party. This is a good place to use unmatched = "error" because we want to quickly find out if any employees didn’t get assigned a party.

employees |> 
  inner_join(parties, join_by(between(birthday, start, end)), unmatched = "error")
#> # A tibble: 100 × 6
#>   name       birthday       q party      start      end       
#>   <variable> <date>     <int> <date>     <date>     <date>    
#> 1 Lindzy     2022-08-11     3 2022-07-11 2022-07-11 2022-10-02
#> 2 Santania   2022-03-01     1 2022-01-10 2022-01-01 2022-04-03
#> 3 Gardell    2022-03-04     1 2022-01-10 2022-01-01 2022-04-03
#> 4 Cyrille    2022-11-15     4 2022-10-03 2022-10-03 2022-12-31
#> 5 Kynli      2022-07-09     2 2022-04-04 2022-04-04 2022-07-10
#> 6 Sever      2022-02-03     1 2022-01-10 2022-01-01 2022-04-03
#> # … with 94 more rows

Exercises

1. Can you explain what’s happening with the keys in this equi-join? Why are they different?

   x |> full_join(y, by = "key")
   #> # A tibble: 4 × 3
   #>     key val_x val_y
   #>   <dbl> <chr> <chr>
   #> 1     1 x1    y1   
   #> 2     2 x2    y2   
   #> 3     3 x3    <NA> 
   #> 4     4 <NA>  y3
   
   x |> full_join(y, by = "key", keep = TRUE)
   #> # A tibble: 4 × 4
   #>   key.x val_x key.y val_y
   #>   <dbl> <chr> <dbl> <chr>
   #> 1     1 x1        1 y1   
   #> 2     2 x2        2 y2   
   #> 3     3 x3       NA <NA> 
   #> 4    NA <NA>      4 y3

2. When finding if any party period overlapped with another party period we used q < q in the join_by()? Why? What happens if you remove this inequality?