This is very simple question.
I am extending someone's package. It currently uses packages A, B and they are listed in the DESCRIPTION file.
If I need functions from package C - to add a package to the dependencies - do I just add the package in the DESCRIPTION file and that is all that is needed? Into what section - Depends or Imports? Are there more other steps to make? Do I need to use prefix C::functionInC() once my code needs to use a package C function?
Short answer:
Add C to Imports: and when using the C functions, use the double semicolon prefix.
Longer context:
The link below provides the following advice
http://r-pkgs.had.co.nz/namespace.html#imports
R functions
If you are using just a few functions from another package, my recommendation 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().
If you are using functions repeatedly, you can avoid :: by importing the function with #importFrom pgk fun. This also has a small performance benefit, because :: adds approximately 5 µs to function evaluation time.
Alternatively, if you are repeatedly using many functions from another package, you can import all of them using #import package. This is the least recommended solution because it makes your code harder to read (you can’t tell where a function is coming from), and if you #import many packages, it increases the chance of conflicting function names.
Related
I'm writing by first R-Package and was wondering what the right way is to include other libraries, like ggplot2.
So there are two places where an import statement can go in my package. The DESCRIPTION file and the NAMESPACE, where the latter requires to include ggplot in some roxagen statement like #'#import ggplot2.
Actually I thought that is is enough to include ggplot2 inside DESCRIPTION, as I thought that loading my packages will also load or dependencies, however, when ggplot2 is not in the namespace it seems like I cannot use function, e.g. aes, ggplot without writing ggplot2::aes or ggplot2::gpplot. So for what are the import statements in each of the config files, i.e. DESCRIPTION and NAMESPACE?
The one required step is to include ggplot2 under Imports: in your DESCRIPTION file. This ensures that ggplot2 is installed when your package is installed.
Then, to use functions from ggplot2 in your package, you need to tell R where to look for them. You can do this in 3 ways:
Put the name of the package before the function name when you use it: ggplot2::aes(). This is my preferred method, as it doesn’t add anything extra to your NAMESPACE, avoids any name collisions, and avoids breakage if you later rework or remove a function.
Import specific functions as you use them. Do this by putting #’ #importFrom ggplot2 aes in the roxygen block above the function using it. Add however many function names you need to that line. After doing that, you can use aes() directly without having to specify the namespace it’s coming from with ggplot2::aes(). This can be convenient if you’re working with a lot of functions (like with ggplot2), but I recommend using the first option instead in general to keep your NAMESPACE tidier. You technically only need to include the #importFrom line for once in your package for any function, but I recommend including it for each function that is using the imported functions. That way, if you ever rework or remove a function, the other functions don’t break.
You can import a whole package of functions by putting #’ #import ggplot2 in a roxygen block. This imports every function from a package. This can be a lot for big packages like ggplot2 and dplyr, and the can potentially cause issues, so I suggest never doing this and instead importing only the specific functions you need or calling them with ggplot2::aes().
If you depend on a package you should put it in the Imports field of the DESCRIPTION file, after which you can use pkgname::function() in your code.
usethis::use_package() function can help you do this.
If you want your code to be able to use any code of the package without the use of ::, you should put a roxygen comment somewhere like this:
#' #import pkgname
NULL
This then gets ported by roxygen2 to your NAMESPACE file.
If you want to specifically use some functions (but not others), you can use the following that is used by roxygen2:
#' #importFrom pkgname fun1 fun2
NULL
The usethis::use_import_from() function can help you do the above. In the examples above NULL only indicates that you're not documentating a function or data, and you can use it at the end of a documentation comment block.
This is very simple question.
I am extending someone's package. It currently uses packages A, B and they are listed in the DESCRIPTION file.
If I need functions from package C - to add a package to the dependencies - do I just add the package in the DESCRIPTION file and that is all that is needed? Into what section - Depends or Imports? Are there more other steps to make? Do I need to use prefix C::functionInC() once my code needs to use a package C function?
Short answer:
Add C to Imports: and when using the C functions, use the double semicolon prefix.
Longer context:
The link below provides the following advice
http://r-pkgs.had.co.nz/namespace.html#imports
R functions
If you are using just a few functions from another package, my recommendation 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().
If you are using functions repeatedly, you can avoid :: by importing the function with #importFrom pgk fun. This also has a small performance benefit, because :: adds approximately 5 µs to function evaluation time.
Alternatively, if you are repeatedly using many functions from another package, you can import all of them using #import package. This is the least recommended solution because it makes your code harder to read (you can’t tell where a function is coming from), and if you #import many packages, it increases the chance of conflicting function names.
Writing an R-package I use name spaces to use functions from existing packages, e.g. raster::writeRaster(...).
However, I am wondering if functions from the base package have also be used like this, e.g. base::sum(...). This might end up in very confusing code parts:
foo[base::which(base::sapply(bar, function())]
No you don't need to reference base packages like this. You only need to reference non-base packages to ensure they are loaded into the function environment when functions from your package are run, either by using :: or #import in the Roxegen notes at the top of your script. See why you don't need to reference base packages below:
http://adv-r.had.co.nz/Environments.html
"Package namespaces keep packages independent. For example, if package A uses the base mean() function, what happens if package B creates its own mean() function? Namespaces ensure that package A continues to use the base mean() function, and that package A is not affected by package B (unless explicitly asked for)."(Hadley Wickham)
The only time you need to reference base:: is if the namespace for your package contains a package that has an alternative function of the same name.
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.
I have two related questions about writing functions in magrittr package & including them in a package.
In normal way of writing a function, you can specify library(package.a) within function call if any of the steps uses a function from package.a. How would you call this in pipe environment (from magrittr)?
This part of the question arose when I tried to package my functions, and a few of my functions use magrittr's way of creating functions. I wasn't able to add those functions to package. Devtools package's combine function didn't recognize %>% pipe. Basically I had to re-write them to normal functions to include them in the package. How do you overcome this?
Update your NAMESPACE file, see 1.5 Package namespaces.
Add import(magrittr), don't forget to add Imports: magrittr in DESCRIPTION file.
Regarding your comment on ::.
While you are importing all magrittr exported function by using import(magrittr) you don't have to use :: operator to point the package.
Of course as long as you did not create a function with the same name in your package which would override the name from imported package, then you do need ::.
Also the :: would be needed if you would used importFrom() instead of import() and you did not import required function - that might be not recommended anyway.
Another case where you may want to use :: is when you use Suggests or Enhances, none of them is in scope of that question anyway.