133

I would like to use the pipe-operator %>% introduced in the magrittr package in a package I wrote myself to chain dplyr data transformations. magrittr is listed as Import in the DESCRIPTION file. After loading my own package and testing the function which uses the pipe-operator I get the following error message:

Error in functionname(parameter, : could not find function "%>%"

Changing %>% to magrittr::%>% in the function source code does not help either because the package cannot be built anymore.

tonytonov
  • 25,060
  • 16
  • 82
  • 98
alexander keth
  • 1,415
  • 2
  • 10
  • 7
  • 9
    I would advise against the pipe operator inside a function inside a package. It makes debugging a lot harder (the call stack gets insanely deep with the pipe). For packages I'd just overwrite a temporary variable, which makes testing a lot easier (think: R telling you on what line the error occurred). The pipe is fine for interactive use but for programming it can be a burden. –  May 23 '17 at 12:55

4 Answers4

121

It should have worked correctly if you had magrittr listed in Depends. However, this is not advised. Instead, you leave magrittr in Imports and add the following line to NAMESPACE:

importFrom(magrittr,"%>%")

I suggest reading Writing R extensions. Your question is covered in paragraphs 1.1.3 and 1.5.1.

Community
  • 1
  • 1
tonytonov
  • 25,060
  • 16
  • 82
  • 98
  • 2
    @alexanderketh In that case you should hit the green tick mark next to the answer to mark it as accepted. Welcome to SO! – tonytonov Jan 19 '15 at 12:03
  • 59
    If you're using `roxygen2`, you could add `#' importFrom magrittr "%>%"` to have NAMESPACE populated automatically during `roxygenize()`. – Roman Luštrik Feb 11 '15 at 15:20
  • 44
    @RomanLuštrik, just missing @, should be `#' @importFrom magrittr "%>%"` – Roah Aug 14 '15 at 18:05
  • 15
    Note that this will only allow you to use `%>%` internally in your package. If your API requires users to chain functions using `%>%`, they will still have to explicitly load `magrittr`. One way to solve this problem is to re-export the function. Here is [an example](https://github.com/rstudio/ggvis/blob/master/R/pipe.R) of how to do it. – Ramnath Dec 28 '15 at 07:10
  • 1
    This is also what the usethis package does, as mentioned [here](https://stackoverflow.com/a/52231630/4627134) – jiggunjer Jul 13 '20 at 08:22
59

There's now an easier way to support the pipe in your packages. The wonderful package usethis has the function use_pipe(). You run that function once and it handles everything. This is how the use_pipe() function is described in the usethis documentation:

Does setup necessary to use magrittr's pipe internally in your package and to re-export it for users of your package:

Adds magrittr to "Imports" in DESCRIPTION

Creates R/utils-pipe.R with the necessary roxygen template

Andrew Brēza
  • 7,705
  • 3
  • 34
  • 40
  • 1
    Do you add the line `use_pipe()` to the code that you use to build the package? For example, I run: `usethis::use_description(usethis_description); usethis::use_build_ignore(directories); usethis::use_build_ignore(paste0(pkg_name, ".Rproj")); if (file.exists(file.path(pkg_path, "NAMESPACE"))) { file.remove(file.path(pkg_path, "NAMESPACE")) }; devtools::document(pkg_path); devtools::check(pkg_path); devtools::load_all(pkg_path); devtools::install(pkg_path)`. Would I just add `use_pipe()` at the beginning? – Josh Jul 09 '19 at 13:13
  • 1
    @Josh you use the `usethis` functions once when you're developing the package. Those functions then add the necessary parts to the build instructions and everything else. – Andrew Brēza Jul 09 '19 at 13:52
  • Would you kindly explain the mechanism of this method? What is the difference between making your package depends on `magrittr` vs `usethis`? – aiorr Jul 16 '22 at 20:57
  • 1
    @aiorr this is basically a shortcut that handles all of the behind-the-scenes work for you. No improvement in functionality compared to manually setting up the settings. – Andrew Brēza Jul 17 '22 at 17:48
37

One additional solution - use the roxygen package. It's implemented as part of the devtools package. Once devtools is installed, calling devtools::document() will update your NAMESPACE for you. It also auto-builds .Rd files with documentation, which is handy.

All you do is add a special comment in the format #' @import packagename to a file to import all functions from that package, or #' @importFrom packagename functionname to import a function. You can have as many of these comments as you want in your files, so you can have a set of them at the top of each file, or with each of your functions that needs an external function.

Then you run devtools::document() and it parses your code looking for those comments, and then it creates an appropriate NAMESPACE file for you. Easy.

Mike Stanley
  • 1,420
  • 11
  • 13
  • 1
    When I do this, it messes up the following oxygen comments that pertain to the help file for the first function in the R script. How do I separate global oxygen comments from the help file ones? – jzadra Oct 24 '17 at 21:36
  • 2
    I usually put the import comments with each function individually. That way if other functions in the file change, your imports stay accurate. So then there are no global definitions. – Mike Stanley Oct 24 '17 at 21:39
20

Assuming that you're using RStudio, Hadley's devtools package, and listed magrittr in the Imports section of the DESCRIPTION file, here are steps I took to make %>% work in my package function(s).

First, write function foo.R:

#' Convert \code{data.frame} to \code{list}.
#' 
#' @importFrom magrittr %>%
#' @name %>%
#' @rdname pipe
#' @export
#' @param x A \code{data.frame} object.
#' @examples
#' my_result <- foo(iris)
#'
foo <- function(x) {
    x %>%
        as.list()
}

Second, run devtools::document().

Third, run devtools::load_all().

A file like this will be created in your R/ directory and your function should work as expected.

Jubbles
  • 4,450
  • 8
  • 35
  • 47