Difference between revisions of "Download and Installation"

(-Install R in system directory)
(-Install R in system directory)
Line 138: Line 138:
 
** then clicking "Properties", Advanced system settings",  
 
** then clicking "Properties", Advanced system settings",  
 
** then under "User variables" for "your_user_name", click "New...".   
 
** then under "User variables" for "your_user_name", click "New...".   
** Enter the new variable name '''R_LIBS_USER''' and the location '''C:\Users\''user_name''\R\win-library\3.0'''.   
+
** Enter the new variable name '''R_LIBS_USER''' and the location '''C:\Users\''user_name''\R\win-library\3.1'''.   
 
* You must create the corresponding directory structure yourself before running geWorkbench, e.g.  
 
* You must create the corresponding directory structure yourself before running geWorkbench, e.g.  
 
** in your home directory '''C:\Users\''user_name''''', create the new folder '''R''',  
 
** in your home directory '''C:\Users\''user_name''''', create the new folder '''R''',  

Revision as of 17:29, 15 October 2014

Download Instructions | License Information



This section contains instructions for downloading and installing geWorkbench.


Special Note for Mac Users

When you try to install geWorkbench on the Mac, you may see a message "Install is damaged and cannot be opened. You should move it to the Trash"

The installer is not damaged, rather, this message is a consequence of restrictions imposed by the OSX Gatekeeper. Please see the Mac installation section for a work-around.

Download geWorkbench

As of November 6, 2013, geWorkbench downloads are being hosted on an SFTP server hosted by NCI-CBIIT.

The previous download site on the NCI GForge system is no longer usable.

geWorkbench 2.5.1 (released November 1st, 2013)

NOTE - November 12, 2013, 8 pm EST - The geWorkbench 2.5.1 files were replaced between 8 pm and 8:15 pm, as a file needed by the VIPER analysis was missing.



geWorkbench 2.5.1 - System Requirements

Java

  • The Java 6 Runtime Environment (JRE6) is required for full functionality. geWorkbench will run using Java 7 and Java 8, but has not been fully tested in that environment. A few components are known not to work under Java 7/8 (see Known Issues for details).
  • For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE6 included. To install a version of geWorkbench that does not include the JRE, the JRE6 must be installed separately on the machine.
  • On MacOSX, the Java 6 JRE is still available with recent versions of MacOSX versions (Intel platforms only) (But see the special note below in the Mac section). Java 6 and higher are not available for the PowerPC platform.
  • The "Generic" distribution of geWorkbench does not include the JRE6. It must be installed separately.
  • geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
  • See the Java System Requirements for further details.


How to choose

  • Using an installer version of geWorkbench that inludes the JRE6 allows you to be sure that you are running geWorkbench with the correct version of the JRE.
  • You may wish to install a "no JRE" version of geWorkbench if you want to choose between 32 and 64 bit JREs, to keep up with the latest updates to the JRE, or to experiment with Java 7. However, under Windows, the installer version of geWorkbench will then use the latest version of Java available on your computer. You can specify the exact JRE to use, even when using an installer version, by following the instructions in the below section Generic for setting the JAVA_HOME variable and starting geWorkgbench.

Obtaining the Java 6 JRE

Display Driver

  • This requirement pertains only to using the PCA component 3D graph viewer.
  • When using a 64-bit JVM, the Java 3D library requires that OpenGL version 1.2 or higher be supported by your display driver.

Memory

At least 2 GB is recommended. geWorkbench 2.5.1 by default will request up to 1 GB of memory for the Java VM.

Operating System

  • Windows XP/Vista/Windows 7 (32 or 64-bit): no special requirements.
  • MacOSX: Version 10.5 with latest updates, or any higher version (10.6, 10.7 +) is required to provide the Java 6 JRE (Intel platform only) (See special note above).
  • Linux: A version of Java must already be installed on the machine in order to run the geWorkbench installer.

geWorkbench, unless otherwise noted for particular components, can be run on both 32 and 64-bit operating systems and JREs.

Graphics Driver

At least one component, the PCA viewer, uses a Java 3D library. When using a 64-bit JVM, the Java 3D library requires OpenGL version 1.2 or higher to be supported by the graphics display adapter in your computer.


R server

Several components (SAM, DeMAND, and VIPER) can use a local installation of R on your desktop computer.

This has been tested with R versions 2.15.0, 3.0.2 and 3.0.3.

There are special considerations for installing a local copy of R on Windows computers. Please see the section on this further below.

IMPORTANT NOTICE ABOUT THE LICENSE

