Diff for "Cytoscape_3/UserManual/Launching_Cytoscape"

Cytoscape is a Java application verified to run on the Linux, Windows, and Mac OS X platforms. Although not officially supported, other UNIX platforms such as Solaris or FreeBSD may run Cytoscape if Java version 5 or later is available for the platform.

System requirements

The system requirements for Cytoscape depend on the size of the networks the user wants to load, view and manipulate.

Specific system requirements, limitations, and configuration options apply to each platform, as described in the Release Notes available on the http://cytoscape.org website.

Getting Started

Install Java

If not already installed on your computer, download and install Java SE 6. Cytoscape functionality has not been verified yet with SE 7. Link to download SE 6: Java SE 6

Install Cytoscape

A quick note on upgrading

If you are installing Cytoscape for the first time on your workstation, skip to the Download section below.

There should really be no issue in upgrading. If you have a previous installation you have two options:

1. Starting with a clean slate. For this you should delete your previous installation directory and the CytoscapeConfiguration directory (see below for the location of this directory).

2. Just keep what you have and simply pick a distinct, new directory for installation. In the unlikely event that you should encounter any problem, delete the .props files in your CytoscapeConfiguration directory. If that doesn't help try deleting the CytoscapeConfiguration directory. This latter step will cause you to lose all of the apps that you have installed via the App Store, so only do that if you are having problems or if you don't mind reinstalling your apps. The core apps will not be affected by this step.

Download

There are a number of options for downloading and installing Cytoscape. See the download page at the http://cytoscape.org website for all options.

• Automatic installation packages exist for Windows, Mac OS X, and Linux platforms.
• You can install Cytoscape from a compressed archive distribution.
• You can build Cytoscape from the source code.

• You can check out the latest and greatest software from our Subversion repository.

Cytoscape installations (regardless of platform) containing the following files and directories:

The p/ directory signifies the program directory, which varies from platform to platform.

The u/ directory signifies the user's home directory, which varies from user to user and from platform to platform.

Launch the application

As with any application: double-click on the icon created by the installer or by running cytoscape.sh from the command line (Linux or Mac OS X) or double-clicking cytoscape.bat (Windows).

Alternatively, for more advanced users, you can pass the .jar file to Java directly using the command java -Xmx512M -jar cytoscape.jar -p plugins. The -Xmx512M flag tells java to allocate more memory for Cytoscape and the -p plugins option tells cytoscape to load all of the apps (called plugins in previous Cytoscape versions) in the apps directory. Loading the apps is important because many key features like layouts, filters and the attribute browser are included with Cytoscape as apps in the plugins directory. See the Command Line chapter for more detail. In Windows, it is also possible to directly double-click the .jar file to launch it. However, this does not allow specification of command-line arguments (such as the location of the apps directory).

After launching Cytoscape a window will appear that looks like this (captured on Mac OS 10.7.4):

If your Cytoscape window does not resemble this, further configuration may be required. Consult the Release Notes available on the http://cytoscape.org website.

Note on Memory Consumption

For most regular users Cytoscape will estimate the proper amount of memory, if so; you can skip this section and go for the Quick Tour directly.

For users interested in loading large networks, the amount of memory needed by Cytoscape has to be increased. Memory usage depends on both number of network objects (nodes+edges) and the number of attributes. Here are some rough suggestions for memory allocation:

Suggested Memory Size Without View

Suggested Memory Size With View

Specific memory configuration recommendations for each platform may be described in the Release Notes available on the http://cytoscape.org website.

Overall Memory Size for Cytoscape

To increase the maximum memory size for Cytoscape, you can specify it in a file, residing in the same directory as the Cytoscape executable, called Cytoscape.vmoptions with one option per line and lines separated by linefeeds. The last line must also be followed by a linefeed. The one exception to this rule is the MacOS platform if you are launching Cytoscape by clicking on the Cytoscape icon. (In that case you will have to edit the .../Cytoscape.app/Contents/Info.plist file instead!) For example, if you want to assign 1GB of memory, create the Cytoscape.vmoptions file containing the single line (Do not forget the linefeed at the end of the line!):

-Xmx1GB

Stack Size

There is one more option related to memory allocation. Some of the functions in Cytoscape use larger stack space (a temporary memory for some operations, such as Layout). Since this value is set independently from the Xmx value above, sometimes Layout algorithms fails due to the out of memory error. To avoid this, you can set larger heap size by using the -Xss option. If layout fails for large networks, please try the following:

-Xmx1GB -Xss10M

The option -Xss10M means set the heap size to 10MB. In many cases, this solves out of memory error for Layouts.

Randomly generated scale-free network with 500K nodes and 500k edges: If memory parameters are set properly, you can visualize huge networks. In this example, about 5GB of memory is used by Cytoscape. Stack size is set to 10MB. To use large memory space (4GB+) you need 64-bit version operating system AND 64-bit version Java SE 6.

Note: Some of the web service clients are multi-thread programs and each thread uses the memory size specified by -Xss option. If web service clients fails due to the out of memory error, please reduce the stack size and try again.

For more details, see How_to_increase_memory_for_Cytoscape.

Note on Directory Location

For the application to work properly, all files should be left in the directory in which they were unpacked. The core Cytoscape application assumes this directory structure when looking for the various libraries needed to run the application. If you are adventurous, you can get creative with the $CLASSPATH and/or the cytoscape.jar manifest file and run Cytoscape from any location you want.