geWorkbench - User contributions [en]

Download and Installation

2016-12-22T20:50:54Z

Smith: /* geWorkbench Installation Instructions */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=Install and Run geWorkbench=

==Windows (XP/Vista/7/8/10)==
===Installation===
Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.

New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0. With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.

===Running geWorkbench on Windows===
====Installer versions====
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

====Any 64-bit version====
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - There are specific considerations for installing R on Windows Vista/7/8/10.

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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:42:49Z

Smith: /* Switching between different installed JREs on Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===
Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.

New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0. With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.

===Running geWorkbench on Windows===
====Installer versions====
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

====Any 64-bit version====
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - There are specific considerations for installing R on Windows Vista/7/8/10.

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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:41:31Z

Smith: /* R installation on Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===
Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.

New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0. With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.

===Running geWorkbench on Windows===
====Installer versions====
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

====Any 64-bit version====
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - There are specific considerations for installing R on Windows Vista/7/8/10.

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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:39:08Z

Smith: /* Installation */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===
Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.

New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0. With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.

===Running geWorkbench on Windows===
====Installer versions====
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

====Any 64-bit version====
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:36:20Z

Smith: /* Running geWorkbench on Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===
====Installer versions====
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

====Any 64-bit version====
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:33:10Z

Smith:

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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/

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=Tutorial data=

Tutorial data is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:28:30Z

Smith: /* Generic - any platform */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:26:47Z

Smith: /* Instead you can just download a zip file */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:21:14Z

Smith: /* Java Environment Configuration */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:20:53Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:15:19Z

Smith: /* geWorkbench Installation Instructions */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench Installation Instructions=

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation, or download the Zip file version and extract it.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Recent testing has been on Mac OS X 10.10+ only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T20:08:35Z

Smith: /* Operating System */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:42:36Z

Smith: /* Workaround */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:42:18Z

Smith: /* Instead you can just download a zip file */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
# You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip.

This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

# After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:41:54Z

Smith: /* Instead you can just download a zip file */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
# You can avoid the installer problems by downloading the simple Zip file
geWorkbench_v2.6.0_Windows_JRE7_x64.zip.
This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

# After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:40:24Z

Smith: /* Workaround */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
# You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip.
This file contains the 64-bit Java JRE7.

# After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:39:22Z

Smith: /* Workaround */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:38:56Z

Smith: /* If you wish to run the geWorkbench installer */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:35:56Z

Smith: /* Affected versions */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:35:26Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:34:23Z

Smith: /* Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:32:49Z

Smith: /* Linux */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory.

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:32:22Z

Smith: /* Java */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:31:40Z

Smith: /* Java */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Mac OS X, the Java 7 JRE is included in the geWorkbench installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:29:33Z

Smith: /* Generic - any platform */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB). No Java JRE is included, you must supply the appropriate JRE for your machine.

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:22:46Z

Smith: /* Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T19:22:02Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===Instead you can just download a zip file===
You can avoid the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip. This file contains the 64-bit Java JRE7.

After unzipping the file, you can double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB) Installer version with no included JRE.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T18:40:38Z

Smith: /* Running geWorkbench on Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===If you would like to just download a zip file===
You can avoid all the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip

After unzipping the file, you can choose one of the .bat files to start geWorkbench (described further below), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB) Installer version with no included JRE.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T18:36:43Z

Smith: /* Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===If you would like to just download a zip file===
You can avoid all the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip

After unzipping the file, you can choose one of the .bat files to start geWorkbench (described further below), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB) Installer version with no included JRE.

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T18:35:14Z

Smith: /* If you would like to just download a zip file */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===If you would like to just download a zip file===
You can avoid all the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x64.zip

After unzipping the file, you can choose one of the .bat files to start geWorkbench (described further below), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T16:57:19Z

Smith: /* Workaround */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
===If you wish to run the geWorkbench installer===
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.
===If you would like to just download a zip file===
You can avoid all the installer problems by downloading a simple Zip file containing geWorkbench2.6.0 and the JRE7:
geWorkbench_v2.6.0_Windows_JRE7_x86.zip

After unzipping the file, you can choose one of the .bat files to start geWorkbench (described further below), depending on how much memory you wish to request for geWorkbench.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T16:53:42Z

Smith: /* Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-22T16:48:57Z

Smith: /* Windows */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Known Issues

2016-12-22T16:29:33Z

Smith: /* Gatekeeper stops files from running */

==Installation - top issues==
===Windows platform (maybe also Linux)===
The Windows installers will not run if a version of Java higher than Java 8 update 51 is installed on the machine. For workarounds, see [[Download_and_Installation#IMPORTANT_Note_for_Windows_.28and_Linux.29|IMPORTANT Note for Windows (and_Linux)]].

===Macintosh OSX platform===
====Gatekeeper stops files from running====

The first time a downloaded file (e.g. a command file) is run, you may need to tell Gatekeeper to allow it to run. Please see instructions at [[Download_and_Installation#IMPORTANT_note_for_MacOSX| IMPORTANT note for MacOSX]].

==geWorkbench 2.6.0==
In the CNKB component, interactome export is currently only enabled for three smaller interactomes: BCi, HGi_Sun, and Geneways. Export of larger interactomes is being implemented through server-side changes and will be enabled in a subsequent update. However, export of larger interactomes directly into the Workspace is not recommended.

==geWorkbench 2.6.0 and prior==
===Housekeeping Genes Normalizer and tab-delimited expression files===
If a gene expression set is loaded into geWorkbench in tab-delimited format, the Housekeeping Genes Normalizer will not work. The workaround is to the save the data back to disk in the ".exp" format - to do this, right-click on the data node and select "Save". Then load the data back in to geWorkbench as format type ".exp". The Housekeeping Genes Normalizer can now be used.

===MarkUs===
Viewing MarkUs results directly in geWorkbench is only available when a 32-bit version of Java is being used. In all other cases, the MarkUs results can instead be opened in an external web browser. However, several steps, detailed in the [[MarkUs#Java_Requirements_for_Viewing_MarkUs_Results| MarkUs tutorial]], are necessary to set up the use of Java in the web browser.

===Cytoscape===
When a gene network node is selected (left-click) within Cytoscape, and then right-clicked on, a detailed menu of annotation choices should appear. However, if the node is in the right quarter of the display box, the gene menu instantly disappears and is replaced by the background right-click menu. May occur in this and previous releases (Mantis issue #3194). To get the menu, decrease the network size (zoom out), or move the network left.

Sometimes, the first time Cytoscape is used in geWorkbench, the lower parameter window covers the entire component, so that the network diagram is hidden. It is hard to recognize this is what has happened, but the top of the panel can just be pulled down to reveal the network.

===Use of incomplete annotation file causes errors in MRA-FET analysis===
If an annotation file is loaded along with a microarray dataset, but the annotation file does not contain entries for all markers present in the dataset, then at least for the MRA-FET analysis, an incorrect result will be obtained. Mantis issue #3839.

===PCA and 64-bit Java===
The PCA 3D visualization does not currently work when using 64-bit Java, which is now the default on all platforms. It will work if a 32-bit version of Java is used to run geWorkbench (not available for Mac OS X).

===PCA and OpenGL version===
The PCA 3D viewer requires that the computer display driver support OpenGL version 1.2 or higher. If it does not, a warning message will be displayed at the time the user attempts to create a 3D plot. Any recent graphics card should provide this support.

===BLAST===
(first reported in 2.4.1)
The NCBI BLAST server may occasionally return an error when sequences are searched from geWorkbench. The problem appears to depend on the load on the NCBI BLAST server. When multiple sequences are being submitted, geWorkbench submits them one-at-time to the BLAST server. When many sequences are submitted, it may be more likely that such a server-side problem will be encountered at some point and the search cancelled.

===Running more than one copy of geWorkbench simultaneously===
While running an analysis, some geWorkbench components write data to temporary files with non-unique names. For this reason, two copies of geWorkbench should not be running at the same time, and especially not running the same analysis.

===Embedded browser not compatible with 64-bit Java===
Affects: GSEA, MarkUs, Pudge.

Several geWorkbench components make use of a 32-bit embedded JDIC web browser. This browser will not display when using 64-bit Java JREs (now the default for geWorkbench on all platforms). If this situation is encountered, these components will instead offer a link to display the results in your computer's default web browser. However the displayed web page will not automatically update or interoperate with geWorkbench.

===Astex viewer in MarkUs===
====Windows====
The MarkUs results display includes the Astex molecular structure viewer, which is a Java applet. For this to run, a JRE must be available which matches the architecture (32 or 64-bit) of the browser being used. For Windows (as of early 2015), the default versions of Firefox and Chrome are 32-bit, so a 32-bit JRE must be installed on the computer to use this applet in the default browser versions.

As of February 2015, Chrome is available in a 64-bit version for Windows as a special download, and Firefox is planning a March release of a 64-bit version.

====Getting Java====
Particular versions of the Java JRE can be downloaded from http://java.oracle.com. 32-bit versions of the JRE include "x86" in their descriptions and "i586" in their file names. Additional information on configuring Java can be found on the [[MarkUs|MarkUs]] tutorial page.

===Cytoscape loading===
Cytoscape is by default enabled in the [[Component_Configuration_Manager|CCM]]. This is to prevent certain problems that have been seen if it is loaded later, after geWorkbench has completed its startup. If Cytoscape is unloaded and then later reloaded into the CCM, geWorkbench should be restarted. (c.f. Mantis issue #3381 and links to related issues therein).

===Mac-related issues===

====Building from source on Apple Mac OS X (tested in Lion 10.7)====
There is an issue with the Java 3D library included with Mac OS X. In order to build geWorkbench from source, one must either install certain files from J3D 1.5, or delete the PCA component from the geWorkbench components directory (#2495).
* To configure J3D on the Mac, please see the instructions below.
* To just remove the PCA component, find the geWorkbench installation directory and follow this path: components/gpmodule_v3_0/src/org/geworkbench/components/gpmodule. In the gpmodule directory, delete the folder "pca".

====Mouse-button issues (tested in OS X 10.7 Lion )====
* '''Right-click contextual menu''': On the Mac, control-click can substitute for the PC's "right-click" action, and bring up a contextual menu. However, this is not implemented in geWorkbench on the Mac. The following work-arounds are available:
** Trackpad: In System Preferences, enable "Secondary click". You can choose 3 options on how this will work, including clicking in the lower-right-hand corner of the trackpad.
** Magic Mouse: In System Preferences, enable "Secondary click".

====Cytoscape in 10.6.8====
On OSX 10.6.8, but not 10.7 or later, an extra window may pop up when a network is displayed in Cytoscape. No workaround is known.

===Grid Issues===
* For grid services hosted inside the Columbia firewall, the service metadata cannot be retrieved from outside the firewall. Instead, generic metadata will be displayed. You may see a delay of up to 30 seconds while geWorkbench attempts to retrieve the service metadata, before a timeout occurs and the generic metadata is substituted.

==Previous Releases==
For issues with previous releases, please see the [[Previous_Release_Issues| Previous Release Issues]] page.

==Configuring J3D on the Mac for gpmodule PCA==
The Java3D version included in geworkbench is 1.5. On the Mac platform, an earlier version (1.3) is installed in /System/Library/Java/Extensions/. Unless this is fixed on the user's Mac,
# geWorkbench cannot be built from source, as a compile error is generated, and
# PCA 3D plots cannot be used on the Mac when the Installer version is used.

These problems arise because the j3d libraries in the system java extension directory have higher priority than those in geworkbench.

By copying the appropriate j3d and jogl files into a directory with higher precedence, these problems can be avoided. The following steps have been tested under Mac OS X 10.7 (Lion) but should work for other versions also.

The safest method is to place the updated files within the user's own directory structure. These changes will then apply only to that user and can be easily undone if needed.

* If the directory ~/Library/Java/Extensions does not exist, create it, where "~" refers to the User's home directory.
** Note - in OS X 10.7 Lion, the ~/Library folder may be hidden by default. You can make it visible in the Finder by holding down the "option" key while selecting "Go" in the Finder menu.
** [http://osxdaily.com/2011/07/04/show-library-directory-in-mac-os-x-lion/ Alternatively], to make the ~/Library folder always visible, execute the following command in a terminal window:
chflags nohidden ~/Library/
You can undo this with
chflags hidden ~/Library

* Copy the following java3d 1.5 libs from the geworkbench installation to the java extensions directory ~/Library/Java/Extensions:
** geworkbench/lib/j3dcore.jar
** geworkbench/lib/j3dutils.jar
** geworkbench/lib/vecmath.jar

(Note - The java3d-1.5.1 files can also be downloaded from the [http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-client-419417.html#java3d-1.5.1-oth-JPR Oracle Java3D distribution site]).

* Next, [http://download.java.net/media/jogl/builds/archive/jsr-231-1.1.1/jogl-1.1.1-macosx-universal.zip download the jogl libs], then extract and copy the following files from the extracted lib directory to the your own user extensions directory ~/Library/Java/Extensions:
** gluegen-rt.jar,
** jogl.jar,
** libgluegen-rt.jnilib,
** libjogl.jnilib,
** libjogl_awt.jnilib,
** libjogl_cg.jnilib

If you have system admin privileges on the machine, you can instead update the files for all users in /Library/Java/Extensions, however we do not recommend this.

==General==
* Filtering a data set may after an analysis has already been run may invalidate objects that arose from the original, unfiltered dataset. Any filtering should be done before any analysis which creates child result nodes, e.g. a t-test, ANOVA etc.

* Promoter panel (issue #1988) - under very particular conditions, where a letter has a score and height of zero, and where an external display is being used on a Macintosh computer, a graphics error can be reported to the console. However, this error does not cause any problems.

Release Descriptions

2016-12-22T16:27:51Z

Smith: /* Summary */

==Brief overview of changes in geWorkbench release 2.6.0==

===Summary===
'''geWorkbench 2.6.0.3''' was released on December 21st, 2016 as a minor but very important update. It allows the BLAST and Sequence Retriever components to work again.

'''geWorkbench 2.6.0.2''' was released on February 20th, 2015 as a minor update.

'''geWorkbench 2.6.0.1''' was released on January 28th, 2015 as a minor update.

'''geWorkbench 2.6.0''' was released on January 22nd, 2015.

geWorkbench 2.6.0 was a major release, including more than 70 bug
fixes and other improvements to usability. All users should immediately
upgrade. Previous versions are no longer supported.

Please see the [[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench v2.6.0.3 Release Notes]] or [[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench v2.6.0.3 Change Log]] for full details of all changes.

===Java 7===
With release 2.6.0, geWorkbench requires the Java 7 Runtime Environment (JRE). Versions of geWorkbench including the 64-bit Java 7 JRE are provided for Windows, Mac and Linux. Use of the 64-bit JRE allows larger datasets to be loaded (through setting larger Java max heap sizes, described further below).

===Installation Directory===
geWorkbench no longer writes any files to its own installation directory; all files are now written to temp areas in the user's directory space. This allows geWorkbench to be installed in normal System directories, e.g. "Program Files" on Windows and the Applications folder on Mac OS X.

===Larger Java Heap Memory for larger datasets===
The default maximum Java heap size is now 2 GB for the 64-bit JRE7 installations. Using the 64-bit JRE and larger Java heap sizes allows geWorkbench to work with much larger datasets.

On machines with larger amounts of RAM, users can now easily start
geWorkbench with even higher amounts of Java Heap memory simply by clicking
on specific command files available in the geWorkbench installation
root directory (currently for Windows and Mac OS X only). These files allow
geWorkbench to be started with 1, 2, 4, 8 or 16 GB specified as the maximum
size of the Java heap memory. The user should
take care not to request more heap memory than there is physical RAM memory
available, and also to allow at least 1-2 GB for the operating system.
All heap sizes larger than 1 GB require use of a 64-bit JRE.

The Windows launcher files end in .bat, while those for Mac OS X end in
.command, e.g. "launch_geworkbench_winpc_4G.bat" and
"launch_geworkbench_macosx_4G.command". On either platform, the user can
create shortcuts to the launcher files and place the shortcuts e.g. on the
Desktop.

===BLAST===
The BLAST component now complies with a new specification from NCBI for BLAST job submissions. BLAST submissions may not work in previous releases of geWorkbench.

===R===
Several problems are fixed in how R is used from geWorkbench. The R package directory setting in the geWorkbench Preferences component is now fully implemented and overrides any setting of the environment variable R_LIBS_USER. This allows geWorkbench, if desired, to use a separate version of a package from those installed in regular R directories (e.g. geWorkbench downloads a special version of Viper).

===GenomeSpace===
Integration with GenomeSpace is greatly improved. GenomeSpace allows geWorkbench to exchange data with a number of other tools.

===CART===
Access to the GenePattern 3.0 Classification and Regression Tree (CART) component is now included.

==Brief overview of changes in geWorkbench release 2.5.1==
geWorkbench 2.5.1 was released on 11/01/2013.

geWorkbench 2.5.1 is a maintenance release. However, it includes several important bug fixes and all users should update to this release. Changes include:

* '''ARACNe''' - Exception on cancel fixed.
* '''DeMAND and VIPER''' components - Add licenses for DeMAND and VIPER (in the Component Configuration Manager).
* '''geWorkbench license file''' - Add link to new version of caArray license file.
* '''Menu Bar''' - Remove unneeded items from menus (Project, Knowledge Center).
* '''Scatter Plot''' - Array and Marker lists not populated when no sets activated.
* '''Workspace''' - Merging expression datasets in the Workspace did not work.

See also the [[Media:GeWorkbench_ReleaseNotes_2.5.1.txt | geWorkbench 2.5.1 Release Notes]].

==Brief overview of changes in geWorkbench release 2.5.0==
geWorkbench 2.5.0 was released on 10/11/2013.

The geWorkbench tutorials will be updated in the coming days to reflect the major changes.

See also the [[Media:ReleaseNotes_2.5.0.txt| Release Notes]] for an expanded list of changes.

geWorkbench 2.5.0 is a major release. Changes include:

* '''Workspace''' - The Workspace has been simplified by the removal of the "Project" level of data organization. Files and data nodes are now loaded directly into the Workspace.

[[Image:Workspace_Open_Files.png]]

[[Image:Workspace_data_node.png]]

* '''Marker Annotations''' - The Marker Annotations component was completely reimplemented to use the bioDBNet data service rather than the discontinued caBIO service.

* [[BLAST|BLAST]] - New parsing and display code was written so that all NCBI BLAST sequence alignments are now generated in geWorkbench from the BLAST results XML output file. This removes the dependency on specifics of the BLAST server HTML output.

* '''New Components'''
** [[Consensus_Clustering | Consensus Clustering (GenePattern 3.0)]] - This component implements an interface to Consensus Clustering on a GenePattern 3.0 server. Consensus Clustering uses multiple clustering runs to find consensus clusters and assess their stability.
** [[LINCS_Query | LINCS Query and Display]] - The LINCS Query component provides for query and display of computational and experimental results from the Columbia LINCS center, which performs high-throughput drug candidate prediction and screening.
** '''VIPER''' - VIPER summarizes drug activity on gene expression profiles at the level of the transcription factors.
** '''DeMAND''' - DeMAND is used to compute drug mechanism of action.
** [[ceRNA_Query | ceRNA/Hermes Query]] - The ceRNA component provides query access to a database of precomputed competitive endogenous RNA (miRNA-mRNA) interactions for four different cancer types. These interactions are computed using the Hermes algorithm.

* '''MARINa/MRA''' - The MARINa component has been separated from the MRA-FET version of Master Regulator Analysis. The "bar-code" graph first implemented in the MRA-FET Results Viewer component has now been adapted and added to the MARINa Results Viewer.

* '''Online Help''' - The "Online Help" feature has been removed. This material was identical to the geWorkbench tutorials, which are available at the geWorkbench.org website.

* '''Analysis Components''' - The "All Markers / All Arrays" checkboxes, which could be used to override marker or array set selections in the Markers/Arrays component, have been removed.

* '''ARACNe''' - The adjacency matrix, if saved to disk, is now written in the same format as used by the stand-alone version of ARACNe. Each line starts with a hub gene, followed by all of its targets.

* '''Skybase''' - Implement saving of image of histogram, and export of results to CSV file.

==Brief overview of changes in geWorkbench release 2.4.1==
Version 2.4.1 is a bug fix release to deal with a few specific issues:
* '''BLAST''' - Due to changes in the HTML output format of BLAST result pages from NCBI, results from an NCBI BLAST search could no longer be parsed into geWorkbench. geWorkbench will now rely primarily on NCBI's XML result format, which should remain more stable.
* '''ANOVA''' - A problem with activated marker sets has been corrected. Incorrect markers may have been used.
* '''Installation''' - The installer will now install geWorkbench to the user's home directory on all platforms.

geWorkbench 2.4.1 is only intended for use with Java 6. A few incompatibilities with Java 7 are known to exist.

View the [[Media:GeWorkbench_v2.4.1_ReleaseNotes.txt | geWorkbench 2.4.1 Release Notes]].

==Brief overview of changes in geWorkbench release 2.4.0==
Release Date: July 23, 2012

* '''Significance Analysis of Microarrays (SAM)''' - An interface to an R implementation of SAM has been added. The user can choose an instance of R running on his or her own desktop, or access a remote grid service version with proper authorization.
* '''Master Regulator Analysis''' - Major updates have been made to the MRA component.
** The FET-based method now has the option of performing two FET runs on orthogonal slices of the data to determine the regulatory mode of the candidate master regulators.
** The graphical result display has been completely updated. It now can display multiple bar graphs for multiple master regulator candidates, and uses a rank based ordering of the bars rather than the t-statistic value.
* '''SkyBase''' - Adds access to the much larger PDB-60 database of homology model structures. As of 7/19/2012, the databases have:
** PDB60: 12,264 structures, 7,804,258 models.
** NESG: 946 structures, 1,943,390 models.
* '''Affymetrix Human Gene ST whole-transcript''' and '''Human Exon ST annotation files''' - support has been added for Affymtrix Whole-Transcript Gene and Exon Array transcript-level annotation files. Examples include the Gene and Exon 1.0 ST arrays, and the new Gene 2.0 ST array. All whole-transcript Exon and Gene ST arrays use this format.
* '''caArray''' - The interface to caArray can now query the newly released caArray version 2.5. However, it is not backward compatible with caArray 2.4 or earlier.
* '''t-test''' - The t-test is now calculated using the Apache Commons Math Library. P-values may show slight changes due to improved precision.

Some, but not all, known incompatibilities with Java 7 have been corrected. geWorkbench 2.4.0 is only intended for use with Java 6.

View the [[Media:geWorkbench_2.4.0_ReleaseNotes.txt | geWorkbench 2.4.0 Release Notes]].

==Brief overview of changes in geWorkbench release 2.3.0==
Release Date: March 16, 2012

geWorkbench v2.3.0 introduces significant improvements in responsiveness and memory usage, and a streamlining of the
graphical interface to make using analysis, filtering, normalization and visualization components much easier.

* The analysis, filtering and visualization components are now reached through a right-click menu directly on the data node, or through the commands menu in the upper menu bar. This allowed the removal of the dedicated "commands" area from the geWorkbench graphical interface, making more room available for the display of results.

* Switching back and forth between large data nodes is now much faster.

* caArray downloads have been speeded up dramatically, and memory problems that limited the number of arrays that could be downloaded were resolved. We have test-downloaded 527 arrays of type Affymetrix HT_HG-U133A in 16 minutes with no memory problems.

* Dynamic search for marker and gene names has been added to all filtering components.

* A number of data and result export options have been added. Microarray data can now be exported to a tab-delimited file directly, or from the tabular viewer, allowing subsets of the data to be exported.

* Interactomes stored in the Cellular Network Knowledge Base can now be exported directly into the Project Folders component.

* A new component, IDEA (Interactome Dysregualtion Enrichment Analysis), is included.

==Brief overview of changes in geWorkbench release 2.2.2==
Release Date: 8/19/2011

* In the caArray download dialog, arrays are now sorted by name.
* The following problems in using the Gene Ontology components were fixed:
** Marker sets returned from the Tree Browser was not properly appearing in marker selection pulldown menus (e.g. ARACNe hub marker selection).
** After restoring a saved workspace, the reference gene list in the GO analysis component was not populated.
** In some cases, the GO Tree Browser returned markers having no EntrezID along with the expected markers.

View the [[Media:ReleaseNotes_2.2.2.txt|geWorkbench 2.2.2 Release Notes]] and the [[Media:GeWorkbench_2.2.2_Changes.txt | change list]].

geWorkbench 2.2.2 can be downloaded from the NCI GForge site at https://gforge.nci.nih.gov/frs/?group_id=78. Installation instructions can be found on the [http://wiki.c2b2.columbia.edu/workbench/index.php/Download Download and Installation] page of this Wiki. The Release Notes are also available on [https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4240 GForge].

==Brief overview of changes in geWorkbench release 2.2.1==
Release Date: 7/29/2011

This release augments the recently released version 2.2.0, and includes more than 90 additional enhancements and bug fixes, with many focused on network import, display and export, sequence retrieval, and pattern discovery. It also corrects two omissions from release 2.2.0.

* Alternate file viewer for large networks that may be too large to view in Cytoscape.
* Improvements to display of probeset-level networks.
* Networks can now be imported either from ARACNe adjacency matrix files or from SIF files. Networks can be represented by gene symbols, Entrez IDs, probeset names, or other identifiers.
* Adds support for use of alternate ontology files (e.g. from the GO website) for gene ontology analysis.
* Sequence retrieval for DNA sequences is now based on refSeq records from the UCSC refGene table, and is available for all organisms with genomes supported by UCSC.
* The new "Fold Change" analysis component, omitted from release 2.2.0, is included.
* A feature to overlay a t-test result onto a Cytoscape network, not functional as released in version 2.2.0, now works correctly.
* Bonferroni correction added to the ARACNe GUI.

For a full list of changes, see [[Media:GeWorkbench_2.2.1_Changes.txt| Changes]].

==Brief overview of changes in geWorkbench release 2.2.0==

geWorkbench 2.2.0 is a major release containing more than 180 new features, enhancements and bug fixes. The most important of each are summarize below.

===Overview of new features===
* New network comparison and manipulation features were added to the Cytoscape component,allowing comparison of CNKB interactomes to other expression datasets, projection of t-test results onto a network, and creation of subnetworks from the result of these comparisons.
* The Gene Ontology component can now serve as a full, standalone GO term browser.
* Options for import and export of interaction networks (interactomes) were added.
* Two new filters were added to give the user options to deal with many-to-many relationships between genes and markers (probesets).
* Two new analysis components were added. One calculates differential expression fold-change, and the second provides a front-end to GenePattern GSEA (Gene Set Enrichment Analysis).
* Improvements were made to the Master Regulator Analysis component - it can now accept any user-supplied list of "signature genes", and the "bar-code" display was altered to match the style used in recent publications.
* A new Social Center feature was added to the genSpace component, allowing users to directly interact with each other. Improvements in workflow
saving and visualization were also made.
* A major code refactoring was completed, simplifying a number of core data structures to improve performance and prepare for the development of a new web version.

===New features in detail===
* '''CNKB'''
** (#2389) Export complete CNKB interactomes (SIF or ADJ formats). The Cellular Network Knowledge Base (CNKB) stores a number of "interactomes" derived from computational analysis of various types of gene expression data. These interactomes, and other interaction datasets, can be queried in geWorkbench to find targets which interact with genes of interest. With this release, complete interaction networks stored in the CNKB can be exported to a file, in either SIF format or as an ARACNe-format adjacency matrix.
* '''Cytoscape'''
** (#2424) Compare differential expression results to an interaction network ("interactome"). This feature calculates the Pearson's correlation coefficient for the expression profiles of each pair of nodes connected by an edge in an interaction network. Only those portions of the network which have a correlation coefficient above a user-set threshold will be displayed.
** (#2424) Create a new subnetwork containing only edges exceeding the calculated correlation threshold.
** (#2429) From an existing network, create a subnetwork containing only nodes in a marker set defined in the Markers component.
* '''File Parsers'''
** (#2388) Import an ARACNe adjacency matrix from a file. Either gene symbols or probeset names can be used.
* '''Filters'''
** '''Multiple probeset per gene filter''' (#2444) - For genes with multiple probesets (markers), retain only the probeset with: (a) highest coefficient of variation, (b) highest mean, or (c) highest median expression across all arrays.
** '''Multiple Entrez GeneID Filter''' (#2445) - Filter out markers which are annotated to (a) no Entrez gene id, or (b) multiple Entrez gene ids.
* '''Fold-change Analysis'''
** (#2431) This is a new component that performs fold-change analysis and places markers that pass the specified threshold into two new sets in the Markers component, one for markers with positive fold-change, and the other for those with negative fold-change.
* '''Gene Ontology'''
** The Gene Ontology component is now always available when a microarray dataset has been loaded along with its annotation file. The GO Tree can be browsed or searched for any term. The markers annotated to any term can be returned to a new set in the Markers component.
** (#1875) The most recent Gene Ontology OBO file is now downloaded automatically from the internet when geWorkbench is started, with the option to instead load a specified OBO file from disk.
* '''GenePattern GSEA'''
** A front-end to GSEA running on any GenePattern server has been added.
* '''genSpace'''
** A new social networking feature, the Social Center, has been implemented, allowing users to directly interact with friends or create networks (chat and share).
** Users can now create their own Workflow Repository, where they can collect and comment on their favorite workflows.
** The GUIs for Workflow Visualization, Real Time Workflow Suggestion and Workflow Statistics have been updated.
* '''Master Regulator Analyis''' (#2523 and others)
** Allow any user-supplied list of markers to be used for the phenotype signature.
** Bar-code graph revised to match style of published work.

===Other Enhancements/Fixes===
* '''ARACNe'''
** (#2366) - In ARACNe, bootstrapping is re-enabled but only single threaded.
** (#2482) - ARACNe results can now be pruned to retain only highest MI edge per gene-gene pair, or return all edges.
* '''BLAST''' (#2419) - Continued improvements to BLAST interface to match NCBI website functionality and to improve usability.
* '''CCM''' - "Sequence Analysis" has been retitled as "BLAST Analysis", "Alignment Viewer" has been retitled as BLAST Alignment Viewer.
* '''Gene Ontology Viewer''' (#2391) - When a marker set is returned for a GO term, the set is given the term name.
* '''GEO Soft''' (#2402, #2462, #2465) - GEO Soft parsers improved to handle various special cases - multiple platforms, missing values, mixed sample and data matrix files...
* '''Grid Services''' (#1773) - Simplified grid service activation (removed one radio button).
* '''JMOL''' (#2505) - Updated to JMOL version 12.0.35.
* '''Markers/Arrays component''' (#2430) - Dynamic filtering of displayed marker or array list as search term is entered.
* '''MarkUs'''
** (#2500) - Add ability to retrieve prior MarkUs jobs by job id
** (#2509) - Add private key option to MarkUs job submission
* '''MINDy''' (#2214) - Corrected sign of modulation effect in table displays.
* '''Pattern Discovery''' (#2119) - Corrected display problems in Pattern Discovery related to regular expressions and use of substitution matrices.
* '''Preferences''' (#2393) - Added ability to reorder data sorted by marker name, gene name, or original order (set in preferences, affects all components).
* '''Sequence Retriever''' (#2518) - Fixed problem with obtaining name of latest human genome build from Santa Cruz.
* '''Tabular Microarray Viewer'''(#2253) - Tabular Microarray viewer now allows adjustable precision in display, and choice of fixed or scientific notation.
* '''t-test''' (#1626) - Changed math package used in order to correct precision problem with p-value calculation at very small p-values.
* '''Volcano Plot''' (#2492) - extreme point color range corrected.

===Changes to documentation (Tutorial sections)===
Note - not all of the new features described above have been documented as of the release date, but they will be added as quickly as possible to the tutorial chapters on this website.

* '''ARACNe'''
** Corrected and improved descriptions of DPI Tolerance and DPI Target List.
** Added Technical Notes section and usage notes.
** Mapped relationship of ARACNe command line options -s and -l to ARACNe in geWorkbench.
** Rewrote introduction.
* '''CNKB''' - all screenshots on tutorial page updated to reflect
** Interactome and version details display.
** Illustration of new display options in Cytoscape (see below).
* '''Cytoscape''' - Added new section to show all new features for release 2.2
** Correlation Overlay,
** t-test overlay,
** subnetwork creation,
** interaction type coloring etc.
* '''Data Subsets - Arrays'''
** Many new and revised screenshots added.
** Added new full section on visual properties editor.
** Now call the collections of sets "Lists" (pulldown menu entries).
** Much material was previously in a separate "Examples" section; this has now all been moved into the primary description of each menu item.
* '''Data Subsets - Markers'''
** All the same changes made to "Data Subsets - Arrays" were also made to "Data Subsets - Markers".
** Material unique to the Markers component was added as needed.
* '''File Formats''' - Error dialog offering 3 choices of action when duplicate entries are encountered in an annotation file (#1624).
* '''Local Data files''' - full update, including
** updated descriptions of GEO files.
** updated screenshots and descriptions,
** added additional material about file browser, merging, annotation files....
* '''Menu Bar''' - New tutorial written to cover all actions available in the top level menu bar.
* '''Pattern Discovery''' - all screenshots replaced. Changes reflect:
** Fixed display of regular expression matches in Full Sequence view after running with "Exact" unchecked.
** Better illustration of multiple pattern displays in viewer.
** In Advanced tab, matrix and threshold settings now disabled when "Exact" is checked.
* '''Projects'''
** Improved descriptions and added additional screenshots throughout
** Added missing options such as RCSB PDB.
** Add new section on Workspaces
* '''SVM''' - all new chapter written. It is updated to reflect small changes to the Test tab GUI.
* '''t-test'''
** Fully revised all sections.
** Added sections on Volcano Plot and Color Mosaic

==Brief overview of changes in geWorkbench release 2.1.0==
Release Date: September 10, 2010.

* '''BLAST'''
** A major upgrade of the built-in BLAST interface now provides almost all query options available on the NCBI BLAST website.
** geWorkbench can retrieve full or partial sequences for BLAST hits.
A recent change at NCBI caused this to stop working. This is fixed in this release.
* '''Filtering '''
** A new Coefficient of Variation data filter has been added. This scales expression profile standard deviations by their means, so that profiles can be filtered on a directly comparable measure of variation.
* '''Gene Ontology''' expandable tree views were added to the
** Gene Ontology Enrichment viewer
** Cellular Network Knowledge Base (CNKB) viewer
* '''System Information tool'''
** A menu item was added which provides system information such as Java memory allocated and used, path to the current JRE, and Operating System details.
* '''Arrays component'''
** The members of an array set can now be saved as a list to a file on disk, matching functionality already present for markers.
* '''Online Help''' chapter updates (help files built-in to geWorkbench)
** BLAST (Sequence Alignment component) – fully revised.
** Filtering - added section for Coefficient of Variation filter.
** MINDy - added section on using ARACNe preprocessing.
** Pattern Discovery – fully revised.
* '''Cytoscape component'''
** Updated to Cytoscape version 2.7.0.
* '''Bugs'''
** A number of bugs were fixed; full details are available in the Release Notes.
* '''Refactoring'''
** A project of ongoing refactoring and simplification was continued in order to enhance long-term maintainability and performance of the code.

==Brief overview of changes in geWorkbench release 2.0.2==
Release Date: July 16, 2010.

* Fixed problem with genSpace logging.
* Fully revised Online Help chapter for MINDy.

==Brief overview of changes in geWorkbench release 2.0.1==
Release Date: June 25, 2010

* Fixed a problem with caGrid connectivity.
* Fully revised Online Help chapter for the Cellular Networks Knowledge Base (CNKB) component.

==Brief overview of changes in geWorkbench release 2.0.0==
Release Date: June 9th, 2010

===Major new features===
* '''Filtering''' - completely revamped - now works directly for all modes, allows specification of minimum % matching arrays before filtering occurs.
* '''File parsers added''':
** '''MAGE-TAB data matix'''
** '''GEO Soft''' format - added series (GSE) and curated matrix (GDS).
* '''Java 6''' - Moved from Java 5 to Java 6. geWorkbench now requires Java 6. Works on both 32 bit and 64 bit VMs (JREs).
* '''Look and Feel''' - Switched to new, more modern Look and Feel (Nimbus). geWorkbench appearance now consistent across all platforms.
* '''caBIO''' component updated from 4.2 to 4.3.
* '''Cellular Network Knowledge Base (CNKB)''' - Revamped interface to allow choice of interactome and data types.
* More than 250 additional "bug reports" were closed. These included improvements in the usability of numerous components, and actual bug fixes.

===New Components===
* '''Skybase''' - SkyBase is a database that stores the homology models built by SkyLine analysis for all NESG PSI2 protein structures. It is queried using FASTA-format protein sequence files.
* '''Skyline''' - A high-throughput comparative modeling pipeline. It creates structural homology models for protein sequences with similarity to a protein with an experimentally determined 3-D structure. The input is a PDB file. (Depends on an internal server, external use not yet enabled).
* '''Pudge''' - Interface to a protein structure prediction server which integrates tools used at different stages of the structural prediction process. Modeling starts with a FASTA-format protein sequence file.

===Other major changes===
* '''caArray''' - Improved memory usage on downloads from caArray.
* '''CNKB''' - Can now return markers direct from CNKB without use of Cytoscape.
* '''Color Mosaic''' - enhancements to display (bug 2147):
** toggle array names on/off
** search on array name, accession, or label
* '''Component Configuration Manager''' - now can filter display list by categories: Analysis, Viewer, Normalizer, Filter.
* '''Cytoscape''' - Corrected mapping between gene names in Cytoscape display and markers in Marker Sets panel (now uses Entrez IDs).
* '''Dendrogram''' - can now create Array subsets as well as marker subsets.
* '''Markers and Arrays''' - Hover text available in Markers and Arrays phenotypes to visualize long names if needed.
* '''Marker Annotation''' - search results can be saved to a text file, including relevant URLs and pathway BioCarta pathway names.
* '''File loading''' - Checking for "out of memory" errors during file loading.
* '''GUI''' - in switching to new Look and Feel, fixed many text highlighting problems that were previously seen on Macintosh only but now appeared on Windows also.
* '''File parser menu''' - The file parser selection menu now shows valid file extensions for each type.
* '''Promoter''' - JASPAR promoter motifs now filterable by taxon.
* '''Sequence alignment (BLAST)''' - many enhancements, including added additional databases to match those listed at NCBI improved handling of results from searches containing long query sequences.

==Brief overview of changes in geWorkbench release 1.8.0==

geWorkbench version 1.8.0 was released on November 5, 2009.

geWorkbench 1.8.0 adds one new component for calculating Gene Ontology enrichment using Ontologizer 2.0. It also has been updated to connect with the new caArray 2.3.0 Java API. However, geWorkbench 1.8.0 is not backward compatible with earlier versions of caArray.

The geWorkbench 1.8.0. release notes are available at [https://gforge.nci.nih.gov/frs/shownotes.php?release_id=3638 Release Notes]

The geWorkbench application can be downloaded from [https://gforge.nci.nih.gov/frs/?group_id=78 NCI's GForge site].

===Major new features in 1.8.0===

Gene Ontology Enrichment - A new pair of components, called GO Terms Analysis and GO Terms Visualization have been released. The Analysis component is built on Ontologizer 2.0. This component performs "overrepresentation analysis" on a supplied list of genes. It offers a number of advanced methods through the Ontologzier 2.0 engine.

===Other changes in release 1.8.0===
# caArray - Update caArray component to use caArray 2.3.0 Java API. Please note that geWorkbench 1.8.0 is not compatible with earlier versions of caArray.
# CNKB - The network graph generated by CNKB was only showing nodes centered about a focus node. Now all accepted nodes will be displayed.
# Dataset History - Additions for several modules.
# Grid Services - A number of fixes to grid services were made.
# Marker Annotations - Fixed a problem with retrieving marker annotations when microarray data downloaded from caArray.
# Mark-Us - JMOL dependency added for molecule display.
# Promoter - Update JASPAR motifs to release of December 2007. -Note on October 12, 2009 a new version of JASPAR was released which made an incompatible change in the file format.
# Promoter - component now displays logos using the "Schneider" method, including his "small-value correction", rather than using a previous "in-house" method.
# Promoter - the displayed data now does not include the effects of the pseudo-count normalization process.
# Promoter - Added ability to specify pseudocount or select previous hard-coded option of square root of number of sequences.
# Promoter - Loaded TFs now are properly added to the list of available TFs.
# Sequence Alignment (BLAST) - PFP filtering option removed
# Usability fixes - operation of cancel buttons, progress bar.
# Release Notes - Added specific installation instructions.

==Brief overview of changes in geWorkbench release 1.7.0==
===Major new features in 1.7.0===
* '''Marker Annotations''' - The Marker Annotations component now includes direct access to NCI Cancer Gene Index annotations. It supplies detailed literature-based annotations on a curated set of cancer-related genes.
* '''Grid Services''' - All geWorkbench grid services were updated to use caGrid v1.3, with caTransfer used for transferring large data sets.
* '''ARACNe2''' - cellular regulatory network reverse engineering - This release includes a new version of ARACNe, called ARACNe2, from the lab of Andrea Califano at Columbia University. The new version adds the option to preprocess the user's dataset to obtain optimal runtime parameters. It also adds a new algorithm, Adaptive Partitioning, for calculating the mutual information between gene expression profiles. Adaptive partitioning is much faster and is considered to be more accurate than the previous algorithm.
* '''Component Configuration Manager (CCM)''' - The CCM allows individual components to be loaded and unloaded as desired, allowing geWorkbench to be customized to your needs.
* '''genSpace''' collaborative framework - discovery and visualization of workflows. Implemented user registration, preferences, and enhancements to function.

===Newly released analysis components in 1.7.0===

* '''MarkUs''' - The MarkUs component assists in the assessment of the biochemical function for a given protein structure. It serves as an interface to the Mark-Us web server at Columbia. Mark-Us identifies related protein structures and sequences, detects protein cavities, and calculates the surface electrostatic potentials and amino acid conservation profile.
* '''MRA''' - The Master Regulator Analysis component attempts to identify transcription factors which control the regulation of a set of differentially expressed target genes (TGs). Differential expression is determined using a t-test on microarray gene expression profiles from 2 cellular phenotypes, e.g. experimental and control.
* '''Pudge''' - Interface to a protein structure prediction server (developed in the lab of Barry Honig at Columbia University) which integrates tools used at different stages of the structural prediction process.
* '''SVM 3.0''' (GenePattern) - Support Vector Machines for classification. Provides an interface to remote execution on a GenePattern server.

===Other changes in release 1.7.0===

* Analysis - Parameter saving implemented in all components. If current settings match a saved set, it is highlighted.
* ARACNe - improved description of DPI in Online Help.
* caArray - query filtering on Array Provider, Organism and Investigator implemented.
* caArray - can now add a local annotation file to caArray data downloads.
* caGrid - caGrid connectivity is now built directly in to supported components rather than being a separate component itself.
* caScript - The caScript editor is no longer supported.
* Color Mosaic - now interactive with the Marker Sets list and Selection set.
* Cytoscape - Upgrade to Cytoscape version 2.4 for network visualization and interaction.
* Cytoscape - Set operations on genes being returned from Cytoscape network visualizations, via right-click menu.
* Cytoscape - Changes to tag-for-visualization - e.g., now only one way, from marker set to Cytoscape, not vice-versa.
* File loading - PDB protein structure files can now be loaded directly from the PDB database by structure name.
* Gene Ontology file - the OBO 1.2 file format is supported.
* Marker Annotations - add export to CSV file.
* Marker Sets component - a set copy function was added.
* MINDy - many improvements to display and results filtering - including marker set filtering.
* Scatter Plot - Up to 100 overlapping points can be displayed in a single tooltip.
* Various - A number of components were refactored.
* Workspace saving - now works properly for all components.

File:GeWorkbench v2.6.0.3 ChangeLog.txt

2016-12-21T21:14:00Z

Smith:

Release Descriptions

2016-12-21T21:06:58Z

Smith: /* Summary */

==Brief overview of changes in geWorkbench release 2.6.0==

===Summary===
geWorkbench 2.6.0.3 was released on December 21st, 2016 as a minor but very important update. It allows the BLAST and Sequence Retriever components to work again.

geWorkbench 2.6.0.2 was released on February 20th, 2015 as a minor update.

geWorkbench 2.6.0.1 was released on January 28th, 2015 as a minor update.

geWorkbench 2.6.0 was released on January 22nd, 2015.

geWorkbench 2.6.0 was a major release, including more than 70 bug
fixes and other improvements to usability. All users should immediately
upgrade. Previous versions are no longer supported.

Please see the [[Media:GeWorkbench_v2.6.0.2_ReleaseNotes.txt | geWorkbench v2.6.0.2 Release Notes]] or [[Media:GeWorkbench_v2.6.0.2_ChangeLog.txt | geWorkbench v2.6.0.2 Change Log]] for full details of all changes.

===Java 7===
With release 2.6.0, geWorkbench requires the Java 7 Runtime Environment (JRE). Versions of geWorkbench including the 64-bit Java 7 JRE are provided for Windows, Mac and Linux. Use of the 64-bit JRE allows larger datasets to be loaded (through setting larger Java max heap sizes, described further below).

===Installation Directory===
geWorkbench no longer writes any files to its own installation directory; all files are now written to temp areas in the user's directory space. This allows geWorkbench to be installed in normal System directories, e.g. "Program Files" on Windows and the Applications folder on Mac OS X.

===Larger Java Heap Memory for larger datasets===
The default maximum Java heap size is now 2 GB for the 64-bit JRE7 installations. Using the 64-bit JRE and larger Java heap sizes allows geWorkbench to work with much larger datasets.

On machines with larger amounts of RAM, users can now easily start
geWorkbench with even higher amounts of Java Heap memory simply by clicking
on specific command files available in the geWorkbench installation
root directory (currently for Windows and Mac OS X only). These files allow
geWorkbench to be started with 1, 2, 4, 8 or 16 GB specified as the maximum
size of the Java heap memory. The user should
take care not to request more heap memory than there is physical RAM memory
available, and also to allow at least 1-2 GB for the operating system.
All heap sizes larger than 1 GB require use of a 64-bit JRE.

The Windows launcher files end in .bat, while those for Mac OS X end in
.command, e.g. "launch_geworkbench_winpc_4G.bat" and
"launch_geworkbench_macosx_4G.command". On either platform, the user can
create shortcuts to the launcher files and place the shortcuts e.g. on the
Desktop.

===BLAST===
The BLAST component now complies with a new specification from NCBI for BLAST job submissions. BLAST submissions may not work in previous releases of geWorkbench.

===R===
Several problems are fixed in how R is used from geWorkbench. The R package directory setting in the geWorkbench Preferences component is now fully implemented and overrides any setting of the environment variable R_LIBS_USER. This allows geWorkbench, if desired, to use a separate version of a package from those installed in regular R directories (e.g. geWorkbench downloads a special version of Viper).

===GenomeSpace===
Integration with GenomeSpace is greatly improved. GenomeSpace allows geWorkbench to exchange data with a number of other tools.

===CART===
Access to the GenePattern 3.0 Classification and Regression Tree (CART) component is now included.

==Brief overview of changes in geWorkbench release 2.5.1==
geWorkbench 2.5.1 was released on 11/01/2013.

geWorkbench 2.5.1 is a maintenance release. However, it includes several important bug fixes and all users should update to this release. Changes include:

* '''ARACNe''' - Exception on cancel fixed.
* '''DeMAND and VIPER''' components - Add licenses for DeMAND and VIPER (in the Component Configuration Manager).
* '''geWorkbench license file''' - Add link to new version of caArray license file.
* '''Menu Bar''' - Remove unneeded items from menus (Project, Knowledge Center).
* '''Scatter Plot''' - Array and Marker lists not populated when no sets activated.
* '''Workspace''' - Merging expression datasets in the Workspace did not work.

See also the [[Media:GeWorkbench_ReleaseNotes_2.5.1.txt | geWorkbench 2.5.1 Release Notes]].

==Brief overview of changes in geWorkbench release 2.5.0==
geWorkbench 2.5.0 was released on 10/11/2013.

The geWorkbench tutorials will be updated in the coming days to reflect the major changes.

See also the [[Media:ReleaseNotes_2.5.0.txt| Release Notes]] for an expanded list of changes.

geWorkbench 2.5.0 is a major release. Changes include:

* '''Workspace''' - The Workspace has been simplified by the removal of the "Project" level of data organization. Files and data nodes are now loaded directly into the Workspace.

[[Image:Workspace_Open_Files.png]]

[[Image:Workspace_data_node.png]]

* '''Marker Annotations''' - The Marker Annotations component was completely reimplemented to use the bioDBNet data service rather than the discontinued caBIO service.

* [[BLAST|BLAST]] - New parsing and display code was written so that all NCBI BLAST sequence alignments are now generated in geWorkbench from the BLAST results XML output file. This removes the dependency on specifics of the BLAST server HTML output.

* '''New Components'''
** [[Consensus_Clustering | Consensus Clustering (GenePattern 3.0)]] - This component implements an interface to Consensus Clustering on a GenePattern 3.0 server. Consensus Clustering uses multiple clustering runs to find consensus clusters and assess their stability.
** [[LINCS_Query | LINCS Query and Display]] - The LINCS Query component provides for query and display of computational and experimental results from the Columbia LINCS center, which performs high-throughput drug candidate prediction and screening.
** '''VIPER''' - VIPER summarizes drug activity on gene expression profiles at the level of the transcription factors.
** '''DeMAND''' - DeMAND is used to compute drug mechanism of action.
** [[ceRNA_Query | ceRNA/Hermes Query]] - The ceRNA component provides query access to a database of precomputed competitive endogenous RNA (miRNA-mRNA) interactions for four different cancer types. These interactions are computed using the Hermes algorithm.

* '''MARINa/MRA''' - The MARINa component has been separated from the MRA-FET version of Master Regulator Analysis. The "bar-code" graph first implemented in the MRA-FET Results Viewer component has now been adapted and added to the MARINa Results Viewer.

* '''Online Help''' - The "Online Help" feature has been removed. This material was identical to the geWorkbench tutorials, which are available at the geWorkbench.org website.

* '''Analysis Components''' - The "All Markers / All Arrays" checkboxes, which could be used to override marker or array set selections in the Markers/Arrays component, have been removed.

* '''ARACNe''' - The adjacency matrix, if saved to disk, is now written in the same format as used by the stand-alone version of ARACNe. Each line starts with a hub gene, followed by all of its targets.

* '''Skybase''' - Implement saving of image of histogram, and export of results to CSV file.

==Brief overview of changes in geWorkbench release 2.4.1==
Version 2.4.1 is a bug fix release to deal with a few specific issues:
* '''BLAST''' - Due to changes in the HTML output format of BLAST result pages from NCBI, results from an NCBI BLAST search could no longer be parsed into geWorkbench. geWorkbench will now rely primarily on NCBI's XML result format, which should remain more stable.
* '''ANOVA''' - A problem with activated marker sets has been corrected. Incorrect markers may have been used.
* '''Installation''' - The installer will now install geWorkbench to the user's home directory on all platforms.

geWorkbench 2.4.1 is only intended for use with Java 6. A few incompatibilities with Java 7 are known to exist.

View the [[Media:GeWorkbench_v2.4.1_ReleaseNotes.txt | geWorkbench 2.4.1 Release Notes]].

==Brief overview of changes in geWorkbench release 2.4.0==
Release Date: July 23, 2012

* '''Significance Analysis of Microarrays (SAM)''' - An interface to an R implementation of SAM has been added. The user can choose an instance of R running on his or her own desktop, or access a remote grid service version with proper authorization.
* '''Master Regulator Analysis''' - Major updates have been made to the MRA component.
** The FET-based method now has the option of performing two FET runs on orthogonal slices of the data to determine the regulatory mode of the candidate master regulators.
** The graphical result display has been completely updated. It now can display multiple bar graphs for multiple master regulator candidates, and uses a rank based ordering of the bars rather than the t-statistic value.
* '''SkyBase''' - Adds access to the much larger PDB-60 database of homology model structures. As of 7/19/2012, the databases have:
** PDB60: 12,264 structures, 7,804,258 models.
** NESG: 946 structures, 1,943,390 models.
* '''Affymetrix Human Gene ST whole-transcript''' and '''Human Exon ST annotation files''' - support has been added for Affymtrix Whole-Transcript Gene and Exon Array transcript-level annotation files. Examples include the Gene and Exon 1.0 ST arrays, and the new Gene 2.0 ST array. All whole-transcript Exon and Gene ST arrays use this format.
* '''caArray''' - The interface to caArray can now query the newly released caArray version 2.5. However, it is not backward compatible with caArray 2.4 or earlier.
* '''t-test''' - The t-test is now calculated using the Apache Commons Math Library. P-values may show slight changes due to improved precision.

Some, but not all, known incompatibilities with Java 7 have been corrected. geWorkbench 2.4.0 is only intended for use with Java 6.

View the [[Media:geWorkbench_2.4.0_ReleaseNotes.txt | geWorkbench 2.4.0 Release Notes]].

==Brief overview of changes in geWorkbench release 2.3.0==
Release Date: March 16, 2012

geWorkbench v2.3.0 introduces significant improvements in responsiveness and memory usage, and a streamlining of the
graphical interface to make using analysis, filtering, normalization and visualization components much easier.

* The analysis, filtering and visualization components are now reached through a right-click menu directly on the data node, or through the commands menu in the upper menu bar. This allowed the removal of the dedicated "commands" area from the geWorkbench graphical interface, making more room available for the display of results.

* Switching back and forth between large data nodes is now much faster.

* caArray downloads have been speeded up dramatically, and memory problems that limited the number of arrays that could be downloaded were resolved. We have test-downloaded 527 arrays of type Affymetrix HT_HG-U133A in 16 minutes with no memory problems.

* Dynamic search for marker and gene names has been added to all filtering components.

* A number of data and result export options have been added. Microarray data can now be exported to a tab-delimited file directly, or from the tabular viewer, allowing subsets of the data to be exported.

* Interactomes stored in the Cellular Network Knowledge Base can now be exported directly into the Project Folders component.

* A new component, IDEA (Interactome Dysregualtion Enrichment Analysis), is included.

==Brief overview of changes in geWorkbench release 2.2.2==
Release Date: 8/19/2011

* In the caArray download dialog, arrays are now sorted by name.
* The following problems in using the Gene Ontology components were fixed:
** Marker sets returned from the Tree Browser was not properly appearing in marker selection pulldown menus (e.g. ARACNe hub marker selection).
** After restoring a saved workspace, the reference gene list in the GO analysis component was not populated.
** In some cases, the GO Tree Browser returned markers having no EntrezID along with the expected markers.

View the [[Media:ReleaseNotes_2.2.2.txt|geWorkbench 2.2.2 Release Notes]] and the [[Media:GeWorkbench_2.2.2_Changes.txt | change list]].

geWorkbench 2.2.2 can be downloaded from the NCI GForge site at https://gforge.nci.nih.gov/frs/?group_id=78. Installation instructions can be found on the [http://wiki.c2b2.columbia.edu/workbench/index.php/Download Download and Installation] page of this Wiki. The Release Notes are also available on [https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4240 GForge].

==Brief overview of changes in geWorkbench release 2.2.1==
Release Date: 7/29/2011

This release augments the recently released version 2.2.0, and includes more than 90 additional enhancements and bug fixes, with many focused on network import, display and export, sequence retrieval, and pattern discovery. It also corrects two omissions from release 2.2.0.

* Alternate file viewer for large networks that may be too large to view in Cytoscape.
* Improvements to display of probeset-level networks.
* Networks can now be imported either from ARACNe adjacency matrix files or from SIF files. Networks can be represented by gene symbols, Entrez IDs, probeset names, or other identifiers.
* Adds support for use of alternate ontology files (e.g. from the GO website) for gene ontology analysis.
* Sequence retrieval for DNA sequences is now based on refSeq records from the UCSC refGene table, and is available for all organisms with genomes supported by UCSC.
* The new "Fold Change" analysis component, omitted from release 2.2.0, is included.
* A feature to overlay a t-test result onto a Cytoscape network, not functional as released in version 2.2.0, now works correctly.
* Bonferroni correction added to the ARACNe GUI.

For a full list of changes, see [[Media:GeWorkbench_2.2.1_Changes.txt| Changes]].

==Brief overview of changes in geWorkbench release 2.2.0==

geWorkbench 2.2.0 is a major release containing more than 180 new features, enhancements and bug fixes. The most important of each are summarize below.

===Overview of new features===
* New network comparison and manipulation features were added to the Cytoscape component,allowing comparison of CNKB interactomes to other expression datasets, projection of t-test results onto a network, and creation of subnetworks from the result of these comparisons.
* The Gene Ontology component can now serve as a full, standalone GO term browser.
* Options for import and export of interaction networks (interactomes) were added.
* Two new filters were added to give the user options to deal with many-to-many relationships between genes and markers (probesets).
* Two new analysis components were added. One calculates differential expression fold-change, and the second provides a front-end to GenePattern GSEA (Gene Set Enrichment Analysis).
* Improvements were made to the Master Regulator Analysis component - it can now accept any user-supplied list of "signature genes", and the "bar-code" display was altered to match the style used in recent publications.
* A new Social Center feature was added to the genSpace component, allowing users to directly interact with each other. Improvements in workflow
saving and visualization were also made.
* A major code refactoring was completed, simplifying a number of core data structures to improve performance and prepare for the development of a new web version.

===New features in detail===
* '''CNKB'''
** (#2389) Export complete CNKB interactomes (SIF or ADJ formats). The Cellular Network Knowledge Base (CNKB) stores a number of "interactomes" derived from computational analysis of various types of gene expression data. These interactomes, and other interaction datasets, can be queried in geWorkbench to find targets which interact with genes of interest. With this release, complete interaction networks stored in the CNKB can be exported to a file, in either SIF format or as an ARACNe-format adjacency matrix.
* '''Cytoscape'''
** (#2424) Compare differential expression results to an interaction network ("interactome"). This feature calculates the Pearson's correlation coefficient for the expression profiles of each pair of nodes connected by an edge in an interaction network. Only those portions of the network which have a correlation coefficient above a user-set threshold will be displayed.
** (#2424) Create a new subnetwork containing only edges exceeding the calculated correlation threshold.
** (#2429) From an existing network, create a subnetwork containing only nodes in a marker set defined in the Markers component.
* '''File Parsers'''
** (#2388) Import an ARACNe adjacency matrix from a file. Either gene symbols or probeset names can be used.
* '''Filters'''
** '''Multiple probeset per gene filter''' (#2444) - For genes with multiple probesets (markers), retain only the probeset with: (a) highest coefficient of variation, (b) highest mean, or (c) highest median expression across all arrays.
** '''Multiple Entrez GeneID Filter''' (#2445) - Filter out markers which are annotated to (a) no Entrez gene id, or (b) multiple Entrez gene ids.
* '''Fold-change Analysis'''
** (#2431) This is a new component that performs fold-change analysis and places markers that pass the specified threshold into two new sets in the Markers component, one for markers with positive fold-change, and the other for those with negative fold-change.
* '''Gene Ontology'''
** The Gene Ontology component is now always available when a microarray dataset has been loaded along with its annotation file. The GO Tree can be browsed or searched for any term. The markers annotated to any term can be returned to a new set in the Markers component.
** (#1875) The most recent Gene Ontology OBO file is now downloaded automatically from the internet when geWorkbench is started, with the option to instead load a specified OBO file from disk.
* '''GenePattern GSEA'''
** A front-end to GSEA running on any GenePattern server has been added.
* '''genSpace'''
** A new social networking feature, the Social Center, has been implemented, allowing users to directly interact with friends or create networks (chat and share).
** Users can now create their own Workflow Repository, where they can collect and comment on their favorite workflows.
** The GUIs for Workflow Visualization, Real Time Workflow Suggestion and Workflow Statistics have been updated.
* '''Master Regulator Analyis''' (#2523 and others)
** Allow any user-supplied list of markers to be used for the phenotype signature.
** Bar-code graph revised to match style of published work.

===Other Enhancements/Fixes===
* '''ARACNe'''
** (#2366) - In ARACNe, bootstrapping is re-enabled but only single threaded.
** (#2482) - ARACNe results can now be pruned to retain only highest MI edge per gene-gene pair, or return all edges.
* '''BLAST''' (#2419) - Continued improvements to BLAST interface to match NCBI website functionality and to improve usability.
* '''CCM''' - "Sequence Analysis" has been retitled as "BLAST Analysis", "Alignment Viewer" has been retitled as BLAST Alignment Viewer.
* '''Gene Ontology Viewer''' (#2391) - When a marker set is returned for a GO term, the set is given the term name.
* '''GEO Soft''' (#2402, #2462, #2465) - GEO Soft parsers improved to handle various special cases - multiple platforms, missing values, mixed sample and data matrix files...
* '''Grid Services''' (#1773) - Simplified grid service activation (removed one radio button).
* '''JMOL''' (#2505) - Updated to JMOL version 12.0.35.
* '''Markers/Arrays component''' (#2430) - Dynamic filtering of displayed marker or array list as search term is entered.
* '''MarkUs'''
** (#2500) - Add ability to retrieve prior MarkUs jobs by job id
** (#2509) - Add private key option to MarkUs job submission
* '''MINDy''' (#2214) - Corrected sign of modulation effect in table displays.
* '''Pattern Discovery''' (#2119) - Corrected display problems in Pattern Discovery related to regular expressions and use of substitution matrices.
* '''Preferences''' (#2393) - Added ability to reorder data sorted by marker name, gene name, or original order (set in preferences, affects all components).
* '''Sequence Retriever''' (#2518) - Fixed problem with obtaining name of latest human genome build from Santa Cruz.
* '''Tabular Microarray Viewer'''(#2253) - Tabular Microarray viewer now allows adjustable precision in display, and choice of fixed or scientific notation.
* '''t-test''' (#1626) - Changed math package used in order to correct precision problem with p-value calculation at very small p-values.
* '''Volcano Plot''' (#2492) - extreme point color range corrected.

===Changes to documentation (Tutorial sections)===
Note - not all of the new features described above have been documented as of the release date, but they will be added as quickly as possible to the tutorial chapters on this website.

* '''ARACNe'''
** Corrected and improved descriptions of DPI Tolerance and DPI Target List.
** Added Technical Notes section and usage notes.
** Mapped relationship of ARACNe command line options -s and -l to ARACNe in geWorkbench.
** Rewrote introduction.
* '''CNKB''' - all screenshots on tutorial page updated to reflect
** Interactome and version details display.
** Illustration of new display options in Cytoscape (see below).
* '''Cytoscape''' - Added new section to show all new features for release 2.2
** Correlation Overlay,
** t-test overlay,
** subnetwork creation,
** interaction type coloring etc.
* '''Data Subsets - Arrays'''
** Many new and revised screenshots added.
** Added new full section on visual properties editor.
** Now call the collections of sets "Lists" (pulldown menu entries).
** Much material was previously in a separate "Examples" section; this has now all been moved into the primary description of each menu item.
* '''Data Subsets - Markers'''
** All the same changes made to "Data Subsets - Arrays" were also made to "Data Subsets - Markers".
** Material unique to the Markers component was added as needed.
* '''File Formats''' - Error dialog offering 3 choices of action when duplicate entries are encountered in an annotation file (#1624).
* '''Local Data files''' - full update, including
** updated descriptions of GEO files.
** updated screenshots and descriptions,
** added additional material about file browser, merging, annotation files....
* '''Menu Bar''' - New tutorial written to cover all actions available in the top level menu bar.
* '''Pattern Discovery''' - all screenshots replaced. Changes reflect:
** Fixed display of regular expression matches in Full Sequence view after running with "Exact" unchecked.
** Better illustration of multiple pattern displays in viewer.
** In Advanced tab, matrix and threshold settings now disabled when "Exact" is checked.
* '''Projects'''
** Improved descriptions and added additional screenshots throughout
** Added missing options such as RCSB PDB.
** Add new section on Workspaces
* '''SVM''' - all new chapter written. It is updated to reflect small changes to the Test tab GUI.
* '''t-test'''
** Fully revised all sections.
** Added sections on Volcano Plot and Color Mosaic

==Brief overview of changes in geWorkbench release 2.1.0==
Release Date: September 10, 2010.

* '''BLAST'''
** A major upgrade of the built-in BLAST interface now provides almost all query options available on the NCBI BLAST website.
** geWorkbench can retrieve full or partial sequences for BLAST hits.
A recent change at NCBI caused this to stop working. This is fixed in this release.
* '''Filtering '''
** A new Coefficient of Variation data filter has been added. This scales expression profile standard deviations by their means, so that profiles can be filtered on a directly comparable measure of variation.
* '''Gene Ontology''' expandable tree views were added to the
** Gene Ontology Enrichment viewer
** Cellular Network Knowledge Base (CNKB) viewer
* '''System Information tool'''
** A menu item was added which provides system information such as Java memory allocated and used, path to the current JRE, and Operating System details.
* '''Arrays component'''
** The members of an array set can now be saved as a list to a file on disk, matching functionality already present for markers.
* '''Online Help''' chapter updates (help files built-in to geWorkbench)
** BLAST (Sequence Alignment component) – fully revised.
** Filtering - added section for Coefficient of Variation filter.
** MINDy - added section on using ARACNe preprocessing.
** Pattern Discovery – fully revised.
* '''Cytoscape component'''
** Updated to Cytoscape version 2.7.0.
* '''Bugs'''
** A number of bugs were fixed; full details are available in the Release Notes.
* '''Refactoring'''
** A project of ongoing refactoring and simplification was continued in order to enhance long-term maintainability and performance of the code.

==Brief overview of changes in geWorkbench release 2.0.2==
Release Date: July 16, 2010.

* Fixed problem with genSpace logging.
* Fully revised Online Help chapter for MINDy.

==Brief overview of changes in geWorkbench release 2.0.1==
Release Date: June 25, 2010

* Fixed a problem with caGrid connectivity.
* Fully revised Online Help chapter for the Cellular Networks Knowledge Base (CNKB) component.

==Brief overview of changes in geWorkbench release 2.0.0==
Release Date: June 9th, 2010

===Major new features===
* '''Filtering''' - completely revamped - now works directly for all modes, allows specification of minimum % matching arrays before filtering occurs.
* '''File parsers added''':
** '''MAGE-TAB data matix'''
** '''GEO Soft''' format - added series (GSE) and curated matrix (GDS).
* '''Java 6''' - Moved from Java 5 to Java 6. geWorkbench now requires Java 6. Works on both 32 bit and 64 bit VMs (JREs).
* '''Look and Feel''' - Switched to new, more modern Look and Feel (Nimbus). geWorkbench appearance now consistent across all platforms.
* '''caBIO''' component updated from 4.2 to 4.3.
* '''Cellular Network Knowledge Base (CNKB)''' - Revamped interface to allow choice of interactome and data types.
* More than 250 additional "bug reports" were closed. These included improvements in the usability of numerous components, and actual bug fixes.

===New Components===
* '''Skybase''' - SkyBase is a database that stores the homology models built by SkyLine analysis for all NESG PSI2 protein structures. It is queried using FASTA-format protein sequence files.
* '''Skyline''' - A high-throughput comparative modeling pipeline. It creates structural homology models for protein sequences with similarity to a protein with an experimentally determined 3-D structure. The input is a PDB file. (Depends on an internal server, external use not yet enabled).
* '''Pudge''' - Interface to a protein structure prediction server which integrates tools used at different stages of the structural prediction process. Modeling starts with a FASTA-format protein sequence file.

===Other major changes===
* '''caArray''' - Improved memory usage on downloads from caArray.
* '''CNKB''' - Can now return markers direct from CNKB without use of Cytoscape.
* '''Color Mosaic''' - enhancements to display (bug 2147):
** toggle array names on/off
** search on array name, accession, or label
* '''Component Configuration Manager''' - now can filter display list by categories: Analysis, Viewer, Normalizer, Filter.
* '''Cytoscape''' - Corrected mapping between gene names in Cytoscape display and markers in Marker Sets panel (now uses Entrez IDs).
* '''Dendrogram''' - can now create Array subsets as well as marker subsets.
* '''Markers and Arrays''' - Hover text available in Markers and Arrays phenotypes to visualize long names if needed.
* '''Marker Annotation''' - search results can be saved to a text file, including relevant URLs and pathway BioCarta pathway names.
* '''File loading''' - Checking for "out of memory" errors during file loading.
* '''GUI''' - in switching to new Look and Feel, fixed many text highlighting problems that were previously seen on Macintosh only but now appeared on Windows also.
* '''File parser menu''' - The file parser selection menu now shows valid file extensions for each type.
* '''Promoter''' - JASPAR promoter motifs now filterable by taxon.
* '''Sequence alignment (BLAST)''' - many enhancements, including added additional databases to match those listed at NCBI improved handling of results from searches containing long query sequences.

==Brief overview of changes in geWorkbench release 1.8.0==

geWorkbench version 1.8.0 was released on November 5, 2009.

geWorkbench 1.8.0 adds one new component for calculating Gene Ontology enrichment using Ontologizer 2.0. It also has been updated to connect with the new caArray 2.3.0 Java API. However, geWorkbench 1.8.0 is not backward compatible with earlier versions of caArray.

The geWorkbench 1.8.0. release notes are available at [https://gforge.nci.nih.gov/frs/shownotes.php?release_id=3638 Release Notes]

The geWorkbench application can be downloaded from [https://gforge.nci.nih.gov/frs/?group_id=78 NCI's GForge site].

===Major new features in 1.8.0===

Gene Ontology Enrichment - A new pair of components, called GO Terms Analysis and GO Terms Visualization have been released. The Analysis component is built on Ontologizer 2.0. This component performs "overrepresentation analysis" on a supplied list of genes. It offers a number of advanced methods through the Ontologzier 2.0 engine.

===Other changes in release 1.8.0===
# caArray - Update caArray component to use caArray 2.3.0 Java API. Please note that geWorkbench 1.8.0 is not compatible with earlier versions of caArray.
# CNKB - The network graph generated by CNKB was only showing nodes centered about a focus node. Now all accepted nodes will be displayed.
# Dataset History - Additions for several modules.
# Grid Services - A number of fixes to grid services were made.
# Marker Annotations - Fixed a problem with retrieving marker annotations when microarray data downloaded from caArray.
# Mark-Us - JMOL dependency added for molecule display.
# Promoter - Update JASPAR motifs to release of December 2007. -Note on October 12, 2009 a new version of JASPAR was released which made an incompatible change in the file format.
# Promoter - component now displays logos using the "Schneider" method, including his "small-value correction", rather than using a previous "in-house" method.
# Promoter - the displayed data now does not include the effects of the pseudo-count normalization process.
# Promoter - Added ability to specify pseudocount or select previous hard-coded option of square root of number of sequences.
# Promoter - Loaded TFs now are properly added to the list of available TFs.
# Sequence Alignment (BLAST) - PFP filtering option removed
# Usability fixes - operation of cancel buttons, progress bar.
# Release Notes - Added specific installation instructions.

==Brief overview of changes in geWorkbench release 1.7.0==
===Major new features in 1.7.0===
* '''Marker Annotations''' - The Marker Annotations component now includes direct access to NCI Cancer Gene Index annotations. It supplies detailed literature-based annotations on a curated set of cancer-related genes.
* '''Grid Services''' - All geWorkbench grid services were updated to use caGrid v1.3, with caTransfer used for transferring large data sets.
* '''ARACNe2''' - cellular regulatory network reverse engineering - This release includes a new version of ARACNe, called ARACNe2, from the lab of Andrea Califano at Columbia University. The new version adds the option to preprocess the user's dataset to obtain optimal runtime parameters. It also adds a new algorithm, Adaptive Partitioning, for calculating the mutual information between gene expression profiles. Adaptive partitioning is much faster and is considered to be more accurate than the previous algorithm.
* '''Component Configuration Manager (CCM)''' - The CCM allows individual components to be loaded and unloaded as desired, allowing geWorkbench to be customized to your needs.
* '''genSpace''' collaborative framework - discovery and visualization of workflows. Implemented user registration, preferences, and enhancements to function.

===Newly released analysis components in 1.7.0===

* '''MarkUs''' - The MarkUs component assists in the assessment of the biochemical function for a given protein structure. It serves as an interface to the Mark-Us web server at Columbia. Mark-Us identifies related protein structures and sequences, detects protein cavities, and calculates the surface electrostatic potentials and amino acid conservation profile.
* '''MRA''' - The Master Regulator Analysis component attempts to identify transcription factors which control the regulation of a set of differentially expressed target genes (TGs). Differential expression is determined using a t-test on microarray gene expression profiles from 2 cellular phenotypes, e.g. experimental and control.
* '''Pudge''' - Interface to a protein structure prediction server (developed in the lab of Barry Honig at Columbia University) which integrates tools used at different stages of the structural prediction process.
* '''SVM 3.0''' (GenePattern) - Support Vector Machines for classification. Provides an interface to remote execution on a GenePattern server.

===Other changes in release 1.7.0===

* Analysis - Parameter saving implemented in all components. If current settings match a saved set, it is highlighted.
* ARACNe - improved description of DPI in Online Help.
* caArray - query filtering on Array Provider, Organism and Investigator implemented.
* caArray - can now add a local annotation file to caArray data downloads.
* caGrid - caGrid connectivity is now built directly in to supported components rather than being a separate component itself.
* caScript - The caScript editor is no longer supported.
* Color Mosaic - now interactive with the Marker Sets list and Selection set.
* Cytoscape - Upgrade to Cytoscape version 2.4 for network visualization and interaction.
* Cytoscape - Set operations on genes being returned from Cytoscape network visualizations, via right-click menu.
* Cytoscape - Changes to tag-for-visualization - e.g., now only one way, from marker set to Cytoscape, not vice-versa.
* File loading - PDB protein structure files can now be loaded directly from the PDB database by structure name.
* Gene Ontology file - the OBO 1.2 file format is supported.
* Marker Annotations - add export to CSV file.
* Marker Sets component - a set copy function was added.
* MINDy - many improvements to display and results filtering - including marker set filtering.
* Scatter Plot - Up to 100 overlapping points can be displayed in a single tooltip.
* Various - A number of components were refactored.
* Workspace saving - now works properly for all components.

Home

2016-12-21T21:04:31Z

Smith:

__NOTOC__
<sgallery width="700" showinfopane="false" timed="true" delay="4000" showcarousel="false">
ARACNe_with_t-test_home_gallery.PNG
MarkUs_home_gallery.PNG
Dendrogram_home_gallery.PNG
Volcano_plot_home_gallery.PNG
JMol_viewer_home_gallery.PNG
Skybase_home_gallery.PNG
TF_binding_site_prediction_home_gallery.PNG
Motif_discovery_home_gallery.PNG
BLAST_home_gallery.PNG
CCM_home_gallery.PNG
Gene_Ontology_home_gallery.PNG
</sgallery>

{| class="wikitable" style="background-color:#F8EDD6;" cellpadding="10" width="700px"
|colspan="2"|
<h2>Overview</h2>
'''geWorkbench''' (<u>ge</u>nomics <u>Workbench</u>) is a Java-based open-source platform for integrated genomics. Using a component architecture it allows individually developed plug-ins to be configured into complex bioinformatic applications. At present there are more than 70 available [[Plugins|plug-ins]] supporting the visualization and analysis of gene expression and sequence data. Example use cases include: <toggledisplay status="hide">
* loading data from local or remote data sources.
* visualizing gene expression, molecular interaction networks, protein sequence and protein structure data in a variety of ways.
* providing access to client- and server-side computational analysis tools such as t-test analysis, hierarchical clustering, self organizing maps, regulatory neworks reconstruction, BLAST searches, pattern/motif discovery, etc.
* validating computational hypothesis through the integration of gene and pathway annotation information from curated sources as well as through Gene Ontology enrichment analysis.
<br/>
geWorkbench is the Bioinformatics platform of [http://magnet.c2b2.columbia.edu MAGNet], the '''National Center for the Multi-scale Analysis of Genomic and Cellular Networks''' (one of the [http://www.ncbcs.org 7 National Centers for Biomedial Computing] funded through the [http://nihroadmap.nih.gov/ NIH Common Fund]).

</toggledisplay>
|-
| style="width: 50%; background-color: #F2F8C7;"|
<h2>Quick Start</h2>
Please see the [[QuickStart| Quick Start]] guide to geWorkbench to see how to get started using geWorkbench right away.
| style="width: 50%; background-color: #C7F8CB;"|
<h2>Current Release</h2>
The latest production version of geWorkbench (v2.6.0.3) was released on December 21, 2016.
* [[Release_Descriptions#Brief_overview_of_changes_in_geWorkbench_release_2.6.0|See changes included in latest release]].
* [[Release_Descriptions|See history of past releases]].
* [[Download_and_Installation|Download geWorkbench]].

|-
|style="background-color: #D8FAFA;" colspan="2"|
''<h4><center><font color="red">New web-enabled version available</font></center></h4>''
[[GeWorkbench-web/Overview|'''geWorkbench-web''']] provides installation-free access to the geWorkbench plug-ins through a pure browser interface. You can create and account and access the application at: http://geworkbench.c2b2.columbia.edu/geworkbench/.
|}

Download and Installation

2016-12-21T21:00:47Z

Smith: /* geWorkbench 2.6.0.3 (released December 20, 2015) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 21, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-21T20:59:37Z

Smith: /* Operating System */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-21T20:59:11Z

Smith: /* Windows (XP/Vista/7/8) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8/10)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

File:GeWorkbench v2.6.0.3.md5.txt

2016-12-21T20:57:39Z

Smith:

File:GeWorkbench v2.6.0.3 ReleaseNotes.txt

2016-12-21T20:55:36Z

Smith:

Download and Installation

2016-12-21T20:53:35Z

Smith: /* geWorkbench 2.6.0.2 (released February 20, 2015) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.3 (released December 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]

[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.3.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-21T20:52:07Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of the original release, the Windows geWorkbench_2.6.0 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.2 (released February 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.2.md5.txt|geWorkbench_v2.6.0.2.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.2_ReleaseNotes.txt | geWorkbench_v2.6.0.2 Release Notes]]

[[Media:GeWorkbench_v2.6.0.2_ChangeLog.txt | geWorkbench_v2.6.0.2_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.2.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-21T20:51:41Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of release, the Windows geWorkbench_2.6.0.2 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far up to 111, the Windows installers will no longer work without special handling. This does not affect the generic version of geWorkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.2 (released February 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.2.md5.txt|geWorkbench_v2.6.0.2.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.2_ReleaseNotes.txt | geWorkbench_v2.6.0.2 Release Notes]]

[[Media:GeWorkbench_v2.6.0.2_ChangeLog.txt | geWorkbench_v2.6.0.2_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.2.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-20T22:50:06Z

Smith: /* IMPORTANT Note for Windows (and Linux) */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of release, the Windows geWorkbench_2.6.0.2 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far updates 60, 65 and 66, the Windows installers will no longer work without special handling. This does not affect the generic version of geworkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 bove update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "Windows error 2 occurred while loading the Java VM".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.
# Alternatively, just use "geWorkbench_v2.6.0_Generic.zip" which does not rely on an installer and can be run on any machine. See installation details below.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.2 (released February 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.2.md5.txt|geWorkbench_v2.6.0.2.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.2_ReleaseNotes.txt | geWorkbench_v2.6.0.2 Release Notes]]

[[Media:GeWorkbench_v2.6.0.2_ChangeLog.txt | geWorkbench_v2.6.0.2_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.2.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Download and Installation

2016-12-20T22:46:55Z

Smith: /* Workarounds */

{{DownloadTopNav}}

This section contains instructions for '''downloading''' and '''installing''' geWorkbench.

=IMPORTANT Note for Windows (and Linux)=
At the time of release, the Windows geWorkbench_2.6.0.2 installers were compatible with Java 8 being installed on the machine. This was true up through Java 8 update 51. However with the release of later version of Java 8, including so far updates 60, 65 and 66, the Windows installers will no longer work without special handling. This does not affect the generic version of geworkbench, which can be used on any platform.

==Affected versions==
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe
* geWorkbench_v2.6.0_Windows_noJRE.exe

==The problem==
When a version of Java 8 bove update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "Windows error 2 occurred while loading the Java VM".

==Workaround==
# Uninstall any copies of Java 8 JDK or JRE above update 51 on the machine, perform the geWorkbench installation, and then reinstall Java 8 if desired.
## geWorkbench_v2.6.0_Windows_JRE7_x64.exe and geWorkbench_v2.6.0_Windows_JRE7_x86.exe do not need any version of Java installed to complete their own installation.
## geWorkbench_v2.6.0_Windows_noJRE.exe installation requires that a compatible version of Java be installed. It is best to install a version of Java 7 on the machine. geWorkbench 2.6.0.* has only been tested with Java 7.

==Downloading older versions of Java==
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]. Signing up for an Oracle web account is required.

=IMPORTANT Note for Mac OS X=
(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.

Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].

=Download geWorkbench=

==geWorkbench 2.6.0.2 (released February 20, 2015)==

'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.

[[Media:GeWorkbench_v2.6.0.2.md5.txt|geWorkbench_v2.6.0.2.md5.txt]] - MD5 digest of each download file

[[Media:GeWorkbench_v2.6.0.2_ReleaseNotes.txt | geWorkbench_v2.6.0.2 Release Notes]]

[[Media:GeWorkbench_v2.6.0.2_ChangeLog.txt | geWorkbench_v2.6.0.2_ChangeLog.txt]]

The files for download below have all been updated to version 2.6.0.2.

===Windows===
Note - on Windows 8.1, Windows SmartScreen may warn you about running the downloaded program. Click "More Info" and then "Run".

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe] (290,041 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
* Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (248,306 KB)

===Mac OS X===
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip] (287,622 KB)
* Includes 64-bit JRE7, max Java heap memory selectable by command file.

===Linux===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
* Includes 64-bit JRE7, default 2GB max Java heap memory. Recommended version.

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin] (280,596 KB)

===Generic - any platform===

[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip] (240,045 KB)

=geWorkbench 2.6.0 - System Requirements=
==Java==
* geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
* The latest versions of Java 7 installed separately on your machine will ask you to update to Java 8. For this reason, again, it is better to use a version of geWorkbench that includes its own copy of the Java 7 JRE.
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included. To install a version of geWorkbench that does not include the JRE, Java must be installed separately on the machine.
* On Mac OS X, the Java 7 JRE is included in the installation file.
* The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.

==Special Java Requirements for Specific Components==
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.

There are specific steps to configure Java for these two applets. See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.

===Obtaining Java===
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.

==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 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

==Operating System==
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''':
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.

* '''Mac OS X''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).

* '''Linux''': no special requirements.

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 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

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 [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.

=geWorkbench 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 JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.

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

Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.

==Windows (XP/Vista/7/8)==
===Installation===

New with release 2.6.0, geWorkbench will now by default install to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.

Download one of the Windows installers and double-click the installer file to begin installation.

===Running geWorkbench on Windows===

You can launch geWorkbench using the default Java max heap memory size just by using the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_macosx_4G.command", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

==Mac OS X==
===Installation===
* Requires Mac OS X 10.7.3+. Recent testing has been on 10.10 only.
* As Java 7 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 MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.

===Running geWorkbench on Mac OS X===

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

==Linux==

* If you wish to install the no-JRE version of geWorkbench, you must make sure that an appropriate Java 7 JRE is installed on your system before installing geWorkbench.
* You may need to configure the JRE. See section below, "Java Environment Configuration".

===Installation===

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.6.0_Linux_JRE7_x64.bin".

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

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).

===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, depending on how the alias file was named:

sh geWorkbench_2.6.0
or
sh rungeWorkbench_2.6.0.

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

sh geWorkbench

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

File: geWorkbench_v2.6.0_Generic.zip

===Installation===

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

===Running geWorkbench (generic)===

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

====Windows====

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

====Mac OS X====
Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the 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.

=R Installation for geWorkbench=
Some geWorkbench components can make use of a locally installed version of R.

==R installation on Windows==
* '''R installation directory''' - 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.2\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.2\'''.

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

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

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. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set 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). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

* 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 on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].

* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].

* '''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 [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].

==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.1/Resources/bin/Rscript.
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.

=Java Environment Configuration=

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 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 JRE7.

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

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

==Macintosh OS X==
The Mac OS X version of geWorkbench includes the Java 7 JRE.

==Switching between different installed JREs on Windows==
The no-JRE 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.

=Java Runtime Special Exceptions=
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
* http://www.c2b2.columbia.edu
* https://bhapp.c2b2.columbia.edu
* https://honiglab.c2b2.columbia.edu

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
* If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
* If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

=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
# 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.
# allow remote connections with a command such as "xhost +".

=Quick Start=
A [[QuickStart| 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 is further described on the [[Tutorial_Data]] page.

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

[[Media:Bcell-100.zip|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.

=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,
# First download and extract geworkbench-core.
# Then download and extract geWorkbench-components.
# From within geworkbench-components, move the extracted "components" directory into the core.
# Finally, download the two files from the geworkbench_supplemental_files project.
## Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
## 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==
Public access to the NCI Subversion repository is no longer available.

=Compiling the geWorkbench Source Code=

* you must have the Java JDK 7 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.7.0_71

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 OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

GeWorkbench-web/ARACNe tmp

2016-09-28T19:42:08Z

Smith: Created page with "{{TutorialsTopNav}} =Overview= ARACNe (Algorithm for the Reconstruction of Accurate Cellular Networks) (Basso 2005, Margolin 2006a, 2006b) is an information-theoretic algorithm..."

{{TutorialsTopNav}}

=Overview=
ARACNe (Algorithm for the Reconstruction of Accurate Cellular Networks) (Basso 2005, Margolin 2006a, 2006b) is an information-theoretic algorithm used to identify transcriptional interactions between gene products using microarray gene expression profile data. By proper selection of samples, a tissue (cellular context)-specific set of pairwise regulatory interactions (transcription factor-target) can be obtained – an “interactome”. Such an interactome can form the basis for more complex analysis of cellular regulatory networks. ARACNe has been used to reconstruct networks in mammalian cells for a number of specific tissue types.

For a dataset with a simple, monotonic relationship between input and output, analysis with a normal (e.g. Pearson's) correlation function may be the most suitable method. Where the input/output function is non-linear or irregular, a method based on the calculation of mutual information, such as ARACNe, may be able to find relationships that Pearson's correlation will not find. Calculation of the mutual information does not require a monotonic relationship. ARACNe has proven to be well suited for the reverse engineering of regulatory networks in the context of specific cellular types.

ARACNe performs best with a dataset containing data from a minimum of 100 microarrays (see Margolin, Wang et al. 2006) up to about 300-400 arrays, and representing a number of different states of the same cellular system - for example, cells lines of varying phenotype, or cells subjected to a variety of experimental perturbations. Initial work with ARACNe was performed using a large collection (about 340) of B-cell lines of various phenotypes (Basso et al. 2005). Note - For the "Fixed Bandwidth" option, using in excess of 300 arrays can lead to long computation times.

ARACNe can perform two separate calculations:

# '''Mutual Information''': The mutual information (MI) of one or more marker's expression profile(s) is calculated against all other markers.
# '''Data Processing Inequality (DPI)''': The DPI calculation is used to remove the weakest interaction (edge) between any three markers. That is, if a MI value is available between each of three possible pairings of three markers, the weakest interaction of the three will be removed from the output. This has the intent of removing indirect interactions. For example, if A->B->C, the indirect interaction A->C will likely be weaker than A->B or B->C and would be removed. A tolerance can be set which relaxes this screening to account for uncertainty in the MI calculation.

Parameters described below allow one to incorporate a list of putative transcription factors and optimize the run to discover target genes that they may regulate.

Further information on ARACNe is available in the References section below.

=Prerequisites=
* A microarray dataset of sufficient size and phenotypic diversity is needed (See the Overview, above).
* Load the microarray dataset into the [[Workspace|Workspace]]. A gene annotation file is not required for ARACNe, as it works at the probeset level. However, many other components of geWorkbench do require an annotation file be associated during upload.
* '''Warning on too few arrays''' - if a dataset with fewer than 100 microarrays is submitted for ARACNe analysis, a warning message will appear notifying the user of the suggested minimum of 100 arrays. Too few arrays may also cause the calculation to fail.

=Parameters and Settings=

==Algorithm==
Two algorithms are offered with which to calculate the pairwise mutual information between markers:
* '''Adaptive Partitioning''' (default) - fast calculation, and considered to produce superior results in certain circumstances.
* '''Fixed Bandwidth''' - previous, slower algorithm using a fixed Gaussian kernel. The kernel width parameter can be adjusted.

==Mode==
Choose whether to run the preprocessing calculation for a dataset, or to run ARACNe (Discovery mode)
* '''PREPROCESSING''' - Calculates dataset-specific parameters and stores them in "config" nodes in the workspace.
* '''DISCOVERY''' - Run the ARACNe mutual information calculation.

===Preprocessing===
In this mode, dataset-specific parameters are calculated. They are used to improve the mutual information calculation when Discovery mode is run. Preprocessing for a given combination of dataset and algorithm needs be run only once.

In general, preprocessing should always be run to improve the accuracy of the results. The only real exception is if you are running Adaptive Partioning with an MI value as the threshold, then pre-processing is not needed. Please be aware though that the raw MI values do not carry any information about their significance.

When running Discovery mode (below), if no preprocessing result node is specified, default parameters calculated from the B-cell dataset (see Margolin et al., 2006) are used as needed depending on the algorithm and options chosen.

* '''Fixed Bandwidth (FBW) algorithm''' - calculates parameters later used for (1) calculating the kernel width, and (2) for calculating a MI threshold from a specified P-value.
* '''Adaptive Partitioning (AP) algorithm''' - only the parameters used for calculating a MI threshold from a specified P-value are calculated. No kernel-width parameter is used.

Preprocessing parameter node names take the following form in the Workspace:
* "Aracne - AP - cfg22281": parameters for adaptive partioning. AP indicates this is a node for use (only) with adaptive partitioning. The job number is appended to "cfg".
* "Aracne - FB - cfg22282": parameters for fixed bandwith. FB indicates this is a node for use (only) with the fixed bandwidth method. The job number is appended to "cfg".

Please do not rename the nodes.

The parameters are displayed if the config node is clicked on, e.g.:

[[Image:ARACNe_web_AP_Threshold_Params.png]]

===DISCOVERY===
The ARACNe mutual information and the DPI (if selected) calculations are run.

====Hub Marker(s) From Sets====
The user must have already created a set of hub markers in the "Set View", either by selecting markers directly, or by uploading a list from a text file. Specifies which gene markers will be treated as "hubs" in the ARACNE mutual information (MI) calculation. The mutual information is calculated for each specified hub marker against all other markers in the submitted dataset. Typically, a list of known transcription factors is used to specify the hub markers. Such a list must be supplied by the user.

A pulldown menu allows selection from any marker set present (in the current marker context).

====Threshold Type====
=====Mutual Info. =====
Use the raw MI value calculated by ARACNe. Only interactions with MI above the threshold will be included in the final network. the MI can be any positive value or zero, but not negative.
=====P-Value=====
Use a p-value calculated from the MI values as the threshold. For best results, the preprocessing step must be run first to generate the parameters needed to calculate p-values from MI values for the particular data set.

====Threshold====
Enter the desired threshold value into the text field.

* '''Note''' - Using a P-value for the threshold is preferred to using the raw MI value, as the MI value conveys no information about significance.

====Correction====
If the threshold type is chosen as P-Value, an option to apply the Bonferroni multiple testing correction is offered in the adjacent pulldown menu.

* '''No Correction''' (default) - No correction is applied.
* '''Bonferroni Correction''' - Divide the specified p-value threshold by the (number of markers)*(number of hub genes tested).

====Kernel width====
The Kernel width is a scaling parameter used for fitting a Gaussian function to the data when running the FIXED_BANDWIDTH algorithm only, otherwise this field is disabled. If used, the value can be either inferred or specified directly.

* '''Inferred''': If PREPROCESSING has been run on the dataset (mode is set to PREPROCESSING or COMPLETE), the kernel width is calculated directly from those results. If PREPROCESSING has not been run, the kernel width is inferred based on parameters fitted to a large B-cell dataset (Margolin et al, 2006), extrapolated for the number of samples in the dataset being tested.
* '''Specify''': The user can enter a value for the kernel width directly, e.g. based on a prior calculation with this dataset.

====DPI Tolerance====
The Data Processing Inequality can be used to remove the effects of indirect interactions, e.g. if TF1->TF2->Target, DPI can be used to remove the indirect action of TF1 on the target. It is specifically intended to "remove indirect interactions mediated through two transcriptional interactions" (ARACNe Manual). The DPI tolerance specifies the degree of sampling error to be accepted, as with a finite sample size an exact value MI can not be calculated. The higher the tolerance specified, the fewer the edges that will be removed.
* '''Do Not Apply''' - Do not use the DPI.
* '''Apply''' (default) - In the text box, enter the fraction of the estimated MI to be considered as sampling error, expressed as a real number between 0.0 and 1.0. E.g. for 10%, enter 0.1. The default value of 0.0 (zero) is recommended.

For a full discussion of the theory and use of DPI in ARACNe, please see [http://www.biomedcentral.com/1471-2105/7/S1/S7 Margolin et al. (2006)].

====DPI Target List====
The DPI Target List is used to give preference during application of the DPI to transcriptional interactions over those of genes that are e.g. tightly co-expressed but are not in a regulatory relationship to each other. An example of such co-expressed genes is genes for two proteins that are in a physical complex and hence always produced in the same amounts. If used, the DPI Target List should contain all markers that are annotated as transcription factors. Signaling proteins could also be included depending on the intended use of the network.

* Use of the DPI Target List prevents transcriptional interactions from being removed by non-transcriptional interactions when DPI is run.
* The DPI Target List comes into play when DPI examines a triangle of interactions which contains one TF and two non-TFs. If the weakest of the three interactions involves the TF (a TF-nonTF edge), then that edge would be removed by a simple application of the DPI. However, if the TF is included on the DPI Target List, the TF-nonTF edge will not be removed.

For further explanation and figures on the DPI Target list, see Chapter 3, note 7 of the [http://www.nature.com/nprot/journal/v1/n2/extref/nprot.2006.106-S1.doc ARACNe Manual].

* '''Do Not Apply''' - do not use a DPI target list.
* '''From Sets''' - select a marker set to use for the DPI target list. The marker set must have already been created in the "Set View".

====Bootstrapping====
Bootstrap analysis can be used to generate a more reliable estimate of statistical significance for the interactions. Please see Margolin et al. 2006, Nature Protocols, Vol 1, No. 2, pg. 663-672 for further details (full reference below). Briefly, repeated runs of ARACNE are made, with arrays drawn at random from the full dataset with replacement. The same number of arrays is drawn each time as is present in the original dataset. A permutation test is then used to obtain a null distribution, against which the statistical significance of support for each network edge connection (interaction) can be estimated.

* '''100 rounds of Bootstrapping''': (Checkbox) - when selected 100 rounds of bootstrapping are run in parallel on the C2B2 cluster.
* '''Consensus threshold''' (for bootstrapping only): After the bootstrapping runs are made, a permutation test is used to estimate the significance of interactions. The consensus threshold sets the cutoff point for calling the interactions significant and returning them in the final adjacency matrix

* Note - bootstrapping does not replace the need to filter the individual ARACNe runs using a p-value or MI threshold. That initial screening reduces the initial network to a tractable size, and is a prerequisite for the bootstrapping permutation step.

====Merge multiple probesets====
On a microarray analysis platform, genes may be represented by more than one marker (probeset). The mapping between markers and genes is specified in the annotation file, if it is read in at the time that the data is loaded. The ARACNe analysis in geWorkbench is performed at the level of probesets. In some cases, an interaction between two genes may be represented by more than one edge, each such edge involving an alternate probeset for at least one of the genes.

Selecting "merge multiple probesets" causes

* '''Yes''' - Merge multiple probesets. Interactions will be summarized at the gene level for each hub marker. The edge with the highest mutual information (MI) will be retained The resulting adjacency matrix will contain a single line per hub gene.
* '''No''' - Do not merge probesets. The full ARACNe adjacency matrix, as calculated at the probeset level, will be returned.

===Analysis Actions===
* '''Analyze''' - start the ARACNe analysis

===Technical Note===
* Multiple Gene IDs - In some cases, a marker may be annotated to more than one gene in the annotation file. Only the first such gene name on an annotation line is used when determining if two probesets map to the same gene.

=Adjacency Matrix Result Node=
The result of an ARACNe run is an adjacency matrix, placed as a new data node in the Workspace as a child of the microarray dataset from which it was generated. It contains the mutual information value for each pair of markers (or genes, if "merge probesets" was used) which exceeded the specified MI threshold. The adjacency matrix is placed into the Workspace as a child of the dataset that was analyzed.

The file format is described further in the [[File_Formats | File Formats]] chapter.

=Viewing ARACNe results=

* The adjacency matrix can be visualized automatically in a viewer implemented using Cytoscape.js. Examples are shown below.

=Dataset History=

Details about each run are maintained in the Dataset History component. With the ARACNe result node highlighted in the [[Workspace|Workspace]], the Dataset History display includes the following information:

* Hub markers (list)
* Mode
* Preprocessing node used
* Algorithm
* MI threshold type and value
* Correction type
* DPI Tolerance usage and value
* DPI Target List usage
* Bootstrapping - number of bootstrapping runs (if > 1).
* Merge multiple probesets (yes/no)
* Count of markers in dataset
* Count of microarrays in dataset
* Timestamp

An example of the Dataset History, ommiting the lists of arrays and markers, is:

Aracne Parameters :
Hub Marker(s) from Sets - gc:
1476_s_at
34715_at
Mode - Discovery
Configuration - Aracne - AP - cfg22281
Algorithm - Adaptive Partitioning
Threshold Type - P-Value: 0.01
Correction Type - Bonferroni Correction
DPI Tolerance - Apply : 0.0
DPI Target List - Do Not Apply
100 Bootstrapping is not checked
Merge multiple probesets - No
Markers used (12600) -
All Markers
Phenotypes used (100) -
All Arrays
Timestamp: Sep 23, 2016 3:51:52 PM

=Example of running ARACNe and viewing results=

This example uses the Bcell-100.exp dataset available in the data/public_data directory of geWorkbench, and further described on the [[Download]] page. Briefly, this dataset is composed of 100 Affymetrix HG-U95Av2 arrays on which various B-cell lines, both normal and cancerous, were analyzed. Thus it explores a potentially wide variety of expression phenotypes.

==Prerequisites==
1. (Optional) Obtain the annotation file for the HG-U95Av2 array type from the Affymetrix NetAffx website (http://www.affymetrix.com/analysis/index.affx). The name will be similar to "HG_U95Av2.na36.annot.csv", where na36 is the version number. Loading the annotation file associates gene names and other information with the Affymetrix probeset IDs (see the [[FAQ | geWorkbench FAQ]] for details on obtaining these files).

2. Download the file [[Media:Mapk_list.csv|Mapk_list.csv]] to your computer. These will be the hub markers.

==Load Data==
1. Load the Bcell-100.exp dataset into geWorkbench as type "Expression File (.exp)". (See [[Local_Data_Files | Local Data Files]]).

2. If desired, load the annotation file. Loading the annotation file allows the resulting network to be expressed in terms of genes rather than probesets.

3. Switch to "Set View" and load the file "Mapk_list.csv" as a market set. It contains marker ids, not gene symbols.

==Setting up the parameters and starting ARACNe==
1. Switch back to Workspace view if you are still in "Set View".

2. In the Workspace, click on the expression file you just uploaded, BCell-100.exp.

3. At right, under the heading "Microarray Data", is the list of available commands. Click on ARACNe. You will see the parameter settings page.

==Running Pre-processing==

The pre-processing step is highly recommended to tune the ARACNe calculation to your dataset.

[[Image:ARACNe_web_Preprocessing.png]]

1. Select mode "Preprocessing" and algorithm "Adaptive Partitioning", and then hit "Submit". Note - this may take about 5 minutes to finish. (While "Preprocessing" mode is selected, you see only the choice for "Algorithm").

2. When preprocessing finishes, you will see a new "config" node appear in the Workspace as a child of the expression dataset you are analyzing.

==Running Discovery==

1. Select '''Mode''': '''Discovery'''.

2. Specify '''Algorithm''': '''Adaptive Partitioning'''. You will see the full parameter panel with all available settings.

3. Set '''Hub Markers From Sets''' to '''Mapk_list'''

4. Verify '''Threshold Type''' is '''P-value'''

5. Change '''Threshold Value''' to '''0.05'''

6. Set '''Correction Type''' to '''Bonferroni'''

The full parameter list should now appear as follows:

* '''Mode''': Discovery
* '''Algorithm''': Adaptive Partitioning
* '''Hub Markers from Sets''': Mapk_list
* '''Threshold Type''': P-value
* '''Threshold Value''': '''0.05'''
* '''Correction''': '''Bonferroni'''
* '''DPI Tolerance''': Apply
* '''Tolerance Value''': 0.0
* '''100 rounds of Boostrapping''' - not checked
* '''Merge multiple probesets''' - No

[[Image:ARACNe_web_params_with_PP.png|{{ImageMaxWidth}}]]

5. Press '''Submit''' to launch the job. It should take only a few minutes.

6. The resulting network is shown below, drawn using Cytoscape.js.

[[Image:ARACNe_web_Discovery_with_pp.png|{{ImageMaxWidth}}]]

==Running Discovery with "Merge" enabled'''==
This example is run just as above, but with the option '''Merge multiple probesets''' set to '''yes'''

* '''Merge multiple probesets''' - yes

[[Image:ARACNe_web_Discovery_with_PP_and_merge.png|{{ImageMaxWidth}}]]

=Technical Notes=
* Supplying the set of hub markers is the same as using the "-s" subnet option with the standalone ARACNe executable. "... a list of probes for which a subnetwork will be constructed".
* The DPI target list, if supplied, is the same as using the "-l" transcription factor option with the standalone ARACNe executable. "...a list of probes annotated as transcription factors in the input dataset".
** "This option is ideal for transcriptional network reconstruction. If provided, DPI will not remove any connection of a transcription factor (TF) by connections between two probes not annotated as TFs. (However, this option has no effect if the list of hubs is already limited to transcription factors).
* If DPI is applied, the recommended tolerance value is now zero. In early publications, values up to 0.15 were recommended.
* When reconstructing transcriptional networks use of the bootstrapping option is recommended.
* Running with too few arrays can cause NaNs in Adaptive partioning preprocessing step, and in a NullPointerException in Fixed Bandwidth (Mantis issue 2030).
* The results of an ARACNe run depend to a small extent on the particular order of the arrays in the dataset - that is, reshuffling the arrays can give a numerically different MI.

=References=

* Basso K, Margolin AA, Stolovitzky G, Klein U, Dalla-Favera R, Califano A: Reverse engineering of regulatory networks in human B cells. Nat Genet 2005, 37(4):382-390. PMID [http://www.ncbi.nlm.nih.gov/pubmed/15778709 15778709], ([http://www.nature.com/ng/journal/v37/n4/abs/ng1532.html link to paper]).
* Margolin AA, Nemenman I, Basso K, Wiggins C, Stolovitzky G, Dalla Favera R and Califano A, (2006a) ARACNE: An Algorithm for the Reconstruction of Gene Regulatory Networks in a Mammalian Cellular Context, BMC Bioinformatics;7(Suppl.1):S7 ([http://www.biomedcentral.com/1471-2105/7/S1/S7 link to paper])
* Margolin A, Wang K, Lim WK, Kustagi M, Nemenman I, and Califano A (2006b) Reverse Engineering Cellular Networks. Nature Protocols 1(2):663-672 ([http://www.nature.com/nprot/journal/v1/n2/abs/nprot.2006.106.html link to paper])
** [http://www.nature.com/nprot/journal/v1/n2/suppinfo/nprot.2006.106_S1.html Supplementary materials list]
*** [http://www.nature.com/nprot/journal/v1/n2/extref/nprot.2006.106-S1.doc Supplementary materials - ARACNe Manual]
*** [http://www.nature.com/nprot/journal/v1/n2/extref/nprot.2006.106-S2.doc Supplementary materials - Technical Report]

File:ARACNe web Discovery with PP and merge.png

2016-09-27T19:05:21Z

Smith: