BioShell installation guide

Do you have JAVA?

To use any BioShell tool you need to have JAVA installed. So open a terminal (or DOS command prompt in Windows) and type:

java

If you see a documentation for command-line options of JAVA executable, than you can go directly to the next section. Otherwise go to JAVA installation page on Oracle website and download Java Runtime Environment - at least in version 1.5.

If you have access to root account on your machine, you can install JRE for all users, e.g. in /usr/java/jdk1.5.0_06/jre. If not, you can do it on your account, e.g. in /home/john/bin/jre. Remember to edit your .bashrc or .bash_profile script and add JAVA bin directory to your PATH shell variable:

PATH=$PATH:/usr/java/jdk1.5.0_06/jre/bin

Installing BioShell command line tools

Download BioShell distribution from here. To use BioShell, you need two files: bioshell.bioinformatics.jar and bioshell.bioinformatics-mono.jar. For biosimulations, download also bioshell.biosimulations.jar. Then simply copy the downloaded files to the directory of your choice, e.g. to /home/john/bin/BioShell

Once the destination directory contains all the relevant jar files, you have to set up CLASSPATH shell variable, by adding the following line to your startup script. For example, if your shell is bash, add them to .bashrc. The file names added to CLASSPATH must be of course as the files in your local directory.

export CLASSPATH=$CLASSPATH:$HOME/bioshell/bioshell.bioinformatics-2.2.jar:$HOME/bioshell/bioshell.bioinformatics-2.2-mono.jar

If you downloaded other jars, such as bioshell.biosimulations-0.9.jar, you should also add them there. The bioshell should work after re-login to your machine (e.g. you may open a new terminal). You can test it e.g. by the following:

java apps.Seqc -h

If you see an error instead of a help message, double check the CLASSPATH value:

echo $CLASSPATH

The result of the above must include the correct path to the BioShell jar files.

Intalling Jython

With the new BioShell distribution (versions 2.x and above) it is possible to access all its objects from a (more or less) Python level. What does it mean? Well, it can be python, although implemented in java. This tool is called Jython and can be obtained from its website. Download an installer class (at the time of writing this page, the newest stable version has been jython_installer-2.5.3.jar) and launch it - usually double click should work. If not try the following from a terminal:

java -jar jython_installer-2.5.2.jar

The graphical installer will guide you through the process. To make you life easier you may add Jython to your PATH variable. Now you can type jython to get a console that behaves as a regular Python would. At first run, Jython will look for all jar files on your classpath which may take a while. Finally you can try to type some Python commands at Jython prompt:

>>> print 'hello world',1+1*(3-1)
hello world 3

OutOfMemoryError in JAVA

Sometimes your command (either execution of BioShell application or a jython script) may end up with the following message:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

This is because all java applications (in particular Jython, which is a Python interpreter written in JAVA) are executed in a sandbox, called JAVA virtual machine (JVM). For security reasons, JVM limits the amount of RAM that any application may allocate. If your program exceeds this limit, it will be killed. You can however adjust the limit by yourself. In the case of command-line BioShell programs, simply start typing your Trac command with:

java -Xmx1024m apps.Trac

where -Xmx1024m sets up one gigabyte (1024Mb) memory limit for Trac application.