BiocCheck: Ensuring Bioconductor package guidelines

BiocCheck

BiocCheck encapsulates Bioconductor package guidelines and best practices, analyzing packages and reporting three categories of issues:

Using BiocCheck

BiocCheck is meant to run within R on a directory containing an R package, or a source tarball (.tar.gz file):

library(BiocCheck)
BiocCheck("packageDirOrTarball")

BiocCheck takes options which can be seen by:

suppressPackageStartupMessages(library(BiocCheck))
usage()

Note that the --new-package option is turned on in the package builder attached to the Bioconductor package tracker, since this is almost always used to build new packages that have been submitted.

When should BiocCheck be run

Run BiocCheck after running R CMD check.

Note that BiocCheck is not a replacement for R CMD check; it is complementary. It should be run after R CMD check completes successfully.

BiocCheck can also be run via the Travis-CI (continuous integration) system. This service allows automatic testing of R packages in a controlled build environment.

Simply add the following line to your package's .travis.yml file:

bioc_check: true

Installing BiocCheck

BiocCheck should be installed as follows:

if (!"BiocManager" %in% rownames(installed.packages()))
     install.packages("BiocManager")
BiocManager::install("BiocCheck")

The package loading process attempts to install a script called BiocCheck (BiocCheck.bat on Windows) into the bin directory of your R installation. If it fails to do that (most likely due to insufficient permissions), it will tell you, saying something like:

Failed to copy the "script/BiocCheck" script to
/Library/Frameworks/R.framework/Resources/bin. If you want to be
able to run 'R CMD BiocCheck' you'll need to copy it yourself to a
directory on your PATH, making sure it is executable.  See the
BiocCheck vignette for more information.

You can fix the problem by following these instructions (noting that R may live in a different directory on your system than what is shown above).

If you don't have permission to copy this file to the bin directory of your R installation, you can, as noted, copy it to any directory that's in your PATH. For assistance modifying your PATH, see this link (Windows) or this one (Mac/Unix).

If you manually copy this file to a directory in your PATH that is not your R bin directory, you'll continue to see the above message when (re-)installing BiocCheck but you can safely ignore it.

Interpreting BiocCheck output

Actual BiocCheck output is shown below in bold.

Dependency Checks

Checking Package Dependencies...

Can be disabled with --no-check-dependencies.

Checking if other packages can import this one...

Checking to see if we understand object initialization....

Deprecated Package Checks

Checking for deprecated package usage...

Can be disabled with --no-check-deprecated.

At present, this looks to see whether your package has a dependency on the multicore package (ERROR).

Our recommendation is to use BiocParallel. Note that 'fork' clusters do not rpovide any gain from parallelizing code on Windows. Socket clusters work on all operating systems.

Also checks Deprecated Packages currently specified in release and devel versions of Bioconductor (ERROR).

Remotes Usage Check

Checking for remote package usage...

Can be disabled with --no-check-remotes

Bioconductor only allows dependencies that are hosted on CRAN or Bioconductor. The use of Remotes: in the DESCRIPTION to specify a unique remote location is not allowed.

Version Checks

Can be disabled with --no-check-version-num and --no-check-R-ver.

Checking version number...

For more information on package versions, see the Version Numbering HOWTO.

Package and File Size Check

Can be disabled with --no-check-pkg-size and --no-check-file-size.

It may be necessary to remove large files from your git history; see Remove Large Data Files and Clean Git Tree

biocViews Checks

These can be disabled with the --no-check-bioc-views option, which might be useful when checking non-Bioconductor packages (since biocViews is a concept unique to Bioconductor).

Checking biocViews...

Can be disabled with --no-check-bioc-views

More information about biocViews is available in the Using biocViews HOWTO.

Build System Compatibility Checks

The Bioconductor Build System (BBS) is our nightly build system and it has certain requirements. Packages which don't meet these requirements can be silently skipped by BBS, so it's important to make sure that every package meets the requirements.

Can be disabled with --no-check-bbs

Checking build system compatibility...

A valid Authors@R field consists of: * A valid R object of class person. * Only one person with the cre (creator) role. * That person must have a syntactically valid email address. * That person must have either family or given name defined. * (optional) A syntactically valid ORCID ID, results in note if not.

NAMESPACE checks

Can be disabled with --no-check-namespace

