Skip to main content

Piping

r
Using the pipe operator to have more readable code
Authors

Etienne Bacher

Will Gearty

Published

November 16, 2026

View source file

Objectives

  • Learn more about the pipe operator (|>) and how to use it to write more readable code

Piping

Example without the pipe

Let’s say we want to process the mtcars dataset as follows:

  • keep the first 10 rows
  • keep the observations where cyl >= 6
  • sort the remaining data by the am column.

We could do this in two different ways: by assigning intermediate output or by nesting function calls.

Intermediate objects

First, we can assign each function output to an object. This object can keep the same name and be overwritten at each step:

# Same name gets overwritten
res <- head(mtcars, 10)
res <- subset(res, cyl >= 6)
res <- sort_by(res, ~ am)
res
                   mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
Duster 360        14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
Merc 280          19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4

However, if we want to rename res in the future then we must be careful to rename all its occurrences throughout the code. It also means that if, say, the call to sort_by() is wrong, then we must run the entire block again so that res is properly reset. Depending on the data size and operations to run, this can be very time-consuming.

An alternative is to use a collection of temporary names:

# Temporary names
tmp1 <- head(mtcars, 10)
tmp2 <- subset(tmp1, cyl >= 6)
res <- sort_by(tmp2, ~ am)
res
                   mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
Duster 360        14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
Merc 280          19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4

This is also not ideal because we will potentially pollute the global environment with lots of temporary objects. Additionally, using a counter in a temporary name means that we will, for instance, need to update multiple names if we want to add an operation between the first and second step.

Nested calls

The second approach isn’t to define intermediate objects, but instead to run all those calls at once by nesting functions:

res <- sort_by(subset(head(mtcars, 10), cyl >= 6), ~ am)
res
                   mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
Duster 360        14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
Merc 280          19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4
# Same code with different formatting
res <- sort_by(
  subset(
    head(mtcars, 10),
    cyl >= 6
  ),
  ~ am
)
res
                   mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
Duster 360        14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
Merc 280          19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4

We didn’t define intermediate objects, but to read this code we now need to start from the innermost code (head(mtcars, 10)) and expand outwards. This may hurt code readability.

Introducing the pipe

Using “|>”

The pipe is a way to chain operations in natural reading order by automatically passing the output of the left-hand side code to the next call. Using the pipe |> with the example above would give:

res <- head(mtcars, 10) |> 
  subset(cyl >= 6) |> 
  sort_by(~ am)
res
                   mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
Duster 360        14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
Merc 280          19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4

The pipe can be read as “and then”: we keep the first 10 rows, and then we apply our filter, and then we sort the remaining data.

While we have used <- to assign the output above, we could have used -> to move the assignment to the end of the chain:

head(mtcars, 10) |> 
  subset(cyl >= 6) |> 
  sort_by(~ am) -> res

# Equivalent:
head(mtcars, 10) |> 
  subset(cyl >= 6) |> 
  sort_by(~ am) -> 
  res

We now have some code that doesn’t require intermediate objects, but is also easy to read because we see operations in the order in which they are executed.

The |> operator was introduced in R 4.1, released in 2021, meaning that you cannot use it in older versions of R.

Note that |> requires a function call on the right-hand side:

1:3 |> mean()
[1] 2
1:3 |> mean
Error in mean: The pipe operator requires a function call as RHS (<input>:1:8)

This differs from the magrittr pipe, %>%.

Using “_”

In the code above, we could seamlessly chain operations because each of those functions take the input data as their first argument.

This is not always the case. For instance, grepl() (which detects whether elements of a character vector match a specific pattern) takes the vector to check in second position:

let <- letters[1:6]
grepl("a|e", let)
[1]  TRUE FALSE FALSE FALSE  TRUE FALSE

Using |> without specifying the position of the input would lead to incorrect code:

let |> 
  grepl("a|e")
Warning in grepl(let, "a|e"): argument 'pattern' has length > 1 and only the
first element will be used
[1] TRUE

The code above is equivalent to grepl(let, "a|e"), which is not what we want and is the cause of the warning. We want to tell grepl() that the data we’re passing via |> should end up in second position. To do so, we can use _:

let |> 
  grepl("a|e", x = _)
[1]  TRUE FALSE FALSE FALSE  TRUE FALSE

Some operations don’t have named arguments but still require specifying _, e.g. to extract a column and then compute its mean:

mtcars |> 
  _$drat |> 
  mean()
[1] 3.596563

Note that using _ comes with a few restrictions:

  • this operator is available since R 4.2 (released in 2022);

  • _ must be used on a named argument (except in some cases, such as $ shown above). For example, this fails:

    let |> 
      grepl("a|e", _)
    Error in grepl("a|e", "_"): pipe placeholder can only be used as a named argument (<input>:2:3)
  • a function call can contain only one _:

    mtcars$drat |> 
      cor(x = _, y = _)
    Error in cor(x = "_", y = "_"): pipe placeholder may only appear once (<input>:2:3)

Using anonymous functions in a piped chain

So far, we have only used functions provided in base R (though we could have used functions from other packages). Sometimes, it is necessary to run custom code on the data without creating a dedicated new function for that, i.e. we want to use an anonymous function. If you have used one of the *apply() functions before, then you may have used anonymous functions:

# The function below is anonymous: it isn't assigned to anything, we 
# just create it on the fly:
lapply(my_list, function(x) {
  (x - mean(x) / sd(x))
})

To use an anonymous function in a piped chain, we need to wrap it in parentheses and evaluate it with () at the end of its definition:

mtcars |> 
  subset(cyl == 4) |> 
  (function(d) lm(mpg ~ disp, data = d))()

Call:
lm(formula = mpg ~ disp, data = d)

Coefficients:
(Intercept)         disp  
    40.8720      -0.1351  

What about “%>%”?

You may have seen code that chains operations using %>%. This %>% is also a pipe and it is provided by the magrittr package. It predates |> and was widely used in the tidyverse. Its design and popularity inspired the implementation of |> in base R in 2021.

For simple cases, |> and %>% behave identically. We recommend using |> simply because it is always available in R and doesn’t rely on an external package (and the Tidyverse style guide also recommends |>).



Session info
─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.6.2 (2026-10-29)
 os       Ubuntu 26.04.1 LTS
 system   x86_64, linux-gnu
 ui       X11
 language (EN)
 collate  C.UTF-8
 ctype    C.UTF-8
 tz       UTC
 date     2026-11-16
 pandoc   3.7.0.2 @ /usr/bin/pandoc
 quarto   1.11.9 @ /usr/local/bin/quarto

──────────────────────────────────────────────────────────────────────────────