R：如何在我的 package 中正确包含库

Question

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, eg aes, ggplot without writing ggplot2::aes or ggplot2::gpplot . So for what are the import statements in each of the config files, ie DESCRIPTION and NAMESPACE?

Answer 1

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:

1. 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.
2. 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.
3. 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() .

Answer 2

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.