Checking DESCRIPTION/NAMESPACE consistency...

BiocCheck detects packages that are imported in NAMESPACE but not DESCRIPTION, or vice versa, and provides an explanation of how to fix this (ERROR).

Checking for namespace import suggestions...

If the package codetoolsBioC is installed, BiocCheck will run it to see if it has suggestions for the "Imports" section of your package NAMESPACE.

codetoolsBioC is an experimental package that is not presently available via BiocManager::install(). It is available from our Subversion repository with the credentials readonly/readonly. Output of codetoolsBioC is printed to the screen but BiocCheck does not label it ERROR, WARNING, or NOTE.

Vignette Checks

Can be disabled with --no-check-vignettes.

Checking vignette directory...

Only run if your package is a software package (as determined by your biocViews), or if package type cannot be determined.

Checking whether vignette is built with 'R CMD build'...

Only run when --build-output-file is specified.

Analyzes the output of R CMD build to see if vignettes are built. It simply looks for a line that starts:

* creating vignettes ...

If this line is not present, it means R has not detected that a vignette needs to be built (ERROR).

If you have vignette sources yet still get this message, there could be several causes:

See knitr's package vignette page, or the Non-Sweave vignettes section of "Writing R Extensions" for more information.

Checking Install or Update Package Calls in R code

Can be disabled with --no-check-library-calls and --no-check-install-self.

Coding Practices Checks

Can be disabled with --no-check-coding-practices.

Checking coding practices...

Checks to see whether certain programming practices are found in the R directory.

Checking parsed R code in R directory, examples, vignettes...

BiocCheck parses the code in your package's R directory, and in evaluated man page and vignette examples to look for various symbols, which result in issues of varying severity.

Function length checking

Can be disabled with --no-check-function-len.

Checking function lengths...

BiocCheck prints an informative message about the length (in lines) of your five longest functions (this includes functions in your R directory and in evaluated man page and vignette examples).

If there are functions longer than 50 lines, BiocCheck outputs (NOTE). You may want to consider breaking up long functions into smaller ones. This is a basic refactoring technique that results in code that's easier to read, debug, test, reuse, and maintain.

man page checking

Can be disabled with --no-check-man-doc.

Checking man page documentation...

It can be handy to generate man page skeletons with prompt() and/or RStudio. These skeletons contain comments that look like this:

%%  ~~ A concise (1-5 lines) description of the dataset. ~~

BiocCheck asks you to remove such comments (NOTE).

Checking exported objects have runnable examples...

BiocCheck looks at all man pages which document exported objects and lists the ones that don't contain runnable examples (either because there is no examples section or because its examples are tagged with dontrun or donttest). Runnable examples are a key part of literate programming and help ensure that your code does what you say it does.

NEWS checks

Can be disabled with --no-check-news.

Checking package NEWS...

BiocCheck looks to see if there is a valid NEWS file either in the 'inst' directory or in the top-level directory of your package, and checks whether it is properly formatted (NOTE).

The location and format of the NEWS file must be consistent with ?news. Meaning the file can be one of the following four options:

NEWS files are a good way to keep users up-to-date on changes to your package. Excerpts from properly formatted NEWS files will be included in Bioconductor release announcements to tell users what has changed in your package in the last release. In order for this to happen, your NEWS file must be formatted in a specific way; you may want to consider using an inst/NEWS.Rd file instead as the format is more well-defined. Malformatted NEWS file outputs WARNING.

More information on NEWS files is available in the help topic ?news.

Unit Test Checks

Can be disabled with --no-check-unit-tests.

Checking unit tests...

We strongly recommend unit tests, though we do not at present require them. For more on what unit tests are, why they are helpful, and how to implement them, read our Unit Testing HOWTO.

At present we just check to see whether unit tests are present, and if not, urge you to add them (NOTE).

Checking skip_on_bioc() in tests...

Can be disabled with --no-check-skip-bioc-tests.

Finds flag for skipping tests in the bioconductor environment (NOTE)

Formatting checks

Can be disabled with --no-check-formatting.

Checking formatting of DESCRIPTION, NAMESPACE, man pages, R source, and vignette source...

There is no 100% correct way to format code. These checks adhere to the Bioconductor Style Guide (NOTE).

We think it's important to avoid very long lines in code. Note that some text editors do not wrap text automatically, requiring horizontal scrolling in order to read it. Also note that R syntax is very flexible and whitespace can be inserted almost anywhere in an expression, making it easy to break up long lines.

