# magrittr v1.5

0

0th

Percentile

## A Forward-Pipe Operator for R

Provides a mechanism for chaining commands with a new forward-pipe operator, %>%. This operator will forward a value, or the result of an expression, into the next function call/expression. There is flexible support for the type of right-hand side expressions. For more information, see package vignette. To quote Rene Magritte, "Ceci n'est pas un pipe."

# Introduction

The magrittr package offers a set of operators which promote semantics that will improve your code by

• structuring sequences of data operations left-to-right (as opposed to from the inside and out),
• avoiding nested function calls,
• minimizing the need for local variables and function definitions, and
• making it easy to add steps anywhere in the sequence of operations.

The operators pipe their left-hand side values forward into expressions that appear on the right-hand side, i.e. one can replace f(x) with x %>% f, where %>% is the (main) pipe-operator. When coupling several function calls with the pipe-operator, the benefit will become more apparent. Consider this pseudo example

the_data <-
subset(variable_a > x) %>%
transform(variable_c = variable_a/variable_b) %>%


Four operations are performed to arrive at the desired data set, and they are written in a natural order: the same as the order of execution. Also, no temporary variables are needed. If yet another operation is required, it is straight-forward to add to the sequence of operations wherever it may be needed.

# Installation

To install the current development version use devtools:

devtools::install_github("smbache/magrittr")


To install the CRAN version:

install.packages("magrittr")


# Features

### Basic piping:

• x %>% f is equivalent to f(x)
• x %>% f(y) is equivalent to f(x, y)
• x %>% f %>% g %>% h is equivalent to h(g(f(x)))

### The argument placeholder

• x %>% f(y, .) is equivalent to f(y, x)
• x %>% f(y, z = .) is equivalent to f(y, z = x)

### Re-using the placeholder for attributes

It is straight-forward to use the placeholder several times in a right-hand side expression. However, when the placeholder only appears in a nested expressions magrittr will still apply the first-argument rule. The reason is that in most cases this results more clean code.

x %>% f(y = nrow(.), z = ncol(.)) is equivalent to f(x, y = nrow(x), z = nrow(x))

The behavior can be overruled by enclosing the right-hand side in braces:

x %>% {f(y = nrow(.), z = ncol(.))} is equivalent to f(y = nrow(x), z = nrow(x))

### More advanced right-hand sides and lambdas

To define a unary function on the fly in the pipeline, enclose the body of such function in braces, and refer to the argument as ., e.g.

iris %>%
{
n <- sample(1:10, size = 1)
T <- tail(., n)
rbind(H, T)
} %>%
summary


### Building (unary) functions

Any pipeline starting with the . will return a function which can later be used to apply the pipeline to values. Building functions in magrittr is therefore similar to building other values.

f <- . %>% cos %>% sin
# is equivalent to
f <- function(.) sin(cos(.))


### Tee operations

Some right-hand sides are used for their side effect (e.g. plotting, printing to a file, etc) and it may be convenient to be able to subsequently continue the pipeline. The "tee" operator, %T>% can be used for this purpose and works exactly like %>%, except it returns the left-hand side value, rather than the potential result of the right-hand side operation:

rnorm(200) %>%
matrix(ncol = 2) %T>%
plot %>% # plot usually does not return anything.
colSums


### Pipe with exposition of variables

Many functions accept a data argument, e.g. lm and aggregate, which is very useful in a pipeline where data is first processed and then passed into such a function. There are also functions that do not have a data argument, for which it is useful to expose the variables in the data. This is done with the %$% operator: iris %>% subset(Sepal.Length > mean(Sepal.Length)) %$%
cor(Sepal.Length, Sepal.Width)

data.frame(z = rnorm(100)) %$% ts.plot(z)  ### Compound assignment pipe operations There is also a pipe operator which can be used as shorthand notation in situations where the left-hand side is being "overwritten": iris$Sepal.Length <-
iris$Sepal.Length %>% sqrt  To avoid the repetition of the left-hand side immediately after the assignment operator, use the %<>% operator: iris$Sepal.Length %<>% sqrt


This operator works exactly like %>%, except the pipeline assigns the result rather than returning it. It must be the first pipe operator in a longer chain.

# Further information

For more detail, see the package vignette

vignette("magrittr")


## Functions in magrittr

 Name Description %<>% magrittr compound assignment pipe-operator extract Aliases print.fseq Print method for functional sequence. %\$% magrittr exposition pipe-operator [[.fseq Extract function(s) from a functional sequence. %T>% magrittr tee operator freduce Apply a list of functions sequentially %>% magrittr forward-pipe operator debug_fseq Debugging function for functional sequences. debug_pipe Debugging function for magrittr pipelines. magrittr magrittr - Ceci n'est pas un pipe functions Extract the function list from a functional sequence. %>% magrittr forward-pipe operator %T>% magrittr tee operator %<>% magrittr compound assignment pipe-operator No Results!