This page describes how to configure Goby.

Java Compatibility

Please note that at this time Goby is compatible with Java6. Compatibility with Java7 will be addressed in a future release.

Execution PATH

After dowloading and unpacking a new goby distribution, you can always run the goby.jar executable with java in the following way:

java -Xmx2g -jar <path-to-distribution-directory>/goby.jar --mode version

However, it is much simpler to add <path-to-distribution-directory> in your PATH environment variable. After you do this, you can simply run the shortcut goby script:

goby 2g version

(If you obtain an error with the previous command, make sure the script <path-to-distribution-directory>/goby is executable.)
The second argument to the goby shortcut script is the amount of memory to provide when running the Java virtual machine (2 gigabytes are requested in the above example). The argument is exposed because you often need to adjust the memory setting for different activities. The second argument is the Goby mode to run. Goby can run in several modes, each implementing a different utility. You can obtain a list of Goby modes here, or simply type

goby 1g

to obtain the help message for your installed version of Goby.

Each mode has its own help, accessible with the –help/-h option, for instance:

goby 1g fasta-to-compact --help

Goby C/C++ API

The Goby C/C++ API is required to compile aligners with native Goby support (e.g., GSNAP or BWA, see below). Please follow these detailed copy/paste instructions to compile and install this library on your machine.

NGS aligners

Most NGS analyses require to align reads to a reference sequence (a whole genome or cDNA database). You should download and install alignment programs. Goby works best with the following programs:

BWA with Goby support, recommended for DNA-Seq [download]

GNSAP with Goby support, recommended for RNA-Seq, RRBS or Methyl-Seq [download version > 28/3/2011 and configure --with-goby=/path/to/goby. Detailled instructions provided in README with the distribution]

Goby can also work with these aligners by using wrappers that convert input and output of the aligners:

Last, recommended for small RNA or reads with distant homology to the reference [download]

BSMAP, for RRBS or Methyl-Seq [download]

BWA [download] (still supported, but not recommended for use with Goby, install the version with native Goby support instead).

Aligners with native Goby support should be used directly from the command line. Goby will search system paths for the aligners that are run with the align mode wrapper.

R

Some goby modes (e.g., alignment-to-annotation-counts, or discover-sequence-variants) requires native R libraries and rJava to be installed. If you need these modes, follow these installation steps.

1. Install the R distribution.

2. Set the R_HOME environment variable to point to where the R distribution was installed in Step 1. [ on Mac OS, this should work:

export R_HOME=/Library/Frameworks/R.framework/Resources]

3. Run the R console

4. From the R console enter:

 install.packages('rJava')

After installing rJava, run this command in the R console to find out where rJava was installed on your system:

system.file("jri",package="rJava")

On a PC, this may print something like ”C:\Program Files (x86)\R\R-2.10.1\library\rJava\jri”, on a Mac, something like “/Library/Frameworks/R.framework/Resources/library/rJava/jri”.

Set the RJAVA_HOME environment variable to the value system.file returned. The ‘goby’ script located in the distribution will try to pick up this variable and configure the JVM appropriately.The script is the simplest way to run goby. We suggest to edit this script to define R_HOME for your system there.

When running goby without the goby script wrapper (i.e., using java -jar), you need to add the R and rJava libraries to the library path. For example on windows, add

 -Djava.library.path=$RJAVA_HOME

On Unix systems, add the R and JRI paths to the LD_LIBRARY_PATH environment variable.

Multi-threading

Goby is designed to execute certain tasks in parallel where possible through the use of the Parallel Java (PJ) library. By default the Parallel Java library will attempt to use the same number of threads as there are CPUs on the host. To specify the number of threads on the Java command line like this:

 java -Dpj.nt=n ...

where “n” us the number of threads you wish to use.

Logging and other settings

Goby uses the Commons Logging api to display informational messages, however log4j is recommended. Consult the documentation of respective frameworks if you need to configure custom logging. The Goby log configuration file is located under the distribution under config/log4j.properties, see config/log4j-example.properties.

In some instances, it may be helpful to enable assertions by adding “-ea” to the java command line.