README.Rmd

---
output: github_document
---


```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/"
)
library(pipes)
```


# pipes

Install and attach package:

```{r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("moodymudskipper/pipes")
library(pipes)
```

The *pipes* package expands the *magrittr* package by providing :

* More pipe operators to debug, print extra info, suppress warnings or
messages etc
* A convenient way to create custom pipes
* A couple of pipe friendly functions for printing (`pprint`) and testing (`pif`).

The package works just as *magrittr* except that:

* `alias` functions were not imported
* pipes have a class `pipe` and have a dedicated printing method

*magrittr* doesn't need to be attached, but attaching it before *pipes* will
make the alias functions available.

## New operators

* **`%D>%`** : Debug the pipe chain at the relevant step
* **`%V>%`** : Use `View()` on the output
* **`%L>%`** : Log the relevant call and execution time to the console
* **`%P>%`** : Use `print()` on the output
* **`%summary>%`** : Print the `summary()` off the output
* **`%glimpse>%`** : Use `tibble::glimpse()` on the output
* **`%skim>%`** : Use `skimr::skim()` on the output
* **`%ae>%`** : Use `all.equal` on the input and output
* **`%compare>%`** : Use `arsenal::compare()` and open the report of the 
  differences in the default browser window
* **`%gg>%`** : Apply the `rhs` to the data of a `gg` object and return the 
  modified `gg` object
* **`%nowarn>%`** : Silence warnings
* **`%nomsg>%`** : Silence messages
* **`%strict>%`** : Fail on warning
* **`%try>%`** : Try, and in case of failure prints error and returns input
* **`%quietly>%`** : Use `purrr::quietly()` to capture outputs of all kind and print them

Let's showcase a few of them.

debug the chain:

```{r, , eval = FALSE}
iris %>% head(2) %D>% `[`(4:5)
```

view steps of chain in the viewer:

```{r, eval = FALSE}
iris %V>% head(2) %V>% `[`(4:5)
```

Log steps in the console:

```{r}
iris %L>% {Sys.sleep(1);head(.,2)} %L>% {Sys.sleep(2);.[4:5]}
```

Use `print`, `summary` or `glimpse` on output:

```{r}
iris %P>% head(2) %P>% `[`(4:5)

iris %summary>% head(2) %summary>% `[`(4:5)

iris %glimpse>% head(2) %glimpse>% `[`(4:5)
```

Use `all.equal` on input and output, note that the method for tibbles gives
a different output.

```{r}
iris %>% head(2) %ae>% 
  transform(Species = as.character(Species), cst = 42)

iris %>% tibble::as_tibble() %>% head(2) %ae>% 
  transform(Species = as.character(Species), cst = 42)
```

Use `arsenal::compare` on input and output, and opens a markdown report written
into a temp file.

```{r, eval = FALSE}
iris %>% head(2) %compare>% 
  transform(Species = as.character(Species), cst = 42)
```

Use *tidyverse* syntax to mofidy a *gg* object's underlying data:

```{r}
library(ggplot2,quietly = TRUE, warn.conflicts = FALSE)
ggplot(iris, aes(Species, Sepal.Width, fill=Species)) +
  geom_col() %gg>% dplyr::group_by(Species) %gg>% dplyr::summarize_at("Sepal.Width", mean) +
  ggtitle("Using dplyr verbs")
```


Silence a warning or a message:

```{r}
-1  %>% sqrt
-1  %nowarn>% sqrt
iris[50:51,3:5] %>% dplyr::left_join(iris[50:51,c(1:2,5)])
iris[50:51,3:5] %nomsg>% dplyr::left_join(iris[50:51,c(1:2,5)])
```

Strictly fail on a warning

```{r}
try(-1  %strict>% sqrt())
```

Try, and in case of failure prints error and returns input

```{r}
"a"  %try>% log()
```

Use `quietly` to capture outputs of all kind and print them.

```{r}
iris[50:51,3:5] %quietly>% 
  dplyr::left_join(iris[50:51,c(1:2,5)]) %quietly>%
  dplyr::mutate(Petal.Length = - Petal.Length, Petal.Length = sqrt(Petal.Length))
```

## `new_pipe`

It's easier to understand how to build a new `pipe` by looking at examples.

```{r}
 `%T>%`
```

If we want to rebuild this operator from scratch, all we have to do is :

```{r}
`%newT>%` <- new_pipe({
  local(BODY)
  .
})
```

`.` is the value of the input and `BODY` contains the code that would have been
executed by `%>%`, for example `iris %>% head(3)` `BODY` would be `head(.,3)`.

so what `%newT>%` is doing is executing the call in a protected environment through
`local(BODY)`, then returning the unaltered input `.`.

```{r}
iris %>% head(2) %newT>% print %>% head(1)
```

Take a look at the other functions to understand how to make your own :

```{r}
`%nowarn>%`
`%P>%`
`%summary>%`
`%strict>%`
```


## easy conditional steps with `pif`

Using functions, formulas or expressions

```{r}
iris %>% pif(is.data.frame, dim, nrow)
iris %>% pif(~is.numeric(Species), ~"numeric :)",~paste(class(Species)[1],":("))
iris %>% pif(nrow(iris) > 2, head(iris,2))
```

## print info on intermediate steps with `pprint`

```{r}
iris %>%
  pprint(~"hello")           %>%
  head(2)                    %>%
  transform(Species = NULL)  %>%
  pprint(rowSums,na.rm = TRUE) %>%
  pprint(~setNames(.[1:2],toupper(names(.[1:2])))) %>%
  pprint(dim)
```