vignettes/install_main.Rmd
install_main.RmdTime to get those machines in gear, paleontologists!
To actively participate in the Short Course, you will need access to several pieces of software on a personal computer, particularly RevBayes, R, RStudio, Mesquite and Tracer. Please see below for an overview on the software we want you to install, followed by instructions specific to each operating system. In addition to this software, you will need an up-to-date web browser, and a functioning wifi card, in order to access several websites we will use during the workshop. Wifi access will be supplied to participants courtesy of The Paleontological Society.
We require five particular software applications: RevBayes, R, RStudio, Mesquite, and Tracer. We expect that you will have all of these on your computer, but we also understand that through circumstance or personal choice, you may not have all of these. We will try to help you as much as possible, and it would be easiest for you to follow along if you have the software installed as we request. In terms of priority, RevBayes is the most important software to get on your personal computer to participate in the majority of the workshop activities. The next most important piece of software to obtain is R and RStudio. R itself might be called in earlier modules, but will only be the principal player in the last module, on comparative methods. However, as instructors, we will use RStudio throughout the day essentially as a plain-text editor to read RevBayes scripts, formatted like Rmarkdown files. If you cannot install the RStudio IDE, you will need to use an alternative text editor, and use R from the system terminal, or the basic packaged GUI. Mesquite will only be used in the third module, on character coding, and later modules will not depend on these exercises. Tracer will only be used in the module on tip-dating and post-inference analysis (and may be cut for time).
RevBayes is a terminal-based program for Bayesian phylogenetic analysis which gives users greater freedom in defining their own models and priors than previous software, designed around graphical models (Höhna et al. 2016). RevBayes also contains an interpreted, scripted language resembling R, rather than a set of fixed commands. It is a spiritual successor to the program MrBayes, which is still maintained but in static form, with no ongoing active development.
In the week before the workshop, one of us (A. Wright) pushed a number of changes to the RevBayes source and compiled new pre-release versions for our GSA workshop, labeled as release version 1.0.13. In particular, and of significance for us paleontologists, this allows us to load character matrices containing characters that entail differing numbers of character states. Previously, matrices with mixtures of characters with differing numbers of states had to be seperated beforehand to be loaded by RevBayes. If you have an older version of RevBayes from before this week, please update!
RevStudio is an analog of RStudio that allows one to edit, debug and run RevBayes scripts in an IDE environment. However, the latest version of RevBayes does not seem to run on all computers - particular issues that have been reported are that it does not work currently on mac OC computers (and it does not exist at all for Linux, anyway). Do not worry: we will be using RevBayes in the terminal mode (rb) and not relying on RevStudio.
R is a programming language that is especially powerful for data exploration, visualization, and statistical analysis. We will interact with R via RStudio, a popular Integrated Development Environment (IDE) that provides a helpful, beginner friendly experience that allows for easy writing and editing of R scripts. This includes the writing and processing of Rmarkdown files which are regular text documents with interspersed ‘chunks’,that can be converted to PDF or HTML format as dynamic reports. Throughout much of the workshop, we will use the script editing features of RStudio essentially as a plain-text editor, to read and edit scripts for RevBayes.
When you’re done installing R and RStudio, regardless of what operating system you are on, you will need to install several additional packages that contain additional, specialized functions that we will cover in our lessons. R’s versatility greatly comes from its thousands of such specialized packages, written by other users, and submitted to the CRAN repository, and not included in the base installation. We will use eight of those packages: ape, geiger, paleotree, phytools, nlme, knitr, devtools, and OUwie. To install all of these packages, we only need to open R (by opening RStudio, or any other alternative you prefer) and paste the following command:
install.packages(c('knitr', 'nlme', 'devtools', 'ape', 'geiger', 'phytools', 'paleotree', 'OUwie'))Note that these packages have about 150 additional packages that depend on, or recursively depend on, and thus this process may take 10-20 minutes depending on your internet connection.
A helpful utility program for creating, formatting, and editing character matrices, taxonomic information, and phylogenies in various file formats, particularly Nexus files, which we will be using in this workshop. In particular, character matrices are viewable in a spreadsheet-like format where information about individual characters, and their states, can be noted for easy reference. Written as a Java applet, and thus requires a Java environment to run.
Tracer is a popular program for examining, measuring and depicting the output of Bayesian analyses. While it was designed originally to work with output from the Bayesian phylogenetics program BEAST, and its successor, BEAST2, it is widely used with all sorts of Bayesian analyses that utilize a Monte Carlo Markov Chain (MCMC) to sample parameter values from the posterior distribution. Archives containing compiled executables for any operating system can be found here:
https://github.com/beast-dev/tracer/releases/tag/v1.7.1
The archives, once unpacked, should contain a readily useable executable for your OS.
On Linux, if you find that blocks executing tracer.jar because it isn’t a marked as an executable file (‘it lacks an executable bit’), you will need to set the executable permissions via chmod. Navigate to the directory the file is in and run:
sudo chmod +x ./tracer.jar An application you don’t have to install, IcyTree is a web-based phylogeny depiction tool which, nearly alone among all phylogeny depiction tools, will remove sampled ancestors (rather than displaying them as tips attached to the tree by ‘zero-length’ terminal branches) and then annotate the tree with dots to depict the collapsed sampled ancestor. IcyTree can be found at:
To obtain RevBayes, download and unzip the compiled binaries for Windows systems, found at:
https://github.com/revbayes/revbayes/releases/tag/v1.0.13
This unzipped directory will contain two executables (among many other files): rb.exe, which will open a command-line application in your respective terminal (probably MS Command Prompt, unless you have an alternative such as bash installed), and RevStudio.exe, which will open a primitive GUI for running RevBayes scripts.
You can see more details at the download page:
Install R by downloading and running this .exe file from CRAN:
https://cran.r-project.org/bin/windows/base/release.htm
Also, please install the RStudio IDE by visiting their website and downloading the installer file for your respective system:
https://www.rstudio.com/products/rstudio/download/#download
Note that if you have separate user and admin accounts, you should run the installers as administrator (to do this, right-click on the .exe file and select “Run as administrator” instead of double-clicking). Otherwise problems may occur later, for example when installing R packages.
Video Tutorial of Installing R on Windows, Courtesy of Software Carpentry:
You can download Mesquite from its Github repository at:
https://github.com/MesquiteProject/MesquiteCore/releases
For Windows, download the file ending in .zip and unpack its contents.
To run Mesquite in Windows, additional properties will have to be set to avoid complications with graphic scaling. The Mesquite developers provide the following steps for Windows 10, but systems with older versions of Windows will need to experiment, or find alternative instructions to achieve capability.
For Windows 10, enter the Properties of the ‘Mesquite.exe’ file by right-clicking, and then go to the Compatibility tab. Open the “Change high DPI settings” menu at the bottom, and then check “Override high DPI scaling behavior” in the new dialog box. In the popup menu located under ‘Scaling performed by:”, choose the option “System”. Click OK on the dialog to save and close, and click OK again to save and close the altered file properties. Again, none of these instructions may apply to Windows 8 and below.
Mesquite requires Java to run in. If you don’t have Java installed, Mesquite should ask you to install it the first time it runs. In case that doesn’t happen, you can download Java from:
You can find more detailed instructions about how to install Mesquite for Windows at:
https://www.mesquiteproject.org/Installation%20on%20Windows.html
We anticipate that all of the software described above should work without needing to be added to your systems path (or PATH) – an environmental variable which contains a list of all the file locations that Windows should look for important applications. If a directory is in your system’s PATH variable, a function in that directory can be called from the terminal (or by another program) from within any other directory on your computer. However, this may not be the case for everyone, and is most often an issue for Windows machines, In particular, Java should automatically add itself to your path when it installs, and RStudio should auto-detect R even if R is not in your path, but sometimes these things fail and you will need to manually edit your path variable.
The easiest way to edit the PATH on a Windows machine, if you are not familiar with using the terminal, is to go to ‘My Computer’ (or ‘Computer’), click on ‘Properties’ (or use the right-click menu on the ‘Computer’ icon to go to ‘Properties’), then go to the tab or dialogue labeled ‘Advanced’ or ‘Advanced system settings’. Within this area, enter the ‘Environment variables’ dialog, and then find the PATH variable in the ‘System Variables’ section. Click on PATH and then ‘Edit’, and add the location of the executable file you are trying to add to the Path environmental variable by pasting it after the existing files and locations listed in your path. Close this dialog and all remaining dialog windows by clicking ‘OK’.
You can find additional details about editing your PATH, and particularly adding Java to your path on the Java website, at:
To obtain RevBayes, download and unpackage the compiled binaries for macOS systems, found at:
https://github.com/revbayes/revbayes/releases/tag/v1.0.13
This archived directory, once unpacked, should contain two executable files in the top-level: rb, which will open as a command-line application in your system’s shell, and RevStudio, which will open a primitive GUI for running RevBayes scripts.
You can see more details at the download page:
Install R by going to CRAN and downloading, and running, this .pkg file:
https://cran.r-project.org/bin/macosx/R-latest.pkg
Also, please install the RStudio IDE by visiting their website and downloading the installer file for macOS:
https://www.rstudio.com/products/rstudio/download/#download
Video Tutorial of Installing R on macOS, Courtesy of Software Carpentry:
On Mac OS, Mesquite requires Java of an appropriate version. Machines with Mac OS 9 or lower cannot use Mesquite, as it requires Java 1.6, which is not available below Mac OS X. On Mac OX W 10.9 or below, Mesquite is optimal with Java 1.6, but Mesquite runs best on systems with Mac OS X 10.0 or higher with Java 1.7 (or higher). For MacOS X 10.10 (Yosemite) and later versions of the MacOS, the authors of Mesquite recommend using Java 1.8.
To install Java 1.7 or higher, if you only have Java 1.6, get the updated version from:
You can download Mesquite from its Github repository at:
https://github.com/MesquiteProject/MesquiteCore/releases
For Mac OS X, download a file ending in .dmg, selecting the release that matches your Java version. There are two alternatives, one for Java 1.6 (recommended for OS X 10.9, Mavericks, and lower), the other for Java 1.7 and above (recommended for OS X 10.10, Yosemite, and higher).
If the downloaded file doesn’t mount into a disk image automatically, double click the icon to mount, and drag the contents to your Applications folder. The Mesquite icon should now be able to start Mesquite. If you don’t have Java already installed, or Mesquite cannot find your Java installation, you will be prompted to install it. If Mesquite doesn’t find Java, or doesn’t automatically choose the version of Java you intended for it to use, you will need to edit your PATH variable. Go to your system terminal and type:
% /usr/libexec/java_home -v 1.8.0_73 --exec javac -versionAdditional details about installing and running Mesquite on macOS computers can be found at:
https://www.mesquiteproject.org/Installation%20on%20MacOS%20X.html
We do not anticipate that any of the program installations described here for macOS will require compiling source code to make a binary. However, it is possible that some macOS installations may require dependencies that need to be compiled to install these software, and CRAN packages occasionally do not have pre-compiled binaries available. To compile your own binanies or do a number of other advanced terminal operations, you will need to install the Command Line Developer Tools. These command line developer tools are an abbreviated version of XCode (https://apps.apple.com/us/app/xcode/id497799835?mt=12), which contains the aforementioned command line developer tools along with a number of other functionalities necessary for developing software on macOS machines. Both are offered for free via download by Apple, but XCode additionally requires you to make a (free) developer login. Command Line Developer Tools should contain sufficient compiler capabilities for what we need to do, particularly gcc, the GNU Compiler Collection.
The easiest way to prompt an install of Command Line Developer Tools is to instead try to install XCode via the XCode switch command, xcode-select, as this operation itself cannot be done with Command Line Developer Tools. Simply go to your terminal and paste:
xcode-select --install
This will prompt a dialog asking you to either obtain XCode, or install developer-line tools - click ‘Install’ to get the Command Line Developer Tools. Note that the files needed are quite large and may take several minutes to download and install.
If you are a regular Linux user, you will be unsurprised to learn that you will need to compile RevBayes yourself. To do so, you will need to first install cmake and the dev version of Boost, which is named libboost-dev-all. For a Ubuntu system that uses apt, you can get these with the following:
sudo apt-get install cmake
sudo apt-get install libboost-all-devThen obtain the source code:
git clone https://github.com/revbayes/revbayes.git revbayes --branch v1.0.13This should clone the source for version 1.0.13, but if not, get the tarball here before proceeding:
https://github.com/revbayes/revbayes/releases/tag/v1.0.13Finally, compile the source code with cmake:
cd revbayes/projects/cmake
./build.shThis will take a while (about half an hour on a relatively new Linux laptop with four cores and 8 GB of RAM). You can see more details at the download page:
You can download the binary files for your distribution from CRAN:
https://cran.r-project.org/index.html
Or you can use your package manager (e.g. for Debian/Ubuntu run sudo apt-get install r-base and for Fedora run sudo dnf install R).
Also, please install the RStudio IDE by visiting their website, and downloading the installer file for your respective flavor of Linux:
You can download the latest version for Mesquite from the Github repository:
https://github.com/MesquiteProject/MesquiteCore/releases
For Linux, download the packaged archive files ending in .tgz, and extract the contents of the downloaded archive. To start Mesquite, execute the mesquite.sh script from the terminal, which should automatically identify your java installation. If Mesquite cannot find Java, you may need to set your JAVA_HOME environment variable.
Installing Mesquite on Linux can be a headache, as most Java Virtual Machines present in modern distros (e.g. modern Ubuntuu distros, like Linux Mint), are known to not properly run Mesquite. The only exception is the official Sun/Oracle VM, but that may not be available or tested for your distribution. Please see here for instructions and troubleshooting related to installing Mesquite on Linux machines:
https://www.mesquiteproject.org/Installation%20on%20Linux.html
Portions of the above text is based on text from the workshop templates supplied by [Software Carpentry] (https://carpentries.github.io/workshop-template/), which is licensed by The Carpentries organization under a CC-BY license.se.