These checks are run against not just R code, but the DESCRIPTION and NAMESPACE files as well as man pages and vignette source files. All of these files allow long lines to be broken up.

The output of this check includes the first 6 offending lines of code; see more with BiocCheck:::checkFormatting("path/to/YourPackage", nlines=Inf).

There are several helpful packages that can be used for formatting of R code to particular coding standards such as formatR and styler as well as the "Reformat code" button in RStudio Desktop. Each solution has its advantages, though styler works with roxygen2 examples and is actively maintained. You can re-format your code using styler as shown below:

## Install styler if necessary
if (!requireNamespace("styler", quietly = TRUE)) {
    install.packages("styler")
}
## Automatically re-format the R code in your package
styler::style_pkg(transformers = styler::tidyverse_style(indent_by = 4))

If you are working with RStudio Desktop use also the "Reformat code" button which will help you break long lines of code. Alternatively, use formatR, though beware that it can break valid R code involving both types of quotation marks (" and ') and does not support re-formatting roxygen2 examples. In general, it is best to version control your code before applying any automatic re-formatting solutions and implement unit tests to verify that your code runs as intended after you re-format your code.

Duplication checks

bioc-devel Subscription Check

Checking for bioc-devel mailing list subscription...

This only applies if BiocCheck is run on the Bioconductor build machines, because this step requires special authorization. This can be disabled with the --no-check-bioc-help option.

All maintainers must subscribe to the bioc-devel mailing list, with the email address used in the DESCRIPTION file. You can subscribe here.

Support Site Registration Check

Checking for support site registration...

The main place people ask questions about Bioconductor packages is the support site. Please register and then optionally include your (lowercased) package name in the list of watched tags. When a question is asked and tagged with your package name, you'll get an email. (If you don't add your package to the list of watched tags, this will be automatically done for you).

BiocCheckGitClone

BiocCheckGitClone provides a few additional Bioconductor package checks that can only should be run on a open source directory (raw git clone) NOT a tarball. Reporting similarly in three categories as discussed above:

Using BiocCheckGitClone

BiocCheckGitClone is meant to run within R on a directory containing an R package:

library(BiocCheck)
BiocCheckGitClone("packageDir")

Installing BiocCheckGitClone

Please see previous Installing BiocCheck section.

Interpreting BiocCheckGitClone output

Actual BiocCheckGitClone output is shown below in bold.

Bad File Check

Checking valid files

There are a number of files that should not be git tracked. This check notifies if any of these files are present (ERROR)

The current list of files checked is as follows:

    hidden_file_ext = c(".renviron", ".rprofile", ".rproj", ".rproj.user",
               ".rhistory", ".rapp.history",
               ".o", ".sl", ".so", ".dylib",
               ".a", ".dll", ".def",
               ".ds_store", "unsrturl.bst",
               ".log", ".aux",
               ".backups", ".cproject", ".directory",
               ".dropbox", ".exrc", ".gdb.history",
               ".gitattributes", ".gitmodules",
               ".hgtags",
               ".project", ".seed", ".settings", ".tm_properties")

These files may be included in your personal directories but should be added to a .gitignore file so they are not git tracked.

Description Check

Checking DESCRIPTION

Default R CMD build behavior will format the DESCRIPTION file; After this occurs, it is hard to determine certain aspects of the original DESCRIPTION file. An example would be how the Authors and Maintainers are specified. The DESCRIPTION file is therefore checked in its raw original form.

CITATION checks

Checking that CITATION file is correctly formatted

BiocCheck tries to read the provided CITATION file (i.e. not the one automatically generated by each package) with readCitationFile() - this is
expected to be in the INST folder (NOTE). readCitationFile() needs to work properly without the package being installed. Most common causes of failure occur when trying to use helper functions like packageVersion() or packageDate() instead of using meta$Version or meta$Date. See R documentation for more information.

Expanding BiocCheck

Contributions to BiocCheck are welcome and encouraged through pull requests. Please adhere to the Pull Request template when submitting your contributions.

SessionInfo {-}

sessionInfo()


Try the BiocCheck package in your browser

Any scripts or data that you put into this service are public.

BiocCheck documentation built on Nov. 8, 2020, 5:38 p.m.