BiocCheck encapsulates Bioconductor package guidelines and best practices, analyzing packages and reporting three categories of issues:
BiocCheckwill continue past an
ERROR, thus it is possible to have more than one, but it will exit with an error code if run from the OS command line.)
Most commonly you will use BiocCheck from your operating system command line, as
R CMD BiocCheck package
package is either a directory containing an R package, or a source tarball (.tar.gz file).
BiocCheck can also be run interactively:
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) ## ## --build-output-file=BUILD-OUTPUT-FILE ## file containing output of R CMD build, for optional additional analysis ## ## -h, --help ## Show this help message and exit
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.
BiocCheck after running
R CMD check.
BiocCheck is not a replacement for
R CMD check; it is complementary. It should be run after
R CMD check completes successfully.
BiocCheck should be installed as follows:
source("https://bioconductor.org/biocLite.R") biocLite("BiocCheck") library(BiocCheck)
The package loading process attempts to install a script called
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.
BiocCheck output is shown below in bold.
Checking if other packages can import this one…
Checking to see if we understand object initialization….
Reports if it can’t figure out how objects were initialized (
Can be disabled with
Checking vignette directory…
Only run if your package is a software package (as determined by your biocViews), or if package type cannot be determined.
vignettesdirectory exists (
vignettesdirectory only contains vignette sources (.Rmd, .Rnw, .Rrst, .Rhtml, *.Rtex) (
eval=FALSEchunks is more than 50% of the total (
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 (
If you have vignette sources yet still get this message, there could be several causes:
VignetteBuilderline in the
VignetteEngineline in the vignette source.
--new-packageoption is supplied (
Depends:field of your
BiocCheckchecks to make sure that the R version specified matches the version currently used by Bioconductor. This prevents the package from being used in earlier versions of R, which is not recommended and is a frequent cause of user confusion (
Version:field in your
DESCRIPTIONfile. If it doesn’t, it usually means you did not build the tarball with
R CMD build. (
For more information on package versions, see the Version Numbering HOWTO.
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).
biocViewsfield is present in the DESCRIPTION file (
biocViewsto automatically suggest some biocViews for your package.
More information about biocViews is available in the Using biocViews HOWTO.
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.
Checking build system compatibility…
Packagefield of DESCRIPTION file matches directory or tarball name (
Versionfield is present in the DESCRIPTION file (
Maintainerfield, or a valid
Authors@Rfield which resolves to 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.
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 (
Checking native routine registration…
Calls to native (C or Fortran) code entry points should be registered with R; see Writing R Extensions (
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
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 ERROR, WARNING, or NOTE.
Checking for deprecated package usage…
At present, this looks to see whether your package has a dependency on the
multicore package (
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.
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.
Checking parsed R code in R directory, examples, vignettes…
FALSE. This is because
Fare ordinary variables whose value can be altered, leading to unexpected results, whereas the value of
FALSEcannot be changed (
browser()causes the command-line R debugger to be invoked, and should not be used in production code (though it’s OK to wrap such calls in a conditional that evaluates to TRUE if some debugging option is set) (
<<-is bad practice. It can over-write user-defined symbols, and introduces non-linear paths of evaluation that are difficult to debug (
ERROR) It is not necessary to call
require()on your own package within code in the R directory or in man page examples. In these contexts, your package is already loaded.
BiocCheckchecks for direct slot access (via
slot()) to S4 objects in vignette and example code. This code should always use accessors to interact with S4 classes. Since you may be using S4 classes (which don’t provide accessors) from another package, the severity is only
NOTE. But if the S4 object is defined in your package, it’s mandatory to write accessors for it and to use them (instead of direct slot access) in all vignette and example code (
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 (
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).
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, reuse, and maintain.
Checking man pages…
Every man page must have a non-empty
\value section. (
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
donttest). Runnable examples are a key part of literate programming and help ensure that your code does what you say it does.
BiocChecklists the missing ones and asks you to add runnable examples to them (
Checking package NEWS…
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. 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.
More information on NEWS files is available in the help topic
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 (
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.
Checking for canned comments in man pages…
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 (
A package with the same name (case differences are ignored) cannot exist in CRAN (
ERROR). * Checking if new package already exists in Bioconductor… Only run if the
--new-package flag is turned on. A package with the same name (case differences are ignored) cannot exist in Bioconductor (
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.
All maintainers must subscribe to the bioc-devel mailing list, with the email address used in the DESCRIPTION file. You can subscribe here.
Checking for support site registration…
Maintainerfield of their package
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).