2.1 InstallingR

We recommend using the current ‘release’ version ofR.Followinstructions for installingR.

2.2 InstallingBiocManager

Use standardR installation procedures to install theBiocManager package. This command is required only once perRinstallation.

install.packages("BiocManager", repos = "https://cloud.r-project.org")

2.3 InstallingBioconductor,CRAN, or GitHub packages

InstallBioconductor (or CRAN) packages with

BiocManager::install(c("GenomicRanges", "Organism.dplyr"))

Installed packages can be updated to their current version with

BiocManager::install()

2.4 Previous releases

To install CRAN package versions consistent with previous releases ofBioconductor, use theBiocArchive package. BiocArchive enablescontemporary installations of CRAN packages with out-of-dateBioconductorreleases usingPosit Public Package Manager.

2.5 Version and validity of installations

Useversion() to discover the version ofBioconductor currently inuse.

BiocManager::version()

Bioconductor packages work best when they are all from the same release. Usevalid() to identify packages that are out-of-date or from unexpectedversions.

BiocManager::valid()

valid() returns an object that can be queried for detailedinformation about invalid packages, as illustrated in the followingscreen 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 LibPathbit "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 Repositorybit "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">

2.6 Available packages

Packages available for your version ofBioconductor can bediscovered withavailable(); the first argument can be used tofilter package names based on a regular expression, e.g., ‘BSgenome’package available forHomo sapiens

avail <- BiocManager::available()length(avail)                               # all CRAN & Bioconductor packagesBiocManager::available("BSgenome.Hsapiens") # BSgenome.Hsapiens.* packages

Questions about installing and managingBioconductor packages shouldbe addressed to theBioconductor support site.

2.7 Updating old packages

The user can often get an update packages prompt similar to:

> BiocManager::install("AnVIL")Bioconductor version 3.18 (BiocManager 1.30.22), R 4.3.1 (2023-06-16)Old packages: 'AnnotationDbi', 'arrow', 'basilisk.utils', 'beachmat',  'BiocParallel', 'BiocSingular', 'biocthis', 'Biostrings', 'bluster',  'DelayedArray', 'downlit', 'edgeR', 'GenomeInfoDb', 'GenomicFeatures',  'IRanges', 'limma', 'pkgbuild', 'pkgload', 'processx', 'RcppSpdlog', 'rhdf5',  'rstudioapi', 'SingleR', 'testthat', 'usethis', 'xml2', 'KernSmooth',  'Matrix', 'mgcv'Update all/some/none? [a/s/n]:

A decision should be made regarding updating packages. In the following sectionwe will detail the rationale, pros, and cons of updating packages.

(An initial draft of this section was produced by ChatGPT on 28 August 2023)

2.8 Archived CRAN packages

In the event that a package is no longer available on CRAN, it may bedesirable to install an archived package, especially if it is assumed that thepackage will return to an unarchived state at a later date. Users who wish toprotect their systems from the consequences of these state changes caninstall archived packages by using theCRANhaven repository. This repositorycontains archived versions of CRAN packages for up to five weeks or untilthey are unarchived on CRAN. To enable archived CRAN package installations, theuser can run the following command:

options(    repos = c(        getOption("repos"),        CRANhaven = "https://cranhaven.r-universe.dev"    ))BiocManager::install('archivedPackage')

3.1 Changing version

Use theversion= argument to update all packages to a specificBioconductorversion

BiocManager::install(version="3.7")

Bioconductor versions are associated with specificR versions, assummarizedhere. Attempting to install a version ofBioconductor that is not supported by the version ofR in useleads to an error; using the most recent version ofBioconductor mayrequire installing a new version ofR.

> BiocManager::install(version="3.9")Error: Bioconductor version '3.9' requires R version '3.6'; see  https://bioconductor.org/install

A special version,version="devel", allows use ofBioconductorpackages that are under development.

3.2 UnsupportedR /Bioconductor versions

The main purpose of BiocManager is to ensure that users install theversion ofBioconductor appropriate for their version ofR. Usethe environment variableR_BIOC_VERSION to install any version ofBioconductor on any version ofR. ThusR version 4.3.0 andBioconductor version 3.19 are not compatible…

> BiocManager::install(version = "3.19")Error: Bioconductor version '3.19' requires R version '4.4'; use  `version = '3.18'` with R version 4.3; see  https://bioconductor.org/install

…but the version can be forced with

> Sys.setenv(R_BIOC_VERSION="3.19")> BiocManager::install(version = "3.19")...Bioconductor version 3.19 (BiocManager 1.30.23), R 4.3.0 (2023-04-21)

Note. Compatibility of Bioconductor with a mismatched version of Ris not guaranteed and support is not provided for such installations.

3.3 Managing multiple versions