Use of geWorkbench is governed by the rules specified in the software license. Please make sure to read the license and understand your obligations before proceeding to download the application.


Installation Instructions

All three platform-specific versions of geWorkbench (Windows, Linux, and Macintosh) provide an installation wizard (generated using InstallAnywhere).

  • Using an installer version of geWorkbench that inludes the JRE6 allows you to be sure that you are running geWorkbench with the correct version of the JRE.
  • You may wish to install a "no JRE" version of geWorkbench if you want to choose yourself between 32 and 64 bit JREs, or to keep up with the latest updates to the JRE.
  • On Windows and Linux, geWorkbench was tested using installer versions which included the JRE6. The included JREs are 32-bit versions.

A generic version of geWorkbench, which does not use any installer, is also available, and should run on any machine which supports Java 6.

Further information about the InstallAnywhere requirements are found at the Flexera website.


Windows (XP/Vista/7/8)

Special note for Vista/Windows 7 & 8

geWorkbench installation

  • geWorkbench installation directory - If you run the installer on Vista or Windows 7 or 8, the installer will prompt you to install geWorkbench to your user home directory, e.g. C:\Users\username\geWorkbench_2.5.1, where username is your Windows login name.

R installation on Windows

  • R installation directory - Some geWorkbench components can make use of a locally installed version of R. There are specific considerations for installing R on Windows Vista/7/8.

We have demonstrated two methods based on the links shown below.

-Install R in user directory

You can install R directly into your own user directory. Packages will be placed directly into the library within the installation. You just need to set the R-script location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.

C:\Users\user_name\R-3.1.1\bin\Rscript.exe 

where for user_name please substitute your own Windows login name.

-Install R in system directory

You can allow Windows to install R into the default system directory, e.g. C:\Program Files\R\R-3.1.1\.

NOTE - If you are using a recent version of Java 6 or Java 7 you must instead install R to a directory without spaces in its path, e.g. C:\R\R-3.1.1\. This problem is fixed in the upcoming release of geWorkbench v2.5.2.

Set the Rscript location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.

C:\Program Files\R\R-3.1.1\bin\Rscript.exe
or 
C:\R\R-3.1.1\bin\Rscript.exe

depending on where you installed R.

However, in this case, geWorkbench will not be able to install needed R packages into the default location because it cannot write to the system directory. However, you can circumvent this problem by setting the Windows environment variable R_LIBS_USER to an appropriate user directory, e.g C:\Users\user_name\R\win-library\3.1 for the current release of R, where for user_name please substitute your own Windows login name. (The proper number to use is x.y, for R version x.y.z).

  • You can create the environment variable R_LIBS_USER by e.g.
    • right-clicking on "Computer" in Windows Explorer,
    • then clicking "Properties", Advanced system settings",
    • then under "User variables" for "your_user_name", click "New...".
    • Enter the new variable name R_LIBS_USER and the location C:\Users\user_name\R\win-library\3.1.
  • You must create the corresponding directory structure yourself before running geWorkbench, e.g.
    • in your home directory C:\Users\user_name, create the new folder R,
    • then within it create win-library,
    • then within win-library create the appropriate directory e.g. 3.1 for version 3.1.* of R.
-Links to information on installing R on Windows
  • R packages directory - You can set the R packages directory to one in your own user space in order to gain write permission. Please see the R FAQ on library directory.

Installer with JRE6

  • File: geWorkbench_v2.5.1_Windows_installer_with_JRE6.exe
  • Includes the 32-bit Sun Java 6 JRE.

Download and double-click the installer file to begin installation.

Installer without JRE6

  • File: geWorkbench_v2.5.1_Windows_installer_noJRE.exe
  • No JRE is included, you must make sure that an appropriate Java 6 JRE is installed on your system before installing geWorkbench.

Download and double-click the installer file to begin installation.

MacOSX

  • File: geWorkbench_v2.5.1_MacOSX_installer.zip.
  • This version uses the Java 6 JRE, which is still available as an update to the MacOSX operating system. (Intel platforms only).

Double-click geWorkbench_v2.5.1_MacOSX_installer.zip to begin installation. This will extract a file called "install". Double-click on this file to install geWorkbench.

You may see a message "Install is damaged and cannot be opened. You should move it to the Trash"

The installer is not damaged, rather, this message is a consequence of restrictions imposed by the OSX Gatekeeper. Please see the next section for a work-around.


GateKeeper

In recent versions of Mac OSX (including 10.8 and 10.9), the Gatekeeper function may not allow the downloaded geWorkbench file to install. The initial zip file can be unpacked, but the resulting "install" app may not execute. Instead, you may see the message:

