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.
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 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'm creating an R package that will use a single function from plyr. According to this roxygen2 vignette:
If you are using just a few functions from another package, the
recommended option is to note the package name in the Imports: field
of the DESCRIPTION file and call the function(s) explicitly using ::,
e.g., pkg::fun().
That sounds good. I'm using plyr::ldply() - the full call with :: - so I list plyr in Imports: in my DESCRIPTION file. However, when I use devtools::check() I get this:
* checking dependencies in R code ... NOTE
All declared Imports should be used:
‘plyr’
All declared Imports should be used.
Why do I get this note?
I am able to avoid the note by adding #importFrom dplyr ldply in the file that is using plyr, but then I end but having ldply in my package namespace. Which I do not want, and should not need as I am using plyr::ldply() the single time I use the function.
Any pointers would be appreciated!
(This question might be relevant.)
If ldply() is important for your package's functionality, then you do want it in your package namespace. That is the point of namespace imports. Functions that you need, should be in the package namespace because this is where R will look first for the definition of functions, before then traversing the base namespace and the attached packages. It means that no matter what other packages are loaded or unloaded, attached or unattached, your package will always have access to that function. In such cases, use:
#importFrom plyr ldply
And you can just refer to ldply() without the plyr:: prefix just as if it were another function in your package.
If ldply() is not so important - perhaps it is called only once in a not commonly used function - then, Writing R Extensions 1.5.1 gives the following advice:
If a package only needs a few objects from another package it can use a fully qualified variable reference in the code instead of a formal import. A fully qualified reference to the function f in package foo is of the form foo::f. This is slightly less efficient than a formal import and also loses the advantage of recording all dependencies in the NAMESPACE file (but they still need to be recorded in the DESCRIPTION file). Evaluating foo::f will cause package foo to be loaded, but not attached, if it was not loaded already—this can be an advantage in delaying the loading of a rarely used package.
(I think this advice is actually a little outdated because it is implying more separation between DESCRIPTION and NAMESPACE than currently exists.) It implies you should use #import plyr and refer to the function as plyr::ldply(). But in reality, it's actually suggesting something like putting plyr in the Suggests field of DESCRIPTION, which isn't exactly accommodated by roxygen2 markup nor exactly compliant with R CMD check.
In sum, the official line is that Hadley's advice (which you are quoting) is only preferred for rarely used functions from rarely used packages (and/or packages that take a considerable amount of time to load). Otherwise, just do #importFrom like WRE advises:
Using importFrom selectively rather than import is good practice and recommended notably when importing from packages with more than a dozen exports.
Title should be pretty clear I hope. I'm writing a package called forecasting, with imports for dplyr among other packages. With the imports written in to the DESCRIPTION file, I am able to force these other packages to be installed along with forecasting - is there an equivalent way to do this for the loading of the package? In other words, is there a way that when I load my package with library(forecasting), it automatically also loads dplyr and the other packages?
Thanks
Yes.
Re-read "Writing R Extensions". The Depends: forces both the initial installation as well as the loading of the depended-upon packages.
But these days you want Imports: along with importFrom() in the NAMESPACE file which is more fine-grained.
But first things first: get it working with Depends.
Edit:
Opps you're correct, the documentation I referenced is not a primary source. Perhaps this is better:
From the R documentation:
The ‘Depends’ field gives a comma-separated list of package names which this package depends on. Those packages will be attached before the current package when library or require is called.
and
The ‘Imports’ field lists packages whose namespaces are imported from (as specified in the NAMESPACE file) but which do not need to be attached. Namespaces accessed by the ‘::’ and ‘:::’ operators must be listed here, or in ‘Suggests’ or ‘Enhances’
Original:
From the R packages documentation:
Adding a package dependency here [the DESCRIPTION file] ensures that it’ll be installed. However, it does not mean that it will be attached along with your package (i.e., library(x)). The best practice is to explicitly refer to external functions using the syntax package::function(). This makes it very easy to identify which functions live outside of your package. This is especially useful when you read your code in the future.
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.