It is possible to have multiple versions ofBioconductor installed on thesame computer. A best practice is tocreate an initialR installation.Then create and use a library for each version ofBioconductor. The librarywill contain allBioconductor, CRAN, and other packages for that version ofBioconductor. We illustrate the process assuming use ofBioconductorversion 3.7, available usingR version 3.5

Create a directory to contain the library (replaceUSER_NAME with your username on Windows)

• Linux:~/R/3.5-Bioc-3.7
• macOS:~/Library/R/3.5-Bioc-3.7/library
• Windows:C:\Users\USER_NAME\Documents\R\3.5-Bioc-3.7

Set the environment variableR_LIBS_USER to this directory, and invokeR.Command line examples for Linux are

• Linux:R_LIBS_USER=~/R/3.5-Bioc-3.7 R
• macOS:R_LIBS_USER=~/Library/R/3.5-Bioc-3.7/library R
• Windows:cmd /C "set R_LIBS_USER=C:\Users\USER_NAME\Documents\R\3.5-Bioc-3.7 && R"

Once inR, confirm that the version-specific library path has been set

.libPaths()

On Linux and macOS, create a bash alias to save typing, e.g.,

• Linux:alias Bioc3.7='R_LIBS_USER=~/R/3.5-Bioc-3.7 R'
• macOS:alias Bioc3.7='R_LIBS_USER=~/Library/R/3.5-Bioc-3.7/library R'

Invoke these from the command line asBioc3.7.

On Windows, create a shortcut. Go to My Computer and navigate to a directorythat 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, typeBioc-3.7.

3.4 Offline use

Offline use ofBiocManager is possible for organizations and users that wouldlike to provide access to internal repositories ofBioconductor packageswhile enforcing appropriate version checks between Bioconductor and R.For offline use, organizations and users require the following steps:

1. Usersync to create local repositories ofCRAN andBioconductor. TellR 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 ofrepositories().

2. Create an environment variable or option, e.g.,

   options(    BIOCONDUCTOR_ONLINE_VERSION_DIAGNOSIS = FALSE)

3. Useinstall.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")).

```roptions(    BIOCONDUCTOR_CONFIG_FILE = "file:///path/to/config.yaml")```

5.1 Package not available

(An initial draft of this section was produced by ChatGPT on 25 May 2023)

A user failed to install the ‘celldex’ package on 25 May 2023. Atranscript of theR session is as follows:

> BiocManager::version()[1] '3.18'> BiocManager::install("celldex")Bioconductor version 3.18 (BiocManager 1.30.20), R 4.3.0 Patched (2023-05-01  r84362)Installing package(s) 'celldex'Warning message:package 'celldex' is not available for Bioconductor version '3.18'A version of this package for your version of R might be available elsewhere,see the ideas athttps://cran.r-project.org/doc/manuals/r-patched/R-admin.html#Installing-packages

The availability of specific packages withinBioconductor can dependon various factors, including simple errors in entering the packagename, the package’s development status, maintenance, and compatibilitywith the latest version ofBioconductor, as well as the availabilityof CRAN packages that theBioconductor package depends on.

Package Name:R package names are case sensitive and must be speltcorrectly, so usingBiocManager::install("Celldex") (with a capitalC) orBiocManager::install("celdex") (with only onel) wouldboth fail to installcelldex;R will sometimes suggest the correctname.

CRAN Packages:BiocManager::install() tries to install packagesfrom CRAN and fromBioconductor. Check that the package is not a CRANpackage by trying to visit the CRAN ‘landing page’

• https://cran.R-project.org/package=celldex

If this page is found, then the package is a CRAN package; see theR-admin manual section on troubleshooting CRAN packageinstallations.

Check also that the package is not a CRAN package that has been‘archived’ and no longer available by trying to visit

• https://cran.R-project.org/src/contrib/Archive/celldex/

If this page exists but the ‘landing page’ does not, this means thatthe package has been removed from CRAN. While it is possible toinstall archived packages, usually the best course of action is toidentify alternative packages to accomplish the task you areinterested in. This is especially true if the ‘Last modified’ date ofthe most recent archived package is more than several months ago.

Compatibility: ABioconductor package must be available for thespecific version ofBioconductor you are using. Try visiting the‘landing page’ of the package for your version ofBioconductor,e.g., forBioconductor version 3.18 and package celldex

• https://bioconductor.org/packages/3.18/celldex

If this landing page does not exist, then the package is not availablefor your version ofBioconductor.

Users may sometimes have an out-of-date version ofR orBioconductor installed; this may be intentional (e.g., to ensurereproducibility of existing analyses) or simply becauseBioconductorhas not yet been updated. Try visiting the current release landingpage

• https://bioconductor.org/packages/release/celldex

If the release landing page exists, and it is not important that youcontinue using the out-of-date version ofBioconductor, considerupdatingR (if necessary) andBioconductor to the current releaseversions using instructions at the top of this document.