"Install is damaged and cannot be opened. You should move it to the Trash"


To allow geWorkbench to install, you must temporarily tell Gatekeeper to allow installation of files from "anywhere".

You can do this by

1. Go to System Preferences, Security and Privacy

2. On the "General" tab select "Allow applications to download from: Anywhere".

3. Now run the geWorkbench installer again.

4. After you have installed geWorkbench, the security preference changed in (2) should be set back to its original setting.

R installation on Mac OS X

R can be installed to the default system location.

  • If you are running as an administrator, R will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.0/Resources/bin/Rscript.
  • In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.0/Resources/Library.

Java 6 on Mac OSX

Recent releases of OS X such as 10.8 and 10.9 may disable the Java 6 runtime which is needed by geWorkbench.

When you first try to run geWorkbench on one of these later versions of OSX, you may be prompted by the operating systgem to install the Java 6 runtime.

If this prompt does not appear, Java 6 can be re-enabled by installing the latest Java 6 update from Apple. The most recent update (as of November 2013) is 2013-005.

With the exception of a few components, geWorkbench will also run under Java 7 and Java 8. The Java 7 and 8 JREs can be downloaded from http://java.oracle.com.


Notes

  • Requires Mac OS X 10.5 with updates, or 10.6+. Recent testing has been on 10.6, 10.8 and 10.9.
  • As Java 6 is not available for the PowerPC platform, regardless of OS X version, geworkbench will not run on the PowerPC platform under any version of OS X.
  • The compressed installer should be expanded automatically by the system.

Linux

Installer with JRE6

  • File: geWorkbench_v2.5.1_Linux_installer_with_JRE6.bin.
  • Includes the 32-bit Sun Java 6 JRE.

Installer without JRE6

  • File: geWorkbench_v2.5.1_Linux_installer_noJRE.bin.
  • No JRE is included, you must make sure that an appropriate Java 6 JRE is installed on your system before installing geWorkbench.
  • You may need to configure the JRE. See section below, "Java Environment Configuration".

Installation

You must already have installed a version of Java 1.6 or later on your Linux machine in order to run the geWorkbench installer.

The Linux version of geWorkbench relies on X-Windows being installed and running. If you are running Linux on a server and e.g. you wish to view the application on a Windows desktop, you will also need to run an X-windows server on your desktop machine. See X-Windows configuration instructions below.

After downloading, cd (if needed) to the directory to which you downloaded the installer.

To begin the installation, type the command for the particular version, e.g. for the installer with JRE:

"sh ./geWorkbench_v2.5.1_Linux_installer_with_JRE6.bin".

This will extract geWorkbench into a new directory called geWorkbench_2.5.1.


If you requested that a desktop link be created, it will be called rungeWorkbench_2.5.1.

Note - if you made changes to the default installation directory name, the shortcut link may just be called "geWorkbench_2.5.1" rather than "rungeWorkbench_2.5.1".

Running geWorkbench (Linux)

To run geWorkbench, and assuming you are using the Linux bash shell, and that you created a shortcut link during installation, issue one of the following commands from your home directory:

   ./rungeWorkbench_2.5.1 
   or
   sh rungeWorkbench_2.5.1.
   or
   sh geWorkbench_2.5.1 if the link received the alternative name (see above).
         

Alternatively, in the directory in which geWorkbench was installed, you can start geWorkbench with the command:

   sh launch_geWorkbench.sh

Generic

A non-installer-based version of geWorkbench is supplied in a Zip file which should work on any platform.

File: geWorkbench_v2.5.1_Generic.zip

Installation

Unzip the file. It will create a directory geWorkbench_2.5.1.


Running geWorkbench (generic)

You must have the Java 6 JRE installed and the JRE must be in the path for geWorkbench (see Java Environment Configuration below).

Windows: you can double click on the file "launch_geWorkbench.bat" to launch geWorkbench, or run it from a command window.

Linux/Unix: Execute the script "launch_geworkbench.sh".

Any: Alternatively, if you have Apache Ant installed, you can type "ant run" in the geWorkbench directory.

Java Environment Configuration

To run a version of geWorkbench that does not include the Java 6 Runtime Environment (JRE6), the JRE6 must be installed and, depending on the platform configured separately.

Two environment variables may need to be properly configured. These are the JAVA_HOME and the PATH variables. They should be configured to point to your own installation of the JRE6.

Linux/Generic

Here is an example of setting the two environment variables for a JRE installed in the directory /opt:

JAVA_HOME=/opt/jre1.6.0_31

PATH=/opt/jre1.6.0_31/bin:$PATH

Macintosh OS X

No special Java configuration is need if you run the regular installer version of geWorkbench.

In recent versions of OS X (including 10.8.5 and 10.9), the Java 6 JDK can be found in /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home. Set JAVA_HOME to this if you wish to run the generic version of geWorkbench, or the Macintosh installer version from the command line rather than the app launcher. In the latter case, see the instructions for running the generic version of geWorkbench.

A recent test on a MacBook Pro with OS X 10.9.2, which had Java 6 installed, and on which then Java 7 update 45 was also installed, showed that the installer version of geWorkbench continued to use the Java 6 installed at the location shown above. The same result was found when Java 8 update 5 was installed.

Switching between different installed JREs on Windows

The installer versions of geWorkbench on Windows will use a system-specified version of Java, typically the highest version installed. They will ignore the JAVA_HOME environment variable.

If you have multiple versions of Java installed, you can set JAVA_HOME to the desired version, and if you start geWorkbench simply by double-clicking on launch_geworkbench.bat, it will use the version of Java specified there.

Typical steps in running X-windows

Here are some typical steps to configure a remote Linux host and a local desktop X-server. Under Windows, a local X-server can be provided for example by the Cygwin package.

On the remote Linux host (assuming you are using the bash shell), issue the command

  • "export DISPLAY=(your IP):0"

where (your IP) should be substituted with the IP address of your local desktop machine.

On your local desktop machine, you may need to

  1. start the X-windows server with a command such as "startx". You may need to cd to the X11 bin directory to find this command.
  2. allow remote connections with a command such as "xhost +".

Quick Start

A Quick Start guide to geWorkbench is being developed.

Community Support Forums

geWorkbench community forums are operated by the caBIG Molecular Analysis Tools Knowledge Center. There are separate user and developer forums. Anyone can browse through existing postings, but to start a new topic one must first register.

The forums can be viewed at https://cabig-kc.nci.nih.gov/Molecular/forums/


Tutorial data

tutorial_data.zip (3.586 MB) - data files in several different formats useful for the tutorials or just trying out geWorkbench.

Bcell-100.zip (5.256 MB) - A large (100 array) microarray dataset in the geWorkbench matrix format. Data is from the lab of Riccardo Dalla-Favera, Columbia University, and is provided only for use in learning and testing geWorkbench. It was obtained from experiments using Affymetrix HG-U95Av2 chips. This file contains the same data as the previously used file "webmatrix", but with the array subsets given more descriptive names.


Training Slides

A set of PowerPoint training slides for an earlier version of geWorkbench is still available, but is of historical interest only. The PowerPoint file is available from the Project Documentation section of this site.


Download the geWorkbench Source Code

geWorkbench 2.5.0 and later on Github

Following release 2.5.0 of geWorkbench, the source code was migrated to a Github repository. geWorkbench 2.5.0 and all following releases can be obtained from there.

On Github, geWorkbench is now divided into three parts: the core, the components, and the supplemnetal files. Each project can be downloaded from the web interface by entering the particular project and pushing the button "Download ZIP".

The main project page on Github is https://github.com/geworkbench-group.

To create the fully functional geWorkbench source tree,

  1. First download and extract geworkbench-core.
  2. Then download and extract geWorkbench-components.
  3. From within geworkbench-components, move the extracted "components" directory into the core.
  4. Finally, download the two files from the geworkbench_supplemental_files project.
    1. Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
    2. VIPER - copy the file viper.tar.gz into the directory components/viper/viperScripts. You do not need to unzip it.

geWorkbench 2.4.1 and earlier on SVN

A. NOTICE - to avoid a huge download, make sure to follow all of the below instructions carefully so that you only check out the development source code, not the entire project.

Geworkbench svn checkout.png

  • For just checking out the code, you can use the username and password of anonymous/anonymous.
  • There should be no further changes in this repository.

Compiling the geWorkbench Source Code

  • you must have the Java JDK 6 installed on your machine - see http://java.oracle.com, under the "Java SE" link.
  • you must make sure that the value of the environment variable JAVA_HOME is the directory where the JDK is installed, e.g.
C:\Program Files\Java\jdk1.6.0_45

If you have Ant installed on your machine, you can just type "ant run" in the geworkbench root directory and the program will be built and run. Ant can be downloaded from http://ant.apache.org/. Note that installing Ant involves manually adding the Ant bin directory to the PATH variable, setting the ANT_HOME directory.

'Special Note for Mac Users - Ant has been removed from release 10.9 of OSX. However, you can reinstall it, either from the Apache distribution or possibly using "brew" and "xcode" (we have not tried this).