---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = FALSE,
  warning = FALSE,
  message = FALSE,
  cache = TRUE
)
library(tidyAnimatedVerbs)
```

[gganimate]: https://github.com/thomasp85/gganimate#README
[dplyr-two-table]: https://dplyr.tidyverse.org/articles/two-table.html
[r4ds-set-ops]: http://r4ds.had.co.nz/relation-data.html#set-operations

# Tidy Animated Verbs

Garrick Aden-Buie -- [&commat;grrrck](https://twitter.com/grrrck) -- [garrickadenbuie.com](https://www.garrickadenbuie.com). Set operations contributed by [Tyler Grant Smith](https://github.com/TylerGrantSmith).

[![Binder](http://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/gadenbuie/tidy-animated-verbs/master?urlpath=rstudio)
[![CC0](https://img.shields.io/badge/license_(images)_-CC0-green.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
[![MIT](https://img.shields.io/badge/license_(code)_-MIT-green.svg)](https://opensource.org/licenses/MIT)

- Mutating Joins: [`inner_join()`](#inner-join), [`left_join()`](#left-join),
  [`right_join()`](#right-join), [`full_join()`](#full-join)
  
- Filtering Joins: [`semi_join()`](#semi-join), [`anti_join()`](#anti-join)

- Set Operations: [`union()`](#union), [`union_all()`](#union-all), [`intersect()`](#intersect), [`setdiff()`](#setdiff)
- Learn more about
    - [Relational Data](#relational-data)
    - [gganimate](#gganimate)
    

Please feel free to use these images for teaching or learning about action verbs from the [tidyverse](https://tidyverse.org).
You can directly download the [original animations](images/) or static images in [svg](images/static/svg/) or [png](images/static/png/) formats, or you can use the [scripts](R/) to recreate the images locally.

Currently, the animations cover the [dplyr two-table verbs][dplyr-two-table] and I'd like to expand the animations to include more verbs from the tidyverse.
[Suggestions are welcome!](https://github.com/gadenbuie/tidy-animated-verbs/issues)

## Installing

The library can be installed with
```{r, echo=T,eval=F}
# install.package("devtools")
devtools::install_github("gadenbuie/tidy-animated-verbs")
```

## Mutating Joins

```{r intial-dfs, echo=T}
library(tidyAnimatedVerbs)
x <- data_frame(
  id = 1:3,
  x = paste0("x", 1:3)
)

y <- data_frame(
  id = (1:4)[-3],
  y = paste0("y", (1:4)[-3])
)

animate_full_join(x, y, by = c("id"), export = "first")
```


```{r echo=TRUE}
x
y
```

### Inner Join

> All rows from `x` where there are matching values in `y`, and all columns from `x` and `y`.

```{r inner-join, echo=T}
animate_inner_join(x, y, by = "id")
```


```{r echo=TRUE}
inner_join(x, y, by = "id")
```

### Left Join

> All rows from `x`, and all columns from `x` and `y`. Rows in `x` with no match in `y` will have `NA` values in the new columns.

```{r left-join, echo=T}
animate_left_join(x, y, by = "id")
```


```{r echo=TRUE}
left_join(x, y, by = "id")
```

### Left Join (Extra Rows in y)

> ... If there are multiple matches between `x` and `y`, all combinations of the matches are returned.

```{r left-join-extra, echo=T}
y_extra <- bind_rows(y, data_frame(id = 2, y = "y5"))
y_extra # has multiple rows with the key from `x`

animate_left_join(x, y_extra, by = "id")
```

```{r echo=TRUE}
left_join(x, y_extra, by = "id")
```

### Right Join

> All rows from y, and all columns from `x` and `y`. Rows in `y` with no match in `x` will have `NA` values in the new columns.

```{r right-join, echo = T}
animate_right_join(x, y, by = "id")
```


```{r echo=TRUE}
right_join(x, y, by = "id")
```

### Full Join

> All rows and all columns from both `x` and `y`. Where there are not matching values, returns `NA` for the one missing.

```{r full-join, echo=T}
animate_full_join(x, y, by = "id")
```


```{r echo=TRUE}
full_join(x, y, by = "id")
```

## Filtering Joins

### Semi Join

> All rows from `x` where there are matching values in `y`, keeping just columns from `x`.

```{r semi-join, echo=T}
animate_semi_join(x, y, by = "id")
```


```{r echo=TRUE}
semi_join(x, y, by = "id")
```

### Anti Join

> All rows from `x` where there are not matching values in `y`, keeping just columns from `x`.

```{r anti-join, echo=T}
animate_anti_join(x, y, by = "id")
```


```{r echo=TRUE}
anti_join(x, y, by = "id")
```

## Set Operations

```{r intial-dfs-so, echo=T}

x <- tibble::tribble(
  ~x,    ~y,
  "1",  "a",
  "1",  "b",
  "2",  "a"
)

y <- tibble::tribble(
  ~x, ~y,
  "1",  "a",
  "2",  "b"
)

animate_union(x, y, export = "first")
```


```{r echo=TRUE}
x
y 
```

### Union

> All unique rows from `x` and `y`.

```{r union, echo=T}
animate_union(x, y)
```


```{r echo=TRUE}
union(x, y)
```



```{r echo=TRUE}
animate_union(y, x)

union(y, x)
```

### Union All

> All rows from `x` and `y`, keeping duplicates.

```{r union-all, echo=T}
animate_union_all(x, y)
```



```{r echo=TRUE}
union_all(x, y)
```


### Intersection

> Common rows in both `x` and `y`, keeping just unique rows.

```{r intersect, echo=T}
animate_intersect(x, y)
```


```{r echo=TRUE}
intersect(x, y)
```

### Set Difference

> All rows from `x` which are not also rows in `y`, keeping just unique rows.

```{r setdiff, echo=T}
animate_setdiff(x, y)
```


```{r echo=TRUE}
setdiff(x, y)
```


```{r echo=TRUE}
animate_setdiff(y, x)

setdiff(y, x)
```

## Learn More

### Relational Data

The [Relational Data](http://r4ds.had.co.nz/relation-data.html) chapter of the
[R for Data Science](http://r4ds.had.co.nz/) book by Garrett Grolemund and Hadley Wickham
is an excellent resource for learning more about relational data.

The [dplyr two-table verbs vignette][dplyr-two-table]
and Jenny Bryan's [Cheatsheet for dplyr join functions](http://stat545.com/bit001_dplyr-cheatsheet.html)
are also great resources.

### gganimate

The animations were made possible by the newly re-written [gganimate] package by 
[Thomas Lin Pedersen](https://github.com/thomasp85)
(original by [Dave Robinson](https://github.com/dgrtwo)).
The [package readme][gganimate] provides an excellent (and quick) introduction to gganimte.
