I'm writing an R package that's going to be used by others, so I'm trying to get this one right! I want to use roxygen for documentation and RUnit for unit testing, but I haven't used them before.
What packages exist (either on CRAN or elsewhere) that use either of these tools well?
Roxygen is used in Hadley's stringr (see also this previous SO question: R documentation with Roxygen), mutatr and testthat packages.
But testthat is used for testing in the mentioned packages instead of RUnit.
If you look at the RUnit page at CRAN you see the list of of packages that have a Depends:, Imports: or Suggests: on it. Maybe try one of those? The list includes plyr and a bunch of Rmetrics packages.
Likewise, the roxygen page at CRAN can be looked at but it only lists a single package.
Related
I often use utility type functions from other packages that are un-exported:
pkg:::fun(). I am wondering if I can use such a function within new functionality/scope in my own R package. What is the correct approach here? Is including the package in my description file enough?
Another trick is using getFromNamespace():
fun <- utils::getFromNamespace("fun", "pkg")
The only advantage over ::: is that you don't get any NOTEs and it's allowed on CRAN. Of course, this is not good practice as a hidden change in pkg can break your package.
Note: With roxygen2 you have to add the utils package to the Imports field of your DESCRIPTION file to fulfill CRAN's requirements. Alternatively, you can put it in your NAMESPACE manually.
Summarising comments from #baptise, and etc...:
::: not allowed on CRAN, so options:
ask author to export it so you can use it in your package via standard imports or suggests.
copy / lift a version of it and clearly cite within your package.
I did install.packages("choroplethr"), followed by library(choroplethr). I want to find out how to do a zip code choropleth, so I start typing in RStudio,
"?choroplethr::zip..." The only function that RStudio finds is zip_map. I go to its help file and see the following documentation:
This function is deprecated as of choroplethr version 3.0.0. Please
use ?zip_choropleth instead. The last version of choroplethr in which
this function worked was version 2.1.1, which can be downloaded from
CRAN here:
http://cran.r-project.org/web/packages/choroplethr/index.html
Okay, I guess I'll find out about this zip_choroplethr function then.
?choroplethr::zip_choroplethr
# No documentation for ‘zip_choroplethr’ in specified packages and libraries:
# you could try ‘??zip_choroplethr’
Wut.
Thank you for using choroplethr.
zip_map is, indeed, deprecated. It used scatterplots, which wasn't the best way to visualize zip codes, especially because they are so small.
Within choroplethr, Zip code choropleths are managed by a new, separate package: choroplethrZip. You can see the installation instructions and documentation here.
CRAN rejected choroplethrZip due to the size of the map, which is why it is in separate package and on github.
I'm trying to use Imports: instead of Depends: in the DESCRIPTION files of my packages, yet I still feel I've got some more to understand on this ;-)
What I learned from this post (by the way: awesome post!!!) is that everything my package, say mypkg, imports (say imported.pkg) via Imports: lives in environment imports:mypkg instead of being attached to the search path. When trying to find foo that ships with imported.pkg, R looks in imports:mypkg before traversing the search list. So far, so good.
Actual question
If imported.pkg (imported by mypkg) depends on a certain other package (stated in Depends: section of the package's DESCRIPTION file), do I need to make this very package a Depends: dependency of my package in order for R to find functions of that package? So it seems to me at the moment as otherwise R complains.
Evidence
Seems like simply importing such a package is not enough. As an example, take package roxygen2 (CRAN). It depends on digest while importing a bunch of other packages. I imported it (along with digest as mypkg also needs it) and checked environment imports:mypkg which does list the digest function: "digest" %in% parent.env(asNamespace("mypkg")) returns TRUE
Yet when running roxygenize() from within a function that is part of mypkg, R complains that it can't find digest.
You could have a look at my blog : http://r2d2.quartzbio.com/posts/package-depends-dirty-hack-solution.html
Now i have a better and cleaner solution but not published yet.
Hope it helps.
I'm writing a vignette for one of my packages.
In this vignette, I would like to demonstrate how this package can interact with other packages that are not being imported by the NAMESPACE or by the Imports section of the DESCRIPTION file.
So, I'm putting a require call to use these external packages in my vignette, but of course I got the following NOTE when I try to R CMD check the package:
* checking for unstated dependencies in vignettes ... NOTE
‘library’ or ‘require’ call not declared from: ‘RColorBrewer’
Is there any way around this, or should I either import these external packages or "fake" the vignette using eval=FALSE?
Put it in Suggests: of your DESCRIPTION file.
From p. 6 of the R extensions manual:
The ‘Suggests’ field uses the same syntax as ‘Depends’ and lists
packages that are not necessarily needed. This includes packages used
only in examples, tests or vignettes (see Section 1.4 [Writing package
vignettes], page 26), and packages loaded in the body of functions.
E.g., suppose an example from package foo uses a dataset from package
bar. Then it is not necessary to have bar use foo unless one wants to
execute all the examples/tests/vignettes: it is useful to have bar,
but not necessary. Version requirements can be specified, and will be
used by R CMD check.
In addition if the vignette properly depends on that package, there should be a
% \VignetteDepends{...}
statement in the vignette itself: Sweave, Part II: Package Vignettes, R News 3/2 (Oct. 2003), 21 - 24.
However, your case possibly is a bit different:
I use if (require ("pkgxy")) without % \\VignetteDepends{pkgxy} (Suggests: pkgxy in the DESCRIPTION is needed anyways) for some things I want to show but where I don't want to force the user to have all the suggested pacakges installed. I put a box at the beginning of the vignette where I report which of those packages are available and if a package is not available when the vignette is built, an "pkgxy is needed to do this" text is put into the vignette.
The "introduction" vignette of package hyperSpec is an example (to find out how it actually works, you need not only the .Rnw but also some more definitions).
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:
A definition of NAMESPACE as used by R
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?
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?
It sounds like "require" is no longer to be used, though it doesn't say that. Is this the correct interpretation?
Thanks!
I've written a little on this topic at https://github.com/hadley/devtools/wiki/Namespaces.
To answer your questions:
See Dirk's answer.
Use roxygen2
Now that every package has a namespace there is little reason to use Depends.
require should only be used to load suggested packages
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.
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!
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.