9 Package Checks & Maintenance

9.1 The R CMD check

One of the major benefits of implementing research workflows with R packages is the R CMD check. R CMD check automatically parses your package files for common issues and errors. R CMD check was traditionally ran in the terminal, however, the current best practice is to execute R CMD check with devtools::check(). If you’re using RStudio the simplest way is to use the Check button in the Build tab interface. This will run devtools::check() for you.

The RStudio Build tab and check button.

(#fig:RStudio build check)The RStudio Build tab and check button.

9.1.1 Relevent to Researchers

The build check carries out more than 50 tests across a variety of key areas. Please refer to Hadley Wickham’s Chapter on Automated Checking(Wickham and Bryan 2020a) for detailed descriptions of the default RStudio build checks. Some of the most relevant checks and sources of errors for researchers include:

  • Basic metadata and your session info (OS, directory, R version, etc.)
  • The package structure, directory organization, file names, files in the root directory (top-level files), and file permissions.
  • Checking for a valid DESCRIPTION file including encoding, license, listed authors, and package imports/suggests.
  • A valid NAMESPACE, although this is automatically generated by roxygen2 and should not trigger issues.
  • Checking the code in the R/ for several issues including existence of non-ASCII characters (a real pain if it fails), ensuring packages used are declared in your DESCRIPTION imports/suggests, and syntax.
  • Structure and contents of the Data/ folder. It’s rare to have data errors if they are embedded with usethis::use_data(). The most common source of data errors are non-ASCII characters for symbols or international characters common in country names. These can be a real pain to track down and fix.
  • Checking package and function documentation. This is a common source of errors and warnings:
    • Open brackets when using \describe{} and \item{} environments.
    • Improper use of \link{} and \code{}.
    • You set up the function documentation fine, but you since changed/removed/added certain arguments and forgot to update the roxygen2 header.
  • Checking your vignettes. This is another of the most common sources for errors when using packages primarily for research.

Vignettes may contain CPU intensive code that takes hours or days to compile. In this scenario you may want to remove vignette compilation from the basic RStudio build check. To do so, select Tools > Project Options..., under the GUI select the Build Tools tab, and under Build Source Package -- R CMD build additional options: type --no-build-vignettes.

The RStudio Build Tools interface.

(#fig:no vignettes )The RStudio Build Tools interface.

Now package vignettes will not be checked when running an RStudio package check. This saves time and frustrations, however, unless individual package vignettes are regularly compiled to outputs, underlying issues may go unnoticed. Changes to package functions and embedded package data, changes to external packages the workflow relies on, and changes to APIs or file locations for automatically acquired data might unknowingly disrupt the workflow and cause vignettes to fail when compiling.

9.2 Dealing With Package Checks

Although R CMD check and devtools::check() are helpful tools to ensure proper package structure, function documentation, code syntax, and research vignettes, they are designed primarily for developers intending to submit their package to The Comprehensive R Archive Network (CRAN). Subsequently, CRAN’s requirements are dogmatic and do not always play nice with custom research packages. This may result in an annoying number of Notes, Warnings, or Errors while running package checks.

Notes may be ignored (there will be dozens if the package depends on data.table), but Warnings and Errors should be addressed. This process can be time consuming if not performed regularly. Address each error as they arise, then run the build check again, fix the next error or warning, and repeat until the build check passes. Most warning and error messages are obvious fixes informing the user that there are open roxygen brackets in a specific file, a package used in a vignette or function is not listed in the Imports or Suggests section of the DESCRIPTION. More cryptic build check fail messages can usually be solved after a Google search. To this point, I have been able to fix every build check fail my packages have induced as a result of some odd structure or use case I’ve implemented to fulfill a research objective. That being said, you don’t have to drive yourself crazy. If your functions work, your data is embedded, your documentation is in order, and your vignettes compile, you don’t have to drive yourself crazy attempting to pass a build check. Your package will still install and be distributable to colleagues.

References

Wickham, Hadley, and Jennifer Bryan. 2020a. R Packages. 2nd ed. https://r-pkgs.org/.