Packages recently contributed toBioconductor are added to the‘devel’ branch, whereas most users are configured to use the ‘release’branch. Try visiting the ‘devel’ landing page

• https://bioconductor.org/packages/devel/celldex

If only the devel landing page exists, then consider updating yourinstallation to use the development version ofBioconductor. Notethat the development version is not as stable as the release version,so should not be used for time-critical or ‘production’ analysis.

It may be that the package you are interested in has been removed fromBioconductor. Check this by visiting

• https://bioconductor.org/about/removed-packages/

If the package has been removed, the best course of action is toidentify alternative packages to accomplish the task you areinterested in.

Maintenance and Operating System Availability: A package may beincluded in the release or devel version ofBioconductor, butcurrently unavailable because it requires maintenance. This might beindicated by a red ‘build’ badge as in the image below (details of thebuild problem are available by clicking on the badge). The build errorusually requires that the package maintainer correct an issue withtheir package; the maintainer and email address are listed on thepackage landing page.

A small number ofBioconductor packages are not available on alloperating systems. An orange ‘platforms’ badge indicates this. Clickon the badge to be taken to the ‘Package Archives’ section of thelanding page; BGmix is not supported on Windows, and not available on‘Intel’ macOS because of build-related errors. Consider using analternative operating system if the package is essential to your work

Packages with landing pages from older releases but not available foryour operating system cannot be updated by the maintainer. If thepackage is available in the current release and for your operatingsystem, consider updating to the current release ofBioconductor.

5.2 Cannot loadBiocManager

After updatingR (e.g., fromR version 3.5.x toR version 3.6.xat the time of writing this) and trying to loadBiocManager,Rreplies

Error: .onLoad failed in loadNamespace() for 'BiocManager', details:  call: NULL  error: Bioconductor version '3.8' requires R version '3.5'; see  https://bioconductor.org/install

This problem arises becauseBiocManager uses a second package,BiocVersion, to indicate the version ofBioconductor in use. Inthe original installation,BiocManager had installedBiocVersionappropriate forR version 3.5. With the update, the version ofBioconductor indicated byBiocVersion is no longer valid – you’llneed to updateBiocVersion and allBioconductor packages to themost recent version available for your new version ofR.

The recommended practice is to maintain a separate library for eachR andBioconductor version. So instead of installing packages intoR’s system library (e.g., as ‘administrator’), install only baseRinto the system location. Then use aliases or other approaches tocreateR /Bioconductor version-specific installations. This isdescribed in the section onmaintaining multipleversions ofR andBioconductor.

Alternatively, one could update allBioconductor packages in theprevious installation directory. The problem with this is that theprevious version ofBioconductor is removed, compromising theability to reproduce earlier results. Update allBioconductorpackages in the previous installation directory by removingallversions ofBiocVersion

remove.packages("BiocVersion")  # repeat until all instances removed

Then install the updatedBiocVersion, and update allBioconductorpackages; answer ‘yes’ when you are asked to update a potentiallylarge number ofBioconductor packages.

BiocManager::install()

Confirm that the updatedBioconductor is valid for your version ofR

BiocManager::valid()

5.3 Timeout during package download

Large packages can take a long time to downloaded over poor internetconnects. The BiocManager package sets the time limit to 300 seconds,usingoptions(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 MB

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

5.4 MultipleBiocVersion installations

One potential problem occurs when there are two or more.libPaths(),with more than one BiocVersion package installed. This might occur forinstance if a ‘system administrator’ installed BiocVersion, and then auser installed their own version. In this circumstance, it seemsappropriate to standardize the installation by repeatedly callingremove.packages("BiocVersion") until all versions are removed, andthen installing the desired version.

5.5 Errors determiningBioconductor version

An essential task forBiocManager is to determine that the versionofBioconductor is appropriate for the version ofR. Severalerrors can occur when this task fails.

• Bioconductor version cannot be determined; no internet connection?When theBioconductor version cannot be obtained from the versionmap hosted athttps://bioconductor.org/config.yaml, this error willoccur. It may be a result of poor internet connectivity or offlineuse. See theoffline config.yaml sectionabove.

• Bioconductor version cannot be validated; no internet connection?Usually occurs when the map is unable to be downloaded possibly dueto a missingBIOCONDUCTOR_CONFIG_FILE. For offline use, a copy ofthe configuration file should be downloaded and its address set tothe environment variable or option.

• Bioconductor version map cannot be validated; is it misconfigured?Onrare occasion, the version map hosted athttps://bioconductor.org/config.yaml may be misconfigured. The checkensures that all the version name tags, i.e., out-of-date, release,devel, and future are in the map.

• Bioconductor version cannot be validated; is type inputmis-specified? The type input refers to the version name inputs,mainly release and devel. This error is chiefly due to internallogic and is not due to user error. Please open aGitHubissue.