# Using the R Installer Plug-in

Due to the possibly difficult nature of setting up a GenePattern server to use multiple versions of R, we have created a plug-in to assist in the process.  This plug-in only deals with R 2.15 at present; we may expand to cover other versions of R in the future.  The plug-in installation is triggered by the installation of a module which declares that it requires R 2.15.   At the moment, this is limited to the beta releases of ExpressionFileCreator v11.14+ and RankNormalize v1.3+, both available from our Beta repository.  We will update other modules as the opportunity permits (this document last updated Dec. 9, 2013).

The Mac platform is the most tricky in terms of support for multiple versions of R and so that will be the main focus of this guide.  As the story is much simpler on Windows and Linux, those platforms will be covered much more briefly.

## Use of the R Installer on Mac OS X

Due to the way that it is installed, support for use of multiple versions of R on Mac OS X is tricky and has a number of issues.  It is mainly due to these issues that the GenePattern team created the R Installer Plug-in to simplify the process.  The plug-in will go through several possible scenarios to detect and/or install R in a way that works for GenePattern.  For the most part, you should not need to worry about those details.

### The Simplest Path

If you already have a version of R installed in the default location on your Mac, the plug-in will be able to set up R 2.15 for use with GenePattern.  This can be any version of R: it could be 2.5.1 or 2.15.2 or any other version.  The reasons for this will be discussed below if you are interested; for most users the reasons are not important.

Many users will have already installed R 2.5.1 as it required for several core GenePattern modules (CART, ComparativeMarkerSelection, ConsensusClustering, GEOImporter, NMFConsensus and others).  If you think you will be using these modules, you should go ahead and install this version of R first.  If you do so, then when you later install ExpressionFileCreator the plug-in will automatically download and install R 2.15.2 into the correct location and set it up for use with GenePattern.

Alternatively, if you have already installed R 2.15 (at any patch level) to the default location then the plug-in will detect it and set it up for use with GenePattern.  Note that this makes some minor changes to the installed version of R.  The reasons for this - and its effects - are discussed below; again, for most users the reasons are not important.

The bottom line for most users is that if you've already installed either R 2.5.1 or R 2.15 as usual from a CRAN installer, the plug-in will configure things correctly for you.  Some possible complications will be discussed in the next section, but you should not need to worry about them unless you use R outside of the context of GenePattern or if you decide to update your R installation.

### Possible Complications

There are some important considerations if you work with R outside of GenePattern or if you decide to update your version of R:
1. On a Mac, installing a newer version of R may result in older versions being removed unless you take specific steps to avoid this.  As a practical matter, the R 2.15 installers will not remove R 2.5.1.
2. Certain files must be changed in the R installation in order to allow multiple versions to work at the same time.  Those changes will be undone if you update R to a different patch level, so it will be necessary to re-apply those by hand.  The R 2.15 patch level bundles are available from the GenePattern FTP site.  After installing R 2.15.3, for example, you would download R_2.15.3_mac_patch.tar.gz and then open Terminal.app to unpack it.  Execute these commands:
 cd /Library/Frameworks/R.framework/Versions sudo tar -xzvmpf ~/Downloads/R_2.15.3_mac_patch.tar.gz
3. If you switch between multiple versions of R outside of the context of GenePattern, you should modify all of your versions of R in a similar way.  At this time, we are only providing patch level bundles for the versions of R used by GenePattern.  For any other version, you will need to do this on your own.  Please note that the available bundles are version-specific down to the patch level, so don't try to use them with other versions.  Also, the use of a utility like RSwitch may confuse GenePattern unless all versions of R have been so modified.
4. The plug-in backs up the modified files beforehand, so if you want to revert your R installation back to the original state for any reason (such as uninstalling GenePattern, for example) you can delete the modifications and put the originals back in place.  Note that doing so will very likely affect the behavior of R modules in GenePattern.  The original files are stored alongside the modified files in the same path location but with the ".orig" extension added (e.g. R64.orig).
5. If you do not install it yourself, the version of R 2.15.2 delivered by the plug-in is not quite a full installation.  In particular it is missing the R.app and R64.app GUI applications.  Again, this will only those user who want to use R outside of GenePattern.  These users should instead install R 2.15.2 on their own and allow the plug-in to detect it.

## Using the R Installer on Windows

Support for use of multiple versions of R on a Windows machine is straightforward.  R comes in standard click-through installers available from CRAN.  Due to the way it is installed, each version is completely isolated and it is possible to have different major and minor R releases, and even different patch-levels, on a Windows machine at the same time: R 3.0.1, R 2.15.2, R 2.15.3, R 2.5.1, etc. can all be present with no issue.  This being the case, R installation is left up to the user with the plug-in making only a few final configuration steps.

On a Windows machine, the R Installer Plug-in will attempt to detect R in the standard location.  If it does, it will go ahead and configure GenePattern to use it.  All you need to do is to obtain and install R 2.15.2 using the default settings, and then install a module like ExpressionFileCreator v11.14+ that needs it.

If you will be installing R to a different location, you will need to take the extra step of setting a custom property for R2.15_HOME manually on your GenePattern server.  This is also required if you decide to run a different patch level of R such as 2.15.3.

## Using the R Installer on Linux

Support for use of multiple versions of R on Linux is good, though it requires platform-specific steps by the system administrator.  Setting up the installations of R varies by Linux distribution; we can't give general instructions due to the large number of distributions available.  You are advised to look to the specific instructions for your platform at either CRAN or your distribution's support site (or both).

Note that obtaining R through a package management system like apt-get may result in an installation that will be auto-updated to a different version in the future.  This can lead to compatibility problems in running your modules and affect reproducibility of your past results.  To avoid this you can instead install R from the archived source bundles to keep multiple versions available.  Please refer to CRAN and your distribution's support site for more information.

After obtaining and installing the required version of R, you will need to set a custom property  for R2.15_HOME manually on your GenePattern server before installing modules which require it.  When the R Installer Plug-in runs, it will check whether this property has been set and verify that it points to an installation of R with the correct major and minor version.

## Possible Plug-in Errors

### Substitution Variable

Depending on your version of GenePattern, you may receive an error message similar to:
no substitution available R2.15_HOME in command line R2.15_HOME/bin/Rscript
Certain versions of GenePattern are not able to load all required settings in one pass but may succeed on a second attempt.  Try re-installing the module or pipeline as that may resolve the issue.  If this error persists, the information in this Admin Guide section and the plug-in output may help you resolve the issue.  There are additional details in the Using Different Versions of R section of the Admin Guide as well.

### Installation location error (Mac only)

On a Mac, if you have never installed any version of R you will probably get a message regarding the /Library/Frameworks/R.framework/Versions directory not being present.  In Mac OS X Lion (10.7) and above, creating this location requires administrator privileges and can't be done within GenePattern.  This is why the plug-in will work if you've already installed some version of R: that previous install will have created the correct location for you.  Without that location, the installation attempt will very likely fail and require some manual steps.  There are two options.  Either choice is fine; you only need to do one or ther other:
• Install R 2.15 manually in the default location so that the plug-in can detect it.  This is available from CRAN; see here for locations.
• Execute the following commands from a Terminal window:
 sudo mkdir -p /Library/Frameworks/R.framework/Versions sudo chgrp -R admin /Library/Frameworks/R.framework/ sudo chmod -R g+w /Library/Frameworks/R.framework/
Administrative access will be required in either case, and afterward it will be necessary to retry the plug-in installation.

### Version Check

The R Installer Plug-in will check the configured version of R to make sure it is compatible.  There are several problems or conditions that it can detect at this point:
• The installed R version has a different patch level than expected.  This is just a warning and will not stop the plug-in installation.
• The installed R version has a different major or minor number than expected.  This is considered an error; the most likely cause is that you have set up R2.15_HOME to use a version of R other than 2.15.
• The installed version of R can't execute, results in an error, or returns no output.  You may need to re-install R 2.15, but first check to make sure that R2.15_HOME contains no typos.

Updated on December 08, 2013 20:46