BiocCheck encapsulates Bioconductor package guidelines
and best practices, analyzing packages and reporting three
categories of issues:
R CMD check). This means the package is missing something critical and it cannot be accepted into Bioconductor until the issue is fixed. (
BiocCheckwill continue past a
requirederror, thus it is possible to have more than one, but it will exit with an error code if run from the OS command line.)
R CMD check). We strongly encourage that these issues be fixed. In the weeks leading up to a Bioconductor release we will ask package authors to fix these issues.
R CMD check, though unlike
NOTEs, there is no expectation that they will increase in severity over time.
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) ## ## -h, --help ## Show this help message and exit
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
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.bat on Windows) into the
bin directory of
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
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
R installation, you can, as noted, copy it to any directory
that's in your PATH. For assistance modifying your PATH, see this link
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
BiocCheck but you can safely ignore it.
Can be disabled with
Only run if your package is a software package (as determined by your biocViews), or if package type cannot be determined.
vignettesdirectory exists. (
RECOMMENDthey be removed.
RECOMMENDthat more chunks be evaluated.
--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 errors. (
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
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. All of the following items
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
Maintainer, which consists of:
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.
Calls to native (C or Fortran) code entry points should be registered with R. This is documented in the Writing R Extensions manual.
BiocCheck detects that your package has native code, but no
entry points have been registered, it will
RECOMMEND that you
If the package
codetoolsBioC is installed,
BiocCheck will run it
to see if it has suggestions for the "Imports" section of your package
codetoolsBioC is an experimental package that is not presently
biocLite(). It is available from
our Subversion repository
with the credentials readonly/readonly.
Output of codetoolsBioC is printed to the screen but
does not label it REQUIRED, RECOMMENDED, or CONSIDER.
At present, this just looks to see whether your package has a
dependency on the
multicore package, and if so,
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.
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.
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:
FALSE. This is because
Fare ordinary variables whose value can be altered, leading to unexpected results, whereas the value of
FALSEcannot be changed.
browser()calls from code. This function 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).
CONSIDERremoving the symbol
<<-from R code; it's generally not a good idea to use it.
RECOMMENDthat you not call
require()on your own package within code in the R directory or in man page examples, because it's not necessary. In these contexts, your package is already loaded.
BiocCheckchecks for direct slot access 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
CONSIDER. 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.
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.
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.
RECOMMENDS that every man page has a non-empty
\value section. Other man page checks may be added in the future.
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
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,
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.
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
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.
It can be handy to generate man page skeletons with
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.
This usually only applies if
BiocCheck is run on the
Bioconductor build machines, because this step requires
If this authorization is present,
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