This page describes how to configure Goby.

Contents

Java Compatibility

Please note that at this time Goby is compatible with Java 7+.

Execution PATH

After downloading 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 -Dlog4j.configuration=<path-to-distribution-directory>/config/goby-logback.xml --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 wrapper 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 wrapper 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

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.
Typically, the binary distribution is not compiled to with the support for shared libraries. This is requested by the rJava package used by some goby modes. In order to verify if the support is enabled, check if the libR.so is available in the R_HOME/lib folder. If not, you must download and compile R from its source distribution. R must be compiled using –enable-R-shlib as follows:

 ./configure --enable-R-shlib
 make
 make rhome=/path/to/R/home install

If you do not have administrator permissions on the target machine, you may need to change the destination folder by passing the prefix option in the last step:

make rhome=/path/to/R/home prefix=/path/where/install/R-dist install

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/lib

On Unix systems, add the R/lib 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. You may make this configuration in copies of the wrapper, for instance goby-2t to run with two threads.

Logging and other settings

Goby uses the simple logging facade api to display informational messages. We use Logback as a logging implementation. Configuration of logging is done by the goby wrapper.  Have a look at the wrapper to locate the logging configuration file.

In some instances, it may be helpful to enable assertions by adding “-ea” to the java command line. You may enable assertions in the wrapper, immediately before the first -D, on the java command line.