BiocCheck

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

Using BiocCheck

Most commonly you will use BiocCheck from your operating system command line, as

R CMD BiocCheck package

Where package is either a directory containing an R package, or a source tarball (.tar.gz file).

BiocCheck can also be run interactively:

library(BiocCheck)
BiocCheck("packageDirOrTarball")

R CMD BiocCheck takes options which can be seen by running

R CMD BiocCheck --help
## Usage: R CMD BiocCheck [options] package
## 
## 
## Options:
##  --no-check-vignettes
##      disable vignette checks
## 
##  --new-package
##      enable checks specific to new packages
## 
##  --no-check-bioc-views
##      disable biocViews-specific checks (for non-BioC packages)
## 
##  -h, --help
##      Show this help message and exit

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.

Installing BiocCheck

BiocCheck should be installed as follows:

source("http://bioconductor.org/biocLite.R")
biocLite("BiocCheck")
library(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

Dependency Checks

Vignette Checks

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

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

Version Checks

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

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).

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. All of the following items are REQUIRED.

Unit Test Checks

We strongly believe in 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 CONSIDER adding them.

Native Routine Registration Checks

Calls to native (C or Fortran) code entry points should be registered with R. This is documented in the Writing R Extensions manual.

If BiocCheck detects that your package has native code, but no entry points have been registered, it will RECOMMEND that you register them.

Namespace Import Suggestion Checks

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 biocLite(). 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 REQUIRED, RECOMMENDED, or CONSIDER.

Deprecated Package Checks

At present, this just looks to see whether your package has a dependency on the multicore package, and if so, REQUIREs you to remove it. multicore does not work on Windows, but the parallel package has all of the same functionality and works on all operating systems.

Note that parallel supports two types of parallelism: forking and socket clusters. Forking only works on Windows if the number of cores is set to 1, meaning there is no gain from parallelizing code. Socket clusters work on all operating systems.

Code Parsing Checks

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:

DESCRIPTION/NAMESPACE consistency checks

BiocCheck detects packages that are imported in NAMESPACE but not DESCRIPTION, or vice versa, and RECOMMENDS fixing them, with an explanation of how to do so.

Function length checking

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).

BiocCheck does not assign severity to long functions, but 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, and maintain.

Man Page checking

RECOMMENDS that every man page has a non-empty \value section. Other man page checks may be added in the future.

Runnable Examples Checking

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). It's REQUIRED that at least 80% of these man pages have runnable examples. If more than 80% of these pages have runnable examples, but some are still missing, BiocCheck lists the missing ones and asks you to CONSIDER adding runnable examples to them.

Runnable examples are a key part of literate programming and help ensure that your code does what you say it does.

NEWS checks

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

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.

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

Formatting checks

There is no 100% correct way to format code. There are various style guides, and these checks adhere to Bioconductor's Style Guide.

We ask only that you CONSIDER adhering to this guide.

In particular, 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.

Canned Comments check

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 CONSIDER removing such comments.

bioc-devel Subscription Check

This usually only applies if BiocCheck is run on the Bioconductor build machines, because this step requires special authorization.

If this authorization is present, BiocCheck will check to see if the email address in the Maintainer (or Authors@R) field is subscribed to the bioc-devel mailing list, and if not, REQUIREs that you subscribe. All maintainers must subscribe to this list. You can subscribe here.