13

If you are a package author, you are hopefully well aware of upcoming changes in package structure when we move to 2.14 in about a week. One of the changes is that all packages will require a NAMESPACE, and one will be generated for you in the event you do not make one (the R equivalent of your Miranda rights in the US). So being good citizen I was trying to figure this out. Here is the section from R-exts:

1.6.5 Summary – converting an existing package

To summarize, converting an existing package to use a namespace involves several simple steps:

Identify the public definitions and place them in export directives. Identify S3-style method definitions and write corresponding S3method declarations. Identify dependencies and replace any require calls by import directives (and make appropriate changes in the Depends and Imports fields of the DESCRIPTION file). Replace .First.lib functions with .onLoad functions or useDynLib directives.

To ensure I do the right thing here, can someone give a short clear definition/answer (am I breaking a rule by having several small but related questions together?). All answers should take 2.14 into account, please:

  1. A definition of NAMESPACE as used by R
  2. Is there a way to generate a NAMESPACE prior to build and check, or do we b/c once and then edit the NAMESPACE created automatically?
  3. The difference between "Depends:" and "Imports:" in the DESCRIPTION file. In particular, why would a I put a package in "Depends:" instead of the "Imports:" or vice versa?
  4. It sounds like "require" is no longer to be used, though it doesn't say that. Is this the correct interpretation?

Thanks!

Bryan Hanson
  • 6,055
  • 4
  • 41
  • 78

4 Answers4

9

I've written a little on this topic at https://github.com/hadley/devtools/wiki/Namespaces.

To answer your questions:

  1. See Dirk's answer.
  2. Use roxygen2
  3. Now that every package has a namespace there is little reason to use Depends.
  4. require should only be used to load suggested packages
Daniel Watkins
  • 1,631
  • 14
  • 16
hadley
  • 102,019
  • 32
  • 183
  • 245
8

CRAN packages have had NAMESPACEs since almost time immortal. Just pick a few of your favorite CRAN packages and look at their NAMESPACE files.

It can be as easy as this one-liner (plus comment) taken from snow:

# Export all names unless they start with a dot
exportPattern("^[^.]")

The run R CMD check as usual, and you should be fine in most circumstances.

Dirk Eddelbuettel
  • 360,940
  • 56
  • 644
  • 725
  • A follow up Dirk, on the role of a NAMESPACE: What should be exported? My guess is most functions, but I can't find any place that says this clearly. In the snow example, they are choosing to hide the .functions but all the others will be "user visible"? The .functions are actually user visible too, right, if you know how to search? – Bryan Hanson Oct 24 '11 at 19:14
  • That is your design decision as maintainer. Typically everything you wrote is meant for the user, which is why the wildcard helps so much. It gets everything that starts with a letter out, yet still allows you to hide identifiers starting with a dot. – Dirk Eddelbuettel Oct 24 '11 at 20:03
  • 3
    Note that I have been Ripleyed on this subject ( http://tolstoy.newcastle.edu.au/R/e13/devel/11/03/0651.html ): "It is consdered good practice not to use exportPattern() (at least, not for broadly defined patterns) in production code: see the current 'Writing R Extensions'. Otherwise things may change under you (what nlme exports has changed recently, hence what import(nlme) brings it has). " – Ben Bolker Oct 24 '11 at 20:52
  • 2
    Too funny given that I quoted from package snow which a) does just that and b) has R Core members as principal authors :-) – Dirk Eddelbuettel Oct 24 '11 at 21:18
5

I'm going to answer my own question with a few details I've learned after switching several packages over to R 2.14.

The description above from the manual sort of gives the impression that whatever you had in Depends: for R 2.13 should be moved over to Imports: in R 2.14. You should do that, but they are not 1-for-1 functionally the same, as I hope will be clear from the notes below.

Here we go:

Depends: should probably be used only for restrictions on versions, like 'R >= 2.10' or 'MASS > 0.1' and nothing else under R 2.14.

Having a namespace is partly a mechanism of notifying users that there may be name conflicts and "replacements" -- in other words overwriting of names in use. The NAMESPACE file must match in items and in order the Imports: field in DESCRIPTION. Function names etc imported will be listed under "loaded via namespace (and not attached)" in sessionInfo(). Those packages are installed but not loaded (i.e. no library(some imported package)).

The other role of a namespace is to make functions available to your package "internally". By that, I mean that if your package uses a function in an imported package, it will be found.

However, when you have an example in an .Rd file to be run during checking, packages that you used to have under Depends: in R 2.13 but are now in Imports: under R 2.14 are not available. This is because the checking environment is pretty much like sourcing a script in a clean environment (assuming you are using R --vanilla so .Rprofiles etc have not been run). Unless you put a library(needed package) statement in your example, it won't work under R 2.14 even if it did under R 2.13. So the old examples do not necessarily run even though your package Imports: the needed packages, because again Imports: is not quite the same as Depends: (strictly, they are attached but not loaded).

Please do correct me if any of this is wrong. Many thanks to Hadley Wickham and others who helped me along!

Bryan Hanson
  • 6,055
  • 4
  • 41
  • 78
2

I recently worked on this for one of my packages. Here are my new Depends, Imports, and Suggests lines

Depends: R (>= 2.15.0)
Imports: nlme, mvtnorm, KFAS (>= 0.9.11), stats, utils, graphics
Suggests: Hmisc, maps, xtable, stringr

stats, utils and graphics are part of base R, but the user could detach them and then my package wouldn't work. If you use R from the command line, you might think 'why would anyone detach those?'. But if a user is using RStudio, say, I could see them going through and 'unclicking' all the packages. Strange thing to do, nonetheless, I don't want my package to stop working if they do that. Or they might redefine, say, the plot function (or some other function) , and then my package would fail.

My NAMESPACE then has the following lines

import(KFAS)
import(stats)
import(utils)
import(graphics)

I don't want to go through and keep track of which stats, utils and graphics functions I use, so I import their whole namespaces. For KFAS, I only need 2 functions, but the exported function names changed between versions so I import the whole namespace and then in my code test which version the user has.

For mvtnorm and nlme, I only use one function so I import just those. I could import the whole namespace, but try to only import what I really use.

importFrom(mvtnorm, rmvnorm)
importFrom(nlme, fdHess)

The vignettes where the Suggests packages appear have 

require(package)

lines in them.

For the exported functions in my NAMESPACE, I'm a little torn. CRAN has become strict in not allowing ::: in your package code. That means that if I don't export a function, I am restricting creative re-use. On the other hand, I understand the need to only export functions that you intend to maintain with a stable arg list and output otherwise we break each other's packages by changing the function interface.

Eli Holmes
  • 656
  • 7
  • 10