What does |> (pipe greater than) mean in R?

Question

I have recently come across the code |> in R. It is a vertical line character (pipe) followed by a greater than symbol.

Here is an example:

mtcars |> head()

What is the |> code doing?

Answer 1

|> is the base R "pipe" operator. It was new in version 4.1.0.

In brief, the pipe operator provides the result of the left hand side (LHS) of the operator as the first argument of the right hand side (RHS).

Consider the following:

1:3 |> sum()
#[1] 6

Here, the vector of numbers 1 through 3 is provided as the first argument of the sum function.

The left hand side result always becomes the first argument of the right hand side call. Consider:

args(sum)
#function (..., na.rm = FALSE) 

c(1:3, NA_real_) |> sum(na.rm = TRUE)
#[1] 6

The emphasis on call is important because you can redirect the LHS to other arguments as long as the first argument is named. Consider:

args(rnorm)
#function (n, mean = 0, sd = 1) 
100 |> rnorm(n = 5)
#[1]  99.94718  99.93527  97.46838  97.38352 100.56502

args(sum)
#function (..., na.rm = FALSE) 
sum(na.rm = TRUE, ... = c(1:2,NA_real_))
#[1] 3
TRUE |> sum(... = c(1:2,NA_real_))
#[1] NA

---

One benefit of using the |> operator is that it can make code more easy to follow logically compared to nested function calls:

split(x = iris[-5], f = iris$Species) |>
  lapply(min) |>
  do.call(what = rbind) 
#           [,1]
#setosa      0.1
#versicolor  1.0
#virginica   1.4

#Compared to:
do.call(rbind,lapply(split(iris[-5],iris$Species),min))

---

This functionality is similar to the magrittr::%>% operator (also implemented in dplyr).

However, unlike %>%, there is no current way to pipe the LHS into the right hand side multiple times or into arbitrary positions. Magrittr uses the . placeholder for the LHS and {} to place it arbitrarily.

library(magrittr)
iris[iris$Sepal.Length > 7,] %>% subset(.$Species=="virginica")

TRUE %>% {sum(c(1:2,NA_real_),na.rm = .)}
[1] 3

Additionally, unlike the base R |>, the %>% operator can pipe into function calls without ():

1:3 |> sum
#Error: The pipe operator requires a function call as RHS

1:3 %>% sum
#[1] 6

Answer 2

To see how the piped code gets parsed we may use quote().

Examples:

quote(1:3 |> sum())
# sum(1:3)

quote(100 |> rnorm(n = 5))
# rnorm(100, n = 5)

quote(split(x = iris[-5], f = iris$Species) |>
        lapply(min) |>
        do.call(what = rbind))
# do.call(lapply(split(x = iris[-5], f = iris$Species), min), what = rbind)

Answer 3

Since I also recently stumbled upon this pipe in a peer's code I looked into the topic and found out that as of R 4.2 you can also pipe the LHS into the right-hand side at arbitrary positions (however, not multiple times, only once) and with a different syntax:

As of R 4.2: you can use |> in combination with _

This means, base R can do some of what magittr does, too:

# magittr
library(magrittr)
TRUE %>% sum(c(1:2, NA_real_), na.rm = .)

# R 4.2 onwards
TRUE |> sum(c(1:2, NA_real_), na.rm = _)

As of R 4.1 you can use => in combination with a variable that you pipe into |> a => f(..., x = a, ...)

# R 4.1 onwards
# you have to set the '_R_USE_PIPEBIND_' envvar to a true value to enable =>
Sys.setenv("_R_USE_PIPEBIND_"=TRUE)
TRUE |> a => sum(c(1:2, NA_real_), na.rm = a)