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.
Related
I want to use functions from the expss package in my own functions/packages. I usually call the functions along with their packages (e.g. dplyr::mutate(...)).
The expss package has a function/operator %to%, and I don't know how I can do the same here, i.e. expss::%to% doesn't work, neither does expss::'%to%'.
What can I do?
Infix operators must be attached to be usable; you can’t use them prefixed with the package name.1
Inside a package, the conventional way is to add an importFrom directive to your NAMESPACE file or, if you’re using ‘roxygen2’, add the following Roxygen directive somewhere:
#' #importFrom expss %to%
Outside of package code, you could use ‘box’ to attach just the operator:
box::use(expss[`%to%`])
Or you can use simple assignment (this is the easiest solution in the simplest case but it becomes a lot of distracting code for multiple operators):
`%to%` = expss::`%to%`
1 Except using regular function call syntax:
expss::`%to%`(…)
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.
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.