49

tl;dr version of my question

If I want to import packages, do I have to manually write import() directives into my NAMESPACE file? It seems like roxygen2 won't magically do that for me, even if I have them listed as "Imports:" in my description.

Fuller Version

This is a pretty dumb question, but I ask because the answer's not obvious to me.

I use roxygen2 to handle my R package documentation. When I want to be sure a function is exported, I add an @export tag to its roxygen block. Subsequent runs of roxygenize() will write the NAMESPACE directive accordingly.

But, my package currently imports several others:

Depends:
    R (>= 2.13.0),
    ggplot2 (>= 0.8.9)
Imports:
    RColorBrewer,
    plyr,
    gridExtra

It appears that while roxygen2 will rewrite the NAMESPACE directive for exported functions, it won't automatically rewrite NAMESPACE to reflect packages I've designated should be imported in my DESCRIPTION.

briandk
  • 6,749
  • 8
  • 36
  • 46
  • 5
    AFAIK, as long as you tag your function with `@imports package` or `@importsFrom package function`, `roxygen2` will take care of writing the `namespace` directives. – Ramnath Dec 22 '11 at 01:01
  • 5
    Currently, the namespace roclet will modify `NAMESPACE` but not `DESCRIPTION` – hadley Dec 22 '11 at 01:02
  • @Ramnath That's exactly the solution I was looking for! If you post it as a quick answer I can formally accept it. – briandk Dec 23 '11 at 17:05
  • 1
    to avoid the confusion I had, @Ramnath is right, but it should be `@importFrom package function`, not `--@importsFrom`.(no s) – ldecicco May 02 '13 at 15:37
  • Am I right in saying that user always has to manually write their `DESCRIPTION` file? So one workflow is to use `@imports` in Roxygen2, and then inspect the autogenerated `NAMESPACE` for `imports` statements, and manually transcribe the libraries into `Imports:` in `DESCRIPTION`? – RobinL May 10 '17 at 10:34
  • 2
    @RobinL I think you have two options. Say the package you want to import is dplyr. Option 1: use `@import dplyr` in the roxygen block of your .R file, then refer to dplyr functions in your code like this: `select()`. Option 2 is to put dplyr in the `Imports: ` field of your `DESCRIPTION`, then use `::` notation in your R files, like this: `dplyr::select`. If you're using the package a lot in a given file, I suggest you use `@import`. If you only use it a little, I suggest double colon notation and listing it ONLY in `Imports: `. – briandk May 25 '17 at 13:57
  • 1
    @RobinL > It’s common for packages to be listed in Imports in DESCRIPTION, but not in NAMESPACE. In fact, this is what I recommend: list the package in DESCRIPTION so that it’s installed, then always refer to it explicitly with pkg::fun(). Unless there is a strong reason not to, it’s better to be explicit. It’s a little more work to write, but a lot easier to read when you come back to the code in the future. The converse is not true. Every package mentioned in NAMESPACE must also be present in the Imports or Depends fields. Source: http://r-pkgs.had.co.nz/namespace.html#imports – briandk May 25 '17 at 14:00

1 Answers1

45

Expanding on my comment, if you want to automatically add namespace directives for packages/functions you import, you can do so by adding the @imports package or @importFrom package function line to the roxygen2 documentation header of your function.

However, as @hadley pointed out, it will only modify the NAMESPACE, but not affect the package DESCRIPTION

Ramnath
  • 54,439
  • 16
  • 125
  • 152
  • Per JPMac's comment above: Shouldn't it be `@importFrom package function ...`? – krlmlr Feb 03 '14 at 10:26
  • Yes. It should be `@importFrom package function`. I have edited my answer to reflect that. Thanks for catching it. – Ramnath Feb 03 '14 at 12:52
  • 5
    I now recommend using `package::function`, not `@importFrom package function`. – hadley Mar 23 '14 at 23:04
  • 4
    So do you mean `@import package::function` ? – Ramnath Mar 23 '14 at 23:07
  • 2
    @Ramnath From the bottom section here (http://cran.r-project.org/web/packages/roxygen2/vignettes/namespace.html) it seems like you don't need @import if you're going to use `package::function()` when you call it as long as it's in the `Imports:` section of `DESCRIPTION`. – Ari B. Friedman May 29 '14 at 12:59
  • Yes. `roxygen2` made some changes to make things easier I believe. – Ramnath May 29 '14 at 13:41
  • Is it @import or @imports? – pete Jul 10 '14 at 23:00
  • 1
    Funny. I use package::function(), and the package is in the Imports section of DESCRIPTION, and I have done load_all(".") on the package...and yet the function could not be found. Edit: Ah, it appears if you are using RStudio, you ahve to specify that roxygen will generate NAMESPACE file. – Brash Equilibrium Sep 09 '14 at 02:20
  • 2
    In addition, I had forgotten that you must call `document()` to update NAMESPACE, not `load_all()` – Brash Equilibrium Sep 09 '14 at 02:38
  • 4
    @pete it's `@import` in the roxygen2 header; it's `import()` in the NAMESPACE; and it's `Imports:` in the DESCRIPTION – woodvi May 16 '16 at 17:24