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