Recommended two lines for installing phyloseq (execute from within a fresh R session).
source('http://bioconductor.org/biocLite.R')
biocLite('phyloseq')Check version
packageVersion('phyloseq')## [1] '1.22.3'Alternatively, from a Unix bash terminal (e.g. Linux, Mac) the following one-liner should also work.
Rscript -e "source('http://bioconductor.org/biocLite.R');biocLite('phyloseq')"Try this first. Read below if problems arise.
Note: You must have a connection to the internet for this to work, and that connection must be available to your R session.
The following tutorial contains information for installing the phyloseq package for R. It includes details for navigating the various versions of the package that are available, and how to tackle some of the challenges that may come up depending on your operating system and familiarity with R.
If one of the following methods in this section works with no errors, then you’re done. The phyloseq package has been installed and you can move on to the phyloseq tutorials. If not, see some of the additional troubleshooting recommendations below. Some of the issues might depend on your system. See if you can install all of the required packages ahead of time before attempting to install phyloseq. Lastly, check that the phyloseq version that you have installed matches well with what is shown in the tutorial you want to emulate. Typically the version used in the tutorial is shown at the top of the page. If your package version number is behind and the tutorial does not work as expected for you, please consider installing the latest devel version of phyloseq from GitHub, described below.
Special Note When installing a recent (“devel”) version of the phyloseq package from GitHub or Bioconductor, you may need to “install from source”. Although the commands for doing this are straightforward and shown below, one dependency that is often missed by users is LaTeX2e. For example, Mac users probably want to install the MacTeX distro of LateX2e prior to any attempts at installing phyloseq from GitHub, as described in more detail in Issue 174.
This is the version installed if you executed the recommended two lines above. It will not necessarily have the very latest features and fixes, but the installation should work easily using the biocLite tool. It should install all the necessary dependencies automatically, so these two lines should be all you need to enter in your R session to install the phyloseq package.
source("http://bioconductor.org/biocLite.R")## Bioconductor version 3.6 (BiocInstaller 1.28.0), ?biocLite for helpbiocLite("phyloseq")If it asks to update old packages, you should probably choose option a, to update all packages.
The phyloseq package includes its own installer script, which you can call from its “home” on GitHub. It has a few phyloseq-specific autochecks, and will attempt to install the latest release version of phyloseq by default (same version installed as above). It also temporarily loads a phyloseq installation function, install_phyloseq(), which you can execute with alternative options as shown in later sections.
source("https://raw.githubusercontent.com/joey711/phyloseq/master/inst/scripts/installer.R",
local = TRUE)There are official instructions for using development versions of Bioconductor packages, and these will apply to phyloseq as well as any other package in the BioC-devel repository. However, using their tool, especially the useDevel() command, appears to force you to use development versions of all your Bioconductor packages.
This is overkill if you only want to use the devel version of phyloseq, but not necessarily the devel version of all other packages in Bioconductor. I recommend installing the stable release versions of all the packages on which phyloseq depends, especially the whichever version is explicitly listed in the DESCRIPTION file. This is actually pretty easy.
First let’s follow the previous instructions for installing the stable release version of phyloseq, shown again here. This is an easy way of installing the stable dependencies for phyloseq while also making sure there are no other strange problems. If it works you will already have the stable version of phyloseq installed as well as updated versions of the packages on which it depends, but this section is about installing the latest devel version.
source("https://raw.githubusercontent.com/joey711/phyloseq/master/inst/scripts/installer.R",
local = TRUE)
install_phyloseq(branch = "devel")When executed, the first line called the latest installer script including a default-arguments call of install_phyloseq(), which installs the release version of phyloseq from precompiled binaries for your specific operating system, and any missing or out-of-date dependencies. The second line installed the latest devel version of phyloseq on Bioconductor, by modifying one of the arguments to install_phyloseq()
This version is updated often, sometimes daily, and includes the latest fixes, documentation, and features. If you’ve requested a fix or feature on the phyloseq Issue Tracker, it will show up in this version first, and might be a while before the changes migrate to the official release version. This delay is for stability, testing, and because Bioconductor is on a semi-annual release schedule. This version is a “live” incrementally updated version of the package that we use to save, share, and collaboratively develop the package. For unstable code there are no guarantees. However, we try very hard not to push any changes to the “master” branch (the one that you see by default) that do not meet the same standards as the Bioconductor repository itself. Typically, changes that have not been fully tested will be pushed to a secondary branch or fork, and then merged into “master” only after they have passed the full suite of checks. Thus, in the vast majority of cases you should be able to install from GitHub and get the latest fixes and functionality that will eventually make its way into the Bioconductor release version.
There are many different ways to obtain and install the GitHub version of the phyloseq package.
This is the easiest way to install the latest devel version of phyloseq from GitHub. It will attempt to install the latest master branch of the package. For alternative branches, you can modify the instructions in the devtools installer section (next).
install_phyloseq(branch = "github")The second easiest way is to use the install_github function now included in the R development tools package, called devtools. This is only useful if the install_phyloseq function didn’t work.
Make sure that you have the devtools package installed,
install.packages("devtools")then go ahead and load the devtools package and attempt to install phyloseq with the install_github() function.
library("devtools")
install_github("phyloseq/joey711")We are aware of a transient, but recurring error:
-----------------------------------
ERROR: dependency 'multtest' is not available for package 'phyloseq'
-----------------------------------
In addition: Warning message:
package 'multtest' is not available (for R version 3.*.*)This recurring problem arises when a new version of core R is released – for example version 3.0.0 was released on 2013-04-03 – and any dependencies (see below) have not yet been built under that new version. This will typically create warnings or errors when you attempt to install phyloseq. In most cases this is not the result of the latest R version “breaking” a particular package (that kind of problem is rare); rather, it is most likely an overly cautious versioning check to ensure that the discrepancy does not go unnoticed (or so we guess). Most importantly, it is a transient problem that will fix itself as new “pre-built” versions of the packages are re-built with the latest release version of your core R installation. However, if you do not or cannot wait for that to happen, you will need to install those dependencies from source. Not to fear, it is hopefully not as scary as it sounds, and has the exact same challenges as those discussed in the following sections for installing the phyloseq package from source.
For example, the above warning/error is probably solved by first installing the multtest package from source with the following code (note: it is a Bioconductor package, and you must have an active internet connection)
source("http://bioconductor.org/biocLite.R")
biocLite("multtest", type="source")Similarly, an offending dependency hosted by the CRAN repository could be installed from source with the following code (in this example, the ggplot2 package)
install.packages("ggplot2", type="source")Note that this assumes that you have the necessary system requirements for building a package from source. This is mainly only an issue for Windows users. If the previous install code failed in your R session, do a google search of the error message that you got back. If that doesn’t reveal the solution and you are using Windows, see the section below entitled “Windows Users”.
Dependencies are other R packages that are required for proper functioning of phyloseq. They must be installed with at least a minimum version number specified by phyloseq for installation to work. If something went wrong in your installation of phyloseq, making sure you can actually install the dependencies is probably the best place to start. The following dependency installation code will usually attempt to upgrade your packages to the latest versions as well, potentially fixing a dependency version that is too old to work with the latest phyloseq version.
Installing Bioconductor dependencies is supposed to be painless, and to work the same way as for the “Quick Install” of the release-version of phyloseq above:
source("http://bioconductor.org/biocLite.R")
biocLite("multtest")An explicit way to upgrade your packages using the new Bioconductor package upgrader:
source("http://bioconductor.org/biocLite.R")
biocLite("BiocUpgrade")The Comprehensive R Archive Network (CRAN) is the main repository for publicly available R packages. Most installation procedures will install these dependencies automagicaly from the CRAN repository. However, if you want to install them ahead of time, update, or help identify a troublesome dependency, the following is an example for installing one of the key phyloseq dependencies, the ape package, using the install.packages function.
install.packages("ape")There is no way for us to guarantee or troubleshoot all the possible issues that might arise for Windows users, but here is a short list of key recommendations and resources that might help you get going with phyloseq as soon as possible. These are only really relevant if you’re attempting to install phyloseq from source code. The recommended installation instructions at the very beginning should work for all Windows users for whom Bioconductor successfully installs under their recommended instructions. The biocLite function will auto-detect that your machine is Windows, and attempt to install the pre-compiled binary of phyloseq for Windows.
If you need a devel, bleeding-edge, or modified source-code version of phyloseq, the following tips might be useful.
Windows Users may first need to install the Rtools application, depending on how phyloseq is being installed, as Rtools is necessary to build anything from source on Windows.
Make sure the R and Rtools paths are added in the environment variable.
Here are the official instructions from CRAN for installing R packages on Windows.
For more detailed troubleshooting or system setup for Windows see Appendix D The Windows toolset published by CRAN.
Depending on the problem that you’re having, it might help to download a compressed version of the phyloseq package, and then attempt to install it locally with standard R commands/tools.
In this particular approach to installing the BioC-devel version of phyloseq, we need a specific URL for downloading the package file. We have provided example URLs below, but they may change slightly as package version numbers change. To check the links, go to the phyloseq page for Bioconductor devel branch.
The URLs below are for installing from source (any properly configured system), from a Mac binary (Mac only), or from a Windows binary (Windows only).
Now, using the links we just checked and the temporary system file that we initialized, we will download the package type appropriate for your system, and use the install.packages command that is part of standard R in order to install the just-downloaded package. Remember that you should only use one of the options below, depending on your system. All other things being equal, the binary versions are supposed to install faster and easier than source. If the binary installation doesn’t work, however, try “installing from source” as shown below.
In all three examples, we first have to define a fresh new temporary file where your system will store the downloaded package file. We can simply call this temp, regardless of which system or package type.
For Windows binary install
temp <- tempfile()
windowsURL = "http://bioconductor.org/packages/devel/bioc/bin/windows/contrib/3.0/phyloseq_1.5.3.zip"
download.file(windowsURL, temp)
install.packages(temp, repos=NULL, type="win.binary")For Mac binary install
temp <- tempfile()
macURL = "http://bioconductor.org/packages/devel/bioc/bin/macosx/leopard/contrib/3.0/phyloseq_1.5.3.tgz"
download.file(macURL, temp)
install.packages(temp, repos=NULL, type="mac.binary.leopard")For installing from source
temp <- tempfile()
sourceURL = "http://bioconductor.org/packages/devel/bioc/src/contrib/phyloseq_1.5.3.tar.gz"
download.file(sourceURL, temp)
install.packages(temp, repos=NULL, type="source")The tar.gz “tarball” of the latest package build can be downloaded by clicking this phyloseq tarball link. Both zipball and tarball versions of the repository are also linked from the phyloseq front page.
Note: The file name will have the form joey711-phyloseq-*.tar.gz
The latest stable release of phyloseq on Bioconductor and the latest development release of phyloseq on Bioconductor can be found at these respective links, as well as some interesting phyloseq use data in the form of the number of downloads of the respective versions each month from Bioconductor.
Note: The file name will have the form phyloseq_1.*.tar.gz
The development branch of phyloseq on Bioconductor is updated less often than the GitHub branch, but might contain recently-developed features in phyloseq that have not yet migrated to the release version. This is a good option if you are having problems installing the GitHub version, or have some other reason to use the slower-moving code.
Download the BioC devel branch of phyloseq the devel page for phyloseq on Bioconductor. It should be a link to download a file called something like phyloseq_1.*.*.tar.gz. Alternatively, you can download package binaries for Windows or Mac OS. These might install easier because you won’t need to install “from source”.
From a (BASH) command line, unpack and install (assuming you downloaded the package to the ~/Downloads directory, as an example):
cd ~/Downloads
tar -xvf joey711-phyloseq-*.tar.gz
R CMD install joey711-phyloseq-*(You need to replace the * or complete file name to match what you actually downloaded and unpacked. The final line refers to the directory you just unpacked, not the compressed file.)
Alternatively, you might be able to build from source from within an R session, as mentioned above
install.packages("~/Downloads/joey711-phyloseq-*", repos = NULL, type="source")Make sure you have Rtools installed.
From within an R session, enter:
install.packages("C:/Desktop/joey711-phyloseq-*", repos=NULL, type="source")Where C:/Temp/ represents the full directory path to where you have saved the joey711-phyloseq-*.tar.gz file containing phyloseq.
Command-line (dos) installation (only try if Option 1 fails): - Make sure the R and Rtools paths are added in the environment variable. - Open a dos command prompt and enter the following
R CMD INSTALL joey711-phyloseq-*.tar.gz`.If you want to make modifications to phyloseq on your own fork, and then install from your modified repository, just replace the "joey711" string to your GitHub username (and if you named the repository something other than "phyloseq", change that too). See the advanced instructions above for using the install_github command.