RMesquite package for R  

Hilmar Lapp & Wayne Maddison

The RMesquite package provides basic services for R to make use of functions in the evolutionary analysis system Mesquite. With RMesquite, R users can have access to the interactive interface of Mesquite as well as a broad array of computations in Mesquite. (A companion package, Mesquite.R, provides access in the reverse direction, for Mesquite to access functions in R.)

Installation

To use RMesquite you must:

• In R, install RMesquite. Until the package appears on CRAN (at which point you can install from CRAN as you normally would install R packages), you can install from R-Forge, using install.packages("RMesquite", repos="http://R-Forge.R-project.org") from within R. RMesquite depends on the packages rJava and ape.
• Install Mesquite 2.72 or later (http://mesquiteproject.org)

Starting Mesquite

Before using functions of Mesquite, start it using startMesquite:

> library(RMesquite) 
> startMesquite() 

This simple style of starting Mesquite will work only if you have previously started your copy of Mesquite. If you have, then Mesquite will have recorded its location in its preferences file, and RMesquite will look there to discover where Mesquite is. If you haven't started Mesquite previously, then you will need to indicate the location of the Mesquite copy you want to run:

> library(RMesquite) 
> startMesquite("/Applications/Mesquite_Folder") 

If you want to run a headless version of Mesquite (see below), you need to either specify its location, or you need to have previously run the headless version and then indicate RMesquite is to look for it by setting headless to TRUE:

> library(RMesquite) 
> startMesquite(headless = TRUE) 

See the R help page for startMesquite for more details.

Headless versus Graphical Mesquite

You can call from R either the normal graphical version of Mesquite, or a headless version of Mesquite. If you want to have access to Mesquite's windows, you need to use its graphical version. If you want to use only non-graphical calculations in Mesquite, you can use either version. See the section on Starting Mesquite for how to specify which version to use.

Note for Mac OS X users: If you want to use the graphical version of Mesquite on Mac OS X 10.5 or later then you must start R using the GUI application JGR application for running R. Conversely, if you want to use the normal R GUI application or R from the Terminal on Mac OS X, then you must use the headless version of Mesquite. (This is not in our control; this restriction is due to a constraints in OS X and R.)

Troubles?

If starting up Mesquite fails, then here are some possible problems:

• java.lang.NoClassDefFoundError — probably indicates you haven't indicated the correct path to Mesquite_Folder, or you haven't started that version of Mesquite on its own recently. Make sure that you indicate the path to Mesquite_Folder, or that before starting R you've started and closed Mesquite separately. When Mesquite starts up, it records its location in a preferences file so that R can find it.
• Mac OS X only: "Sorry, you need to be running R from JGR when starting up a graphical version of Mesquite on Mac OS X." — This indicates you tried to start the graphical version of Mesquite from the normal version of the R GUI application or from the command line on OS X. If you want to use the graphical version of Mesquite from R on Mac OS X, you need to run R from the alternative JGR application.
• Mac OS X only: java.lang.InternalError: Can't start the AWT because Java was started on the first thread. This also indicates you tried to start the graphical version of Mesquite from the normal version of the R GUI application or from the command line on OS X. If you want to use the graphical version of Mesquite from R on Mac OS X, you need to run R from the alternative JGR application.

Example: Using Mesquite to edit a tree from R

To send a phylogenetic tree (of type phylo) to Mesquite to be edited by hand, call editTree:

> modifiedTree <- editTree(myTree)

Mesquite will display the tree. Edit the tree as you wish using Mesquite's tools, then hit the "Done" button to send the modified tree back to R. The tree window in Mesquite will close. (If you want it to persist, use a combination of showTree(tree) to show the tree in Mesquite and then getTreeInWindow() to retrieve it.)

Example: Getting a matrix from Mesquite

After starting Mesquite from R, you can go to Mesquite and use the File>Open File... menu item to open a data file within Mesquite. Bring a character matrix window to the front, and then go back to R to call getMatrixInWindow:

> mesquiteMatrix <- getMatrixInWindow()

This is obtained as a java object, but you can convert it into a normal R matrix using as.matrix.

Source Code, Downloads, Mailing lists

• Source code of RMesquite is available at its R-Forge subversion repository, where you can find the URLs to checkout the code in svn.
  Note that to rebuild the Java sources, Mesquite needs to be installed and found by the Java compiler. If you have launched Mesquite before, it's location should be found automatically. Otherwise copy build.properties.example to build.properties, and specify the path there.
• The R-Forge project page has also links to nightly svn snapshots, and users and developers mailing lists.
• Daily built packages (source, Windows binary, and Mac OSX binary), as well as R CMD check logs, can be downloaded from the R Packages page on R-Forge.

Citation

If you make use of Mesquite for the analysis of results, such as to estimate ancestral states, then you should cite the functions in Mesquite. Thus, we suggest a citation like this: "The <insert analysis name here> analysis was performed by Mesquite 2.72 (Maddison & Maddison, 2009), run via the RMesquite package (Lapp & Maddison, 2009) from R version 2.10.0."

Lapp, H. & Maddison, W.P. 2009. RMesquite, an R package for transparent access to Mesquite functions. http://rmesquite.r-forge.r-project.org

Credits

RMesquite and Mesquite.R were stimulated by the Comparative Methods in R Hackathon at NESCent in Dec 2007, and supported by the National Evolutionary Synthesis Center (NESCent), NSF #EF-0423641.

RMesquite is distributed under a GPL version 2 license.