Use the BiocManager package to install and manage packages from the Bioconductor project for the statistical analysis and comprehension of high-throughput genomic data.
Current Bioconductor packages are available on a ‘release’ version intended for every-day use, and a ‘devel’ version where new features are introduced. A new release version is created every six months. Using the BiocManager package helps users install packages from the same release.
Use standard R installation procedures to install the BiocManager package. This command is requried only once per R installation.
chooseCRANmirror()
install.packages("BiocManager")Install Bioconductor (or CRAN) packages with
BiocManager::install(c("GenomicRanges", "Organism.dplyr"))Installed packages can be updated to their current version with
BiocManager::install()CRAN packages for out-of-date Bioconductor releases can be installed from the Microsoft R Application Network or RStudio Package Manager; see ?BiocManager.snapshot to change this behavior.
Use version() to discover the version of Bioconductor currently in use.
BiocManager::version()Bioconductor packages work best when they are all from the same release. Use valid() to identify packages that are out-of-date or from unexpected versions.
BiocManager::valid()valid() returns an object that can be queried for detailed information about invalid packages, as illustrated in the following screen capture
> v <- valid()
Warning message:
6 packages out-of-date; 0 packages too new
> names(v)
[1] "out_of_date" "too_new"
> head(v$out_of_date, 2)
Package LibPath
bit "bit" "/home/mtmorgan/R/x86_64-pc-linux-gnu-library/3.5-Bioc-3.8"
ff "ff" "/home/mtmorgan/R/x86_64-pc-linux-gnu-library/3.5-Bioc-3.8"
Installed Built ReposVer Repository
bit "1.1-12" "3.5.0" "1.1-13" "https://cloud.r-project.org/src/contrib"
ff "2.2-13" "3.5.0" "2.2-14" "https://cloud.r-project.org/src/contrib"
>Packages available for your version of Bioconductor can be discovered with available(); the first argument can be used to filter package names based on a regular expression, e.g., ‘BSgenome’ package available for Homo sapiens
avail <- BiocManager::available()
length(avail) # all CRAN & Bioconductor packages
BiocManager::available("BSgenome.Hsapiens") # BSgenome.Hsapiens.* packagesQuestions about installing and managing Bioconductor packages should be addressed to the Bioconductor support site.
After updating R (e.g., from R version 3.5.x to R version 3.6.x at the time of writing this) and trying to load BiocManager, R replies
Error: .onLoad failed in loadNamespace() for 'BiocManager', details:
call: NULL
error: Bioconductor version '3.8' requires R version '3.5'; see
https://bioconductor.org/installThis problem arises because BiocManager uses a second package, BiocVersion, to indicate the version of Bioconductor in use. In the original installation, BiocManager had installed BiocVersion appropriate for R version 3.5. With the update, the version of Bioconductor indicated by BiocVersion is no longer valid – you’ll need to update BiocVersion and all Bioconductor packages to the most recent version available for your new version of R.
The recommended practice is to maintain a separate library for each R and Bioconductor version. So instead of installing packages into R’s system library (e.g., as ‘administrator’), install only base R into the system location. Then use aliases or other approaches to create R / Bioconductor version-specific installations. This is described in the section on maintaining multiple versions of R and Bioconductor.
Alternatively, one could update all Bioconductor packages in the previous installation directory. The problem with this is that the previous version of Bioconductor is removed, compromising the ability to reproduce earlier results. Update all Bioconductor packages in the previous installation directory by removing all versions of BiocVersion
remove.packages("BiocVersion") # repeat until all instances removedThen install the updated BiocVersion, and update all Bioconductor packages; answer ‘yes’ when you are asked to update a potentially large number of Bioconductor packages.
BiocManager::install()Confirm that the updated Bioconductor is valid for your version of R
BiocManager::valid()Large packages can take a long time to downloaded over poor internet connects. The BiocManager package sets the time limit to 300 seconds, using options(timeout = 300). Only part of a package may download, e.g., only 15.1 of 79.4 MB in the example below
trying URL 'https://bioconductor.org/packages/3.12/data/annotation/src/contrib/org.Hs.eg.db_3.12.0.tar.gz'
Content type 'application/x-gzip' length 83225518 bytes (79.4 MB)
=========
downloaded 15.1 MBor perhaps with a warning (often difficult to see in the output)
Error in download.file(url, destfile, method, mode = "wb", ...) :
...
...: Timeout of 300 seconds was reached
...Try increasing the download timeout, e.g, options(timeout = 600).
Use the version= argument to update all packages to a specific Bioconductor version
BiocManager::install(version="3.7")Bioconductor versions are associated with specific R versions, as summarized here. Attempting to install a version of Bioconductor that is not supported by the version of R in use leads to an error; using the most recent version of Bioconductor may require installing a new version of R.
> BiocManager::install(version="3.9")
Error: Bioconductor version '3.9' requires R version '3.6'; see
https://bioconductor.org/installA special version, version="devel", allows use of Bioconductor packages that are under development.
It is possible to have multiple versions of Bioconductor installed on the same computer. A best practice is to create an initial R installation. Then create and use a library for each version of Bioconductor. The library will contain all Bioconductor, CRAN, and other packages for that version of Bioconductor. We illustrate the process assuming use of Bioconductor version 3.7, available using R version 3.5
Create a directory to contain the library (replace USER_NAME with your user name on Windows)
~/R/3.5-Bioc-3.7~/Library/R/3.5-Bioc-3.7/libraryC:\Users\USER_NAME\Documents\R\3.5-Bioc-3.7Set the environment variable R_LIBS_USER to this directory, and invoke R. Command line examples for Linux are
R_LIBS_USER=~/R/3.5-Bioc-3.7 RR_LIBS_USER=~/Library/R/3.5-Bioc-3.7/library Rcmd /C "set R_LIBS_USER=C:\Users\USER_NAME\Documents\R\3.5-Bioc-3.7 && R"Once in R, confirm that the version-specific library path has been set
.libPaths()On Linux and macOS, create a bash alias to save typing, e.g.,
alias Bioc3.7='R_LIBS_USER=~/R/3.5-Bioc-3.7 R'alias Bioc3.7='R_LIBS_USER=~/Library/R/3.5-Bioc-3.7/library R'Invoke these from the command line as Bioc3.7.
On Windows, create a shortcut. Go to My Computer and navigate to a directory that is in your PATH. Then right-click and choose New->Shortcut. In the “type the location of the item” box, put:
cmd /C "set R_LIBS_USER=C:\Users\USER_NAME\Documents\R\3.5-Bioc-3.7 && R"Click “Next”. In the “Type a name for this shortcut” box, type Bioc-3.7.
BiocManager expects to be able to connect to online Bioconductor and CRAN repositories. Off-line use generally requires the following steps.
Use rsync to create local repositories of CRAN and Bioconductor. Tell R about these repositories using (e.g., in a site-wide .Rprofile, see ?.Rprofile).
options(
repos = c(CRAN_mirror = "file:///path/to/CRAN-mirror"),
BioC_mirror = "file:///path/to/Bioc-mirror"
)Validate repository setting by reviewing the output of repositories().
Create an environment variable or option, e.g.,
options(
BIOCONDUCTOR_ONLINE_VERSION_DIAGNOSIS = FALSE
)Use install.packages() to bootstrap the BiocManager installation.
install.package(c("BiocManager", "BiocVersion"))BiocManager can then be used for subsequent installations, e.g., BiocManager::install(c("ggplot2", "GenomicRanges")).
BiocManager also expects to reference an online configuration yaml file for Bioconductor version validation at https://bioconductor.org/config.yaml. With offline use, users are expected to either host this file locally or provide their config.yaml version. The package allows either an environment variable or R-specific option to locate this file, e.g.,
```r
options(
BIOCONDUCTOR_CONFIG_FILE = "file:///path/to/config.yaml"
)
```BiocManager’s job is to make sure that all packages are installed from the same Bioconductor version, using compatible R and CRAN packages. However, R has an annual release cycle, whereas Bioconductor has a twice-yearly release cycle. Also, Bioconductor has a ‘devel’ branch where new packages and features are introduced, and a ‘release’ branch where bug fixes and relative stability are important; CRAN packages do not distinguish between devel and release branches.
In the past, one would install a Bioconductor package by evaluating the command source("https://.../biocLite.R") to read a file from the web. The file contained an installation script that was smart enough to figure out what version of R and Bioconductor were in use or appropriate for the person invoking the script. Sourcing an executable script from the web is an obvious security problem.
Our solution is to use a CRAN package BiocManager, so that users install from pre-configured CRAN mirrors rather than typing in a URL and sourcing from the web.
But how does a CRAN package know what version of Bioconductor is in use? Can we use BiocManager? No, because we don’t have enough control over the version of BiocManager available on CRAN, e.g., everyone using the same version of R would get the same version of BiocManager and hence of Bioconductor. But there are two Bioconductor versions per R version, so that does not work!
BiocManager could write information to a cache on the user disk, but this is not a robust solution for a number of reasons. Is there any other way that R could keep track of version information? Yes, by installing a Bioconductor package (BiocVersion) whose sole purpose is to indicate the version of Bioconductor in use.
By default, BiocManager installs the BiocVersion package corresponding to the most recent released version of Bioconductor for the version of R in use. At the time this section was written, the most recent version of R is R-3.6.1, associated with Bioconductor release version 3.9. Hence on first use of BiocManager::install() we see BiocVersion version 3.9.0 being installed.
> BiocManager::install()
Bioconductor version 3.9 (BiocManager 1.30.4), R 3.6.1 Patched (2019-07-06
r76792)
Installing package(s) 'BiocVersion'
trying URL 'https://bioconductor.org/packages/3.9/bioc/src/contrib/\
BiocVersion_3.9.0.tar.gz'
...Requesting a specific version of Bioconductor updates, if possible, the BiocVersion package.
> ## 3.10 is available for R-3.6
> BiocManager::install(version="3.10")
Upgrade 3 packages to Bioconductor version '3.10'? [y/n]: y
Bioconductor version 3.10 (BiocManager 1.30.4), R 3.6.1 Patched (2019-07-06
r76792)
Installing package(s) 'BiocVersion'
trying URL 'https://bioconductor.org/packages/3.10/bioc/src/contrib/\
BiocVersion_3.10.1.tar.gz'
...
> ## back down again...
> BiocManager::install(version="3.9")
Downgrade 3 packages to Bioconductor version '3.9'? [y/n]: y
Bioconductor version 3.9 (BiocManager 1.30.4), R 3.6.1 Patched (2019-07-06
r76792)
Installing package(s) 'BiocVersion'
trying URL 'https://bioconductor.org/packages/3.9/bioc/src/contrib/\
BiocVersion_3.9.0.tar.gz'
...Answering n to the prompt to up- or downgrade packages leaves the installation unchanged, since this would immediately create an inconsistent installation.
One potential problem occurs when there are two or more .libPaths(), with more than one BiocVersion package installed. This might occur for instance if a ‘system administrator’ installed BiocVersion, and then a user installed their own version. In this circumstance, it seems appropriate to standardize the installation by repeatedly calling remove.packages("BiocVersion") until all versions are removed, and then installing the desired version.
sessionInfo()sessionInfo()## R version 4.1.0 beta (2021-05-10 r80280)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.10
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## loaded via a namespace (and not attached):
## [1] compiler_4.1.0 magrittr_1.5 htmltools_0.5.0 tools_4.1.0
## [5] yaml_2.2.1 stringi_1.5.3 rmarkdown_2.3 knitr_1.30
## [9] stringr_1.4.0 digest_0.6.25 xfun_0.17 rlang_0.4.7
## [13] evaluate_0.14