Generally, your R package will make use of functions in other R packages. You need to tell R about that, to ensure that those packages are installed when your package is installed, and that they’re made available when your package is loaded.

This gets a little complicated (and boring!), and the procedures have changed over time, and my understanding of R is not always up-to-date. So some of this may not be quite right. (If you find a mistake or want to suggest improvements, please tell me, by submitting an Issue or Pull Request.)

Using functions in other packages

There are several different ways to make use of functions in other packages. You can load the package with library() and then just use the functions. Or you can use the :: operator, for example writing broman::runningmean( ) rather than library(broman) and then runningmean().

The move is towards the latter, where only the necessary functions will be loaded, rather than attaching the whole package.

The :: operator only works for functions that are in the namespace of that other package. Other functions, that weren’t exported, can be used with the ::: operator. But CRAN doesn’t allow the ::: operator. If you want to use functions that aren’t in that other package’s namespace, you need to either get the author to add it, or (if allowable by the package’s license) just incorporate the code directly into your own package.

NAMESPACE file

You don’t really need to use the :: operator, as you can import the namespace of that other package into your own. With Roxygen2, you do this with @import or @importFrom.

A line like

#' @import jsonlite

will add a line to your package’s NAMESPACE file that imports the entire namespace of that other package into your own, so you can use any of its functions without the :: operator.

A line like

#' @importFrom jsonlite toJSON unbox

will add lines to your package’s NAMESPACE file to import just the named functions.

If your package is thoroughly dependent on another package, so that you’re using all sorts of functions from that other package, I’d go ahead and use @import and import the entire namespace of the other package.

If, on the other hand, you’re just using one or two functions, I’d use @importFrom to import just the particular functions.

And probably it’s best to skip the whole @import and @importFrom technique and just use the :: operator, particularly for clarity: jsonlite::unbox( ) makes it clear that unbox is not part of the present package but is part of jsonlite.

Depends, Imports, Suggests, and Enhances

If your package is using functions in other packages, you also need to add some lines to your DESCRIPTION file.

Here’s the DESCRIPTION file for my R/qtlcharts package.

Package: qtlcharts
Version: 0.2-44
Date: 2014-09-08
Title: Interactive graphics for QTL experiments
Author: Karl W Broman <broman@wisc.edu>
Maintainer: Karl W Broman <broman@wisc.edu>
Description: Web-based interactive charts (using D3.js) for the analysis of
    experimental crosses to identify genetic loci (quantitative trait
    loci, QTL) contributing to variation in quantitative traits.
Depends:
    R (>= 2.15),
    qtl (>= 1.30-4)
Imports:
    jsonlite,
    graphics,
    stats,
    utils
Suggests:
    knitr,
    devtools,
    roxygen2,
    testthat
License: MIT + file LICENSE
URL: https://kbroman.org/qtlcharts
VignetteBuilder: knitr

Note the Depends, Imports, and Suggests lines.

• Depends is used to indicate dependency on a particular version of R, and on packages that are to be loaded (with library()) whenever your package is loaded. If you expect that users would want to load that other package whenever they loaded yours, then you should include the package name here. But this is now relatively rare. (I think the namespaces for these packages should also be imported, with @import.)

• Imports is used for packages that are needed by your package but that don’t need to be loaded with library(). Packages referred to in @import or @importFrom statements in your Roxygen2 comments, or whose functions are accessed via the :: operator, should be here.

• Suggests is for packages that aren’t really necessary, but that you’re using in your examples, vignettes, or tests. Any package listed in Imports will need to be installed with your package, while packages listed in Suggests do not need to be installed with your package.

There’s one more: Enhances. But it’s not so common, and I don’t quite understand the point, and so I’ll just say: go read the Package Dependencies section in the Writing R Extensions manual. Or put that off until you think you need to.

A package should appear in just one of these four sections (Depends, Imports, Suggests, and Enhances).

• If you need to attach the package with library(): Depends
• If you use functions from the package (::, @import, or @importFrom) but don’t need to use library(): Imports
• If it’s not used in the code but is used in examples, vignettes, or tests: Suggests
• Otherwise maybe Enhances

You shouldn’t use Depends or Imports if it’s not necessary, as then your package can’t be installed if one of those is not installable. Packages in Suggests don’t need to be available.

Finally, go to the resources page.