Using Different Versions of R  Print-icon

Installing GenePattern (version 3.1 and later) installs R 2.5.

Most of the GenePattern modules available in the Broad Institute repository (Modules & Pipelines>Install from repository) work with R 2.5. However, some GenePattern modules require different versions of R; for example, ComBat v2 requires R 2.7. Unfortunately, R is not backward compatible. If you simply install and run the latest version of R, modules may fail or (worse) may produce invalid results even though they do not fail.  Instead, you must have multiple versions of R installed in order to run all of these modules together on the same server.

Defining R in GenePattern

In GenePattern, each module definition includes a command line that runs the analysis program. For an R module, the R version is defined by a command line substitution parameter. For example, the <R> parameter is substituted with the full path to the R 2.0.1 executable. The <R2.5> parameter is substituted with the full path to the R 2.5 executable. Similar parameters are used for other versions of R.

GenePattern version 3.1 and later installs R 2.5 and sets the <R2.5> parameter. If you upgraded from GenePattern 3.0, your GenePattern installation also includes R 2.0.1 and sets the <R> parameter.

Newer versions of GenePattern also set the <R2.5_HOME> parameter, pointing to the location of the R 2.5 installation such that Rscript is found at <R2.5_HOME>/bin/Rscript.  The GenePattern team is phasing out the use of <R2.5> in favor of <R2.5_HOME> in future module revisions.

Adding More Recent Versions of R to GenePattern

To add a different version of R to your GenePattern installation (for example R 2.7 on Mac OS X, for ComBat v. 2):

  1. Install the required version of R, if necessary. This is covered in detail on the R Project home page.  For Mac users, please read the section on 'Using Multiple Versions of R on Mac OS X' below.
    1. Go to http://www.r-project.org/ and select a CRAN mirror.
    2. Locate either the source code or the binary for the desired version of R. For a binary installation, look for the subdirectory link labeled 'old', which is towards the bottom of the page.  The next section lists the locations of various versions of R used by GenePattern.
    3. Follow the installation instructions.
  2. After you install the correct version of R, in whatever manner makes sense to you, you need to configure GenePattern to use that version of R. This is as simple as adding two new substitution parameters to the server settings.
    1. Click Administration>Server Settings and go to the Custom page.
    2. Add a setting for R*_HOME and another for R*, replacing the '*' with an actual version number.
      • For R 2.7 on Mac OS X the parameters are:
        R2.7_HOME=/Library/Frameworks/R.framework/Versions/2.7/Resources
        R2.7=<java> -DR_suppress=<R.suppress.messages.file> -DR_HOME=<R2.7_HOME> -Dr_flags=<r_flags> -cp <run_r_path> RunR
      • For other platforms, set R2.7_HOME equal to the full path to the installation directory. It must be a directory which contains a 'bin' folder, which contains the 'R' executable.
    3. For modules requiring R 2.15, it is only necessary to set the <R2.15_HOME> parameter.  Setting the <R2.15> parameter is not required as its use is discouraged.

Where to Find Older Versions of R

CRAN makes older versions of R available through its archives.  Archived binary releases are available here for Mac and here for Windows.  Older binary releases are not available for Linux and other platforms.  Instead, it is necessary to build from the archived source bundles.  In particular, here are direct links to the versions of R required by modules provided in the GenePattern public and beta repositories:

There are a number of CRAN mirrors as well.

Using Multiple Versions of R on Mac OS X

While it is possible to run multiple versions of R on a Mac, doing so requires more care and effort than on Windows or Linux.   In particular, you need to pay careful attention when choosing the R versions that are required and use caution during installation.  The order of operations is important and performing steps out of sequence can adversely affect versions already installed on the machine or require backtracking in the process; please read the following before proceeding.  The GenePattern team has not fully evaluated all of the possible issues and combinations involved.  What follows is our best understanding at present (this document last updated Dec. 9, 2013).
 

The Simplest Path

If you do not plan to be using R outside of GenePattern, then the following steps should cover setting up your Mac for multiple versions of R.  Note that the 'sudo' commands used below will prompt you for your password to grant administrative access.
  1. Install R 2.5.1 using the CRAN installer.
    Download this patch file bundle to modify R 2.5.1 to allow use of other versions of R.  After downloading, execute the following from Terminal:
    cd /Library/Frameworks/R.framework/Versions
    sudo tar -xzvmpf ~/Downloads/R_2.5.1_mac_patch.tar.gz
  2. (Optional) If you will be using the ComBat module, you will also need to install R 2.7.2.  
    Before using the CRAN installer, execute the following from Terminal:
    sudo pkgutil --forget org.r-project.R.framework
    If you do not, the CRAN installer will remove R 2.5.1.  It should give you a message similar to "Forgot package 'org.r-project.R.framework' on '/'."  After that, use the R 2.7.2 CRAN installer as usual.
    Download this patch file bundle to modify R 2.7.2 to allow use of other versions of R.  After downloading, execute the following from Terminal:
    cd /Library/Frameworks/R.framework/Versions
    sudo tar -xzvmpf ~/Downloads/R_2.7.2_mac_patch.tar.gz
    Then set the R2.7_HOME and R2.7 substitution parameters as described above.
  3. If you are planning to use ExpressionFileCreator v11.14+ or another module that requires R 2.15.2, it is recommended that you use the R Installer Plug-in which will automatically install and configure R 2.15.2 for use with GenePattern.  As opportunity permits we will be updating our R 2.15.2 modules to use this plug-in, but if you encounter one which does not then you can use RankNormalize v1.3+ to trigger the installation.  Both of these modules are available from our Beta repository.
For most users, this set of instructions should be sufficient.  If you skip Step 2 but later decide that you need ComBat, it should be fine to go back and do it later provided you first use the pkgutil command.  Users who will be working with R outside of GenePattern will need to be aware of a number of additional details.  This includes users doing R development, running R scripts, or updating the R installations.
 

Further Details

When you install R from CRAN (for example, R 2.7) it becomes the default version of R on your system.  This is true even if you had previously installed a newer version of R such as R 2.15. Executing R from a Terminal command line or the R GUI will run the last installed version.  Unless other steps are taken, this will affect GenePattern as well.
 
By default, the CRAN installer will also modify other installed versions, resulting in these possibly being removed or otherwise adversely affected. This is spelled out in a README displayed within the installer (on the second step) and provides instructions to avoid these effects.  If you want to run multiple versions of R on the Mac, these instructions apply to you.  Before installing an additional version, you will need to execute a "pkgutil --forget" command from the Terminal command line so that the next installer will not touch the existing version of R.  Versions of R are bundled as a DMG file (built for OS X Tiger and later) or as a PKG file (for OS X Leopard and later).  The correct command depends on the type of bundle that you are installing:
  • For R 2.5 (and possibly earlier) to 2.10 (Tiger builds):
    sudo pkgutil --forget org.r-project.R.framework
  • For R 2.10 to R 2.15 (Leopard builds):
    sudo pkgutil --forget org.r-project.R.Leopard.fw.pkg
Since they are registered differently, installing a Leopard build doesn't affect an existing Tiger build other than taking over as the default version of R.  Likewise, a Tiger install won't affect a Leopard build other than becoming the default.  Note that R 2.10 was transitional, so the correct instructions depend on whether it is installed from the DMG (Tiger) or the PKG (Leopard) file.  The command given above for Tiger builds differs from the instructions given in the installer itself.  Those instructions applied to earlier versions of Mac OS X (e.g. Tiger) while the above command is the equivalent in GenePattern-supported versions of Mac OS X.
 
R 3.0 is the first version that requires OS X Snow Leopard.  It comes as a PKG file, gives the same 'pkgutil' instructions as the Leopard builds and seems to behave the same way.  We have not tested any GenePattern components on R 3.0 and therefore do not recommend it for use with GenePattern at this time due to the issues with compatability and validity covered earlier.
 
This posting on the R-SIG-Mac mailing list indicates that the above instructions assume that you are upgrading R (like going from R 2.12 to R 2.15) and that they may not work for installing earlier versions (e.g. installing 2.12 after 2.15).  We have not fully tested the
various combinations but we have seen problems based on installation order.  We recommend first carefully choosing the versions you need and then installing them in order from oldest to most recent. 
 
If you are running R from outside of GenePattern and need to use a different version, you can use the RSwitch program to change which is current.  For example, after you install R 2.7 you can use RSwitch to switch back to R 2.15.  This is documented in the R for Mac OS X FAQ.  There are some additional instructions if you intend to use RSwitch.  We don't havee specific recommendations on this kind of setup but you can find further details in this post on the R-SIG-Mac mailing list. 
 
The use of RSwitch is not effective for use from GenePattern due to the need to run multiple R versions at the same time. As a workaround, you must edit the installed executable shell scripts.  The patch level bundles described above do this for R 2.5.1 and 2.7.2 and the R Installer plug-in does it for R 2.15.  If you have other versions of R you will need to make these modifications on your own.  In the affected files, replace all hard coded paths to /Library/Frameworks/R.framework/Resources with the actual path to the correct installed version of R as described by this posting from the R-SIG-Mac mailing list.  These are the important scripts to modify (not all are present in every version): 
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/bin/R
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/bin/R32
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/bin/R64
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/etc/i386/Makeconf
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/etc/x86_64/Makeconf
  • /Library/Frameworks/R.framework/Versions/<your R version>/Resources/etc/ppc/Makeconf
Use a plain text editor like vi or emacs to make these changes.  It is a good idea to make a backup copy beforehand and to use 'sudo' when editing so that the files retain their original permission and ownership settings.  Be aware that, according to this R-SIG-Mac posting, there may be some issues with this set-up.  If you use R outside of GenePattern, we recommend that you use RSwitch to set your favored version as Current when all these modifications are finished as this seems to be the best way to mitigate those problems. 
 

Adding R Version 2.0.1 to GenePattern

There are some GenePattern modules which rely on R version 2.0.1:

To use these modules on your server you need to add R version 2.0.1.  Note that R 2.0.1 may not be available or may not work properly on newer versions of Windows and Mac OS X.  We are in the process of evaluating how to address this.

To add R2.0.1 to your GenePattern installation:

  1. Install R2.0.1.
  2. In GenePattern, click Administration>Server Settings and go to the Programming Languages page.
  3. Set the R 2.0.1 Home parameter to the full path of the R2.0.1 installation. This defines the <R> variable.
  4. Click Save to update the GenePattern server configuration.

GenePattern can now run modules written for R2.0.1.

<< Setting the Java Version Up Using the R Installer Plug-in >>

Updated on December 08, 2013 20:47