Roxygen and suggested packages

Question

I am developing a package with roxygen2, that includes a number of lattice based visualizations. These are nice but not necessary for using the package, and therefore lattice is listed in the Suggests: section of the DESCRIPTION file rather than the Depends: section.

However, I have not yet figured out how to load lattice upon request from the user in a way that pass both roxygenize() and R CMD check. The following two ways both makes lattice look like an unstated dependency and will return the error below.

##' @import lattice
{}

##' Visualization
##'
##' @param x Data.
##' @param y More data.
##' @export
vizz <- function(x, y){
    xyplot(y ~ x)
}

and

##' Visualization
##'
##' @param x Data.
##' @param y More data.
##' @export
vizz <- function(x, y){
    library(lattice)
    xyplot(y ~ x)
}

both gives the same error

$ R CMD check dummy.roxygen

* using log directory ‘/###/dummy.roxygen.Rcheck’
* using R version 3.0.2 (2013-09-25)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* checking for file ‘dummy.roxygen/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘dummy’ version ‘1.0-0’
* package encoding: UTF-8
* checking package namespace information ... OK
* checking package dependencies ... ERROR
Namespace dependencies not required: ‘lattice’

See the information on DESCRIPTION files in the chapter ‘Creating R
packages’ of the ‘Writing R Extensions’ manual.

Since searches on the term "roxygen" combined with "suggests", "depends" and "imports" return a flood of irrelevant hits, I have unsuccessfully been looking for an answer to this for quite some time. Meanwhile I have just listed lattice and a number of other nice but non-vital-packages as dependencies instead, but now when I am about to publish the package I would like to solve it the proper way.

Answer 1

The recommendation used (in 2013 when I first wrote this answer) to be to require in a conditional statement. Now in 2016 the official recommendation is to use :: and let R print the there is no package called X error:

##' Visualization
##'
##' @description Visualize the data. \pkg{\link{lattice}} package required.
##' @param x Data.
##' @param y More data.
##' @seealso \pkg{\link{lattice}}
##' @export
vizz <- function(x, y){
    lattice::xyplot(y ~ x)
}

And only keep Suggests: lattice in your DESCRIPTION (no import in the NAMESPACE).

If you want to customize the error message you can now use requireNamespace(lattice) in a conditional statement, such as:

vizz <- function(x, y){
    if (! requireNamespace("lattice", quietly = TRUE)) {
        stop("Please install lattice: install.packages('lattice')")
    lattice::xyplot(y ~ x)
}

Answer 2

I am not sure what has been causing my problems, but after some debugging with the help of @juba it turns out I had already suggested the correct solution in the question. The proper way to deal with nice-but-not-vital packages is to list them in the Suggests: section of the DESCRIPTION file, and tag them the following way using roxygen.

##' Visualization
##'
##' See \code{\link[lattice]{xyplot}} for details.
##'
##' @param x Data.
##' @param y More data.
##' @export
vizz <- function(x, y){
    library(lattice)
    xyplot(y ~ x)
}

This will not automatically install nor attach lattice upon installing/attaching my package, but simply throw an error if lattice cannot be attached when the function is executed.