Revision as of 12:13, 12 December 2014

Installation - top issues

Macintosh OSX platform

Gatekeeper prevents installation

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

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

To allow geWorkbench to install, you must temporarily tell Gatekeeper to allow installation of files from "anywhere". Please see the instructions at the link MacOSX Installation and GateKeeper

geWorkbench 2.5.1

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.

R-based analyses (SAM and VIPER) on Windows platforms fail if space in path

The Problem

If you are using a version of geWorkbench on Windows which does not include the built-in JRE, then you may experience problems with components that make use of R. This problem began with a change in Java 6 update 45, and also was introduced in Java 7 update 21. The problem lies in a change in how spaces in file paths are handled, e.g. "C:\Program Files\R".

Note - the problem has been resolved in the geWorkbench 2.5.2 branch.

Background

geWorkbench for Windows can be downloaded with or without a built-in JRE. The version of geWorkbench with built-in JRE does not experience the problem, because it uses Java 6 update 26.

However, you may wish to use a version of geWorkbench which does not include the built-in JRE, for example in order to use a 64-bit version of Java.

Workaround

Install R into a directory path that does not have any spaces in it, e.g. C:\R\R-3.0.3. You can then run geWorkbench with the most recent versions of Java.

MRA-FET

Running MRA-FET with an activated marker set will give incorrect results. Please do not activate any marker sets when running MRA-FET (Mantis issue #2793).

VIPER

A file needed by VIPER was omitted in geWorkbench 2.5.0 and the initial release of geWorkbench 2.5.1. A new version of 2.5.1 containing the missing file was made available on November 12, 2013 at 8 pm EST on the download server. There were no source code changes.

MarkUs

A problem with the MarkUs service URL has been resolved through a redirect to the new URL, https://bhapp.c2b2.columbia.edu.

Update - this redirect does not seem to be working anymore. To see your results, enter the MarkUs job into a web browser as follows, using the job name returned for the MarkUs results node in the Workspace:

https://bhapp.c2b2.columbia.edu/MarkUs/cgi-bin/browse.pl?pdb_id=MUS#### where #### represents the particular job number returned in geWorkbench for your job.

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 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.

Windows Control Panel Version Number

The initial release of geWorkbench 2.5.1 reported its version as 2.5.0 in the Windows control panel. This was corrected in the new copy of 2.5.1 made available November 12, 2013 at 8 pm on the download server.

Java 7

See below entries for information on running with Java 7.

• PCA - the PCA 3D Viewer does not work on the Mac OS X with Java 7 (64bit, tested with update 45).

geWorkbench 2.5.0

• Workspace (#3577) - (fixed in 2.5.1) The "merge" function for expression datasets is not working when invoked from the "File" menu. However, it does work if two or more expression datafiles of the same type are loaded together in the same file open operation. To do this, the files should be in the same directory, and all files to be merged should be selected together (multiple-selection). The files will then be merged into a single dataset and placed into the Workspace.

geWorkbench 2.4.1

BLAST - Due to a change in the output from the NCBI BLAST server, sequence alignments are not being displayed. This will be fixed in version 2.5.0 by switching to using the XML results file.

Marker Annotations - As of September 30th, 2013, NCI-CBIIT is expected to deactivate the caBIO service on which the geWorkbench Marker Annotation component depends. geWorkbench 2.5.0 uses the bioDBNet service as its data source instead.

Issues for 2.4.1 are the same as for those listed for 2.4.0, except that the first BLAST issue, dealing with the HTML page parsing, has been fixed.

BLAST - (also in previous versions) 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.

geWorkbench 2.4.0

The following problems have been noted in geWorkbench 2.4.0. Some may apply to earlier releases as well.

• BLAST (9/26/2012) - due to a change in the HTML result format from the NCBI website, BLAST in geWorkbench 2.4.0 and all previous versions no longer works.
• ARACNe2 -
  • (#2885) ARACNe and MINDy, if local job cancellation is requested, call a non-safe method, thread.stop(), which can occasionally produce an exception.
• Java 7 - geWorkbench 2.4.0 was developed and tested using the Java 6 JDK and JRE. Although several incompatibilites with Java 7 were identified and fixed, as least one remains, shown below. For this reason, please only use Java 6 JREs when running geWorkbench 2.4.0 or earlier.
  • Marker Annotations - (#3072) does not receive activated marker set, caBIO client library conflict with Java 7.
• BLAST - (#2825) the maximum number of hits returned is 50, even if more were requested.
• caArray - (#2893) due to a synchronization problem, a large empty white space may occasionally appear in the caArray list of experiments.
• Cytoscape
  • (#2843) if an instance of Cytoscape is running on a machine, and then Cytoscape is also loaded in geWorkbench, you may see a warning "org.cytoscape.coreplugin.cpath2.http.HTTPServer[WARN]: HTTPServer couldn't create socket.".
  • (#2716) Direct LinkOuts from the right-click menu to UniProt may not work. However, they do work when selected from the Cytoscape Data Panel.
• GenePattern connectivity (#2701) - if you successfully connect to a GenePattern server, and later that server is no longer available, you will experience a time-out delay. This was seen when first connecting to a GP server through a firewall via VPN, then trying again without the VPN.
• GenomeSpace - transfer of large data files is not supported. This has been fixed in development (Mantis issue #3273).
• Grid Services/Dispatcher Service:

As of release 2.3.0, outbound data (from geWorkbench to the grid service) is moved using caTransfer, both from geWorkbench to the Dispatcher, and from the Dispatcher to the grid service. Returning data is transferred for both hops as a base-64 encoded string, which for very large data sets can lead to an out-of-memory error. Full replacement with caTransfer is being investigated.

The error message will read:

Out-of-memory error: Java heap space
It is advisable to restart geWorkbench.
You may also wish to increase the geWorkbench memory size. 

In this case, as the message states, it is advisable to restart geWorkbench. Instructions for increasing the amount of memory available to Java are available in the geWorkbench FAQ. For Java memory requests larger than about 1.5 GB, running geWorkbench using a 64-bit Java Runtime Environment (JRE) will be necessary.

Any current release

Java plug-in in web browsers

In some cases, geWorkbench uses an external browser window for results display, and may also use a Java applet in that window for results display.

Because of this, you may need to specifically enable Java Plugins to run in your particular browser. You should be prompted by the browser to allow this. After you are finished with the tool, you may wish to disable Java applets in your browser again. These controls are usually found in the browser's settings menu.

In addition, there are platform-specific steps that may need to be taken, as detailed below.

Some Java applet-based tools (such as MarkUs) require that the 32-bit version of Java be installed. Even if you have a 64-bit version of Java installed, you should also install the 32-bit version to use these components.

Windows

Some geWorkbench components, such as MarkUs, use a Java-based applet that runs in your web browser. If the applet does not run, you can allow it by taking the following steps: 1. In the Windows Control Panel, click on the Java icon to start the Java Control Panel.

2. In the Java Control Panel, click on the Security tab.

3. Check-mark the box "Enable Java content in the browser".

4. Push the "Edit Site List" button.

5. Add an exception to the Exception Site list in the lower part of the dialog for the page containing the Java applet.

5a. For MarkUs, add "https://honiglab.c2b2.columbia.edu" (without the quotes).

The above has been tested to work on Windows 8.1 with Java 7 update 51.

64-bit Java issue

Affects: GSEA, Markus, Pudge and PCA.

Several geWorkbench components make use of the embedded JDIC web browser. The version of JDIC used in geWorkbench is not entirely compatible with 64-bit versions of Java. If this problem is encountered, these components will instead transfer the display to your computer's default web browser. However the displayed web page will not automatically update or interoperate with geWorkbench.

Cytoscape loading

Cytoscape is by default enabled in the 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

Java 7 on Mac

This affects 10.7.3 and later versions of Mac OS X.

With a recent Java update, Apple has removed the Java plugin for all web browsers. If you load a web page which calls for this plugin, you will be prompted to download Java 7 from Oracle, which does support a browser plugin. However, geWorkbench (officially) requires Java 6. (Most features will work fine on Java 7 however).

We have seen on our own machine that installing Java 7 sometimes leaves the existing Java 6 installation intact, and that the Mac installer version of geWorkbench (tested with v2.5.1) continues to use this Java 6 installation. However, the following links are provided in case any problems arise.

• The following links contain instructions for reverting to Java 6 after installing Java 7, should you so desire: JDK 7 Installation for Mac OS X

• See also the Mac OS X Platform Install FAQ

• How to determine which version of the JDK you are currently using

• More details about Java 6 and 7 are also found here: Note for Users of Macs that Include Apple Java 6

• Java for OS X: How to re-enable the Apple-provided Java SE 6 applet plug-in and Web Start functionality

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.

PowerPC-based Macintosh computers

Java 6 is not available for the PowerPC platform, regardless of the version of OS X. For this reason, recent versions of geWorkbench which require Java 6 will not run on PowerPC Macintosh computers.

Installer Issues

• We observed on a Windows 7 platform, that if geWorkbench, including the JRE6, is installed directly from a USB memory stick, the installation may silently fail. The machine was running the current version of Norton Internet Security. Copying the installer to the hard disk and installing from there solved the problem (Observed for geWorkbench 2.3.0).
• Versions of Norton Internet Security "Sonar" prior to NIS2011 may detect and delete a file generated during the installation process, "Install.exe". This will silently terminate the install. If this occurs, disable the Sonar feature during installation, or disable your antivirus protection during the installation.

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 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,

1. geWorkbench cannot be built from source, as a compile error is generated, and
2. 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.
  • 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 Oracle Java3D distribution site).

• Next, 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.