Developers and administrators of a GobyWeb instance can define new plugins to extend GobyWeb with new functionality. This page describes the plugin system and provides a reference for people who write new plugins or need to maintain existing ones.

There are three categories of GobyWeb plugins:

  • Resources. These plugins define resources such as executable files, scripts, or data files, that other plugins can share access to.
  • Aligners. These plugins provide functionality to align reads to a reference genome. They are used to expose various alignment methods to the end user.
  • Alignment Analyses. These plugins integrate analyses methods that work on sets of alignments. These plugins take alignment files as input, where each alignment is associated with a group, and produce output files that end-users can view.

File System Organization

Plugins are defined in the server-conf/plugins directory on the web app server where GobyWeb is installed. The plugins directory contains one sub-directory for each category of plugin:

ls  server-conf/plugins
aligners	analyses	environment.sh	resources

In addition, the file environment.sh ties plugins to the local environment by defining paths to certain tools and global properties.

Under each directory (aligners, analyses or resources), one can find different directories, named in upper-case. Each of these describes an individual plugin, for instance:

ls server-conf/plugins/resources
GOBY_DEV	LAST_189	SAMTOOLS_0.1.14

Resources

Resources are defined in the server-conf/plugins/resources directory. The directory should be named with the pattern TOOL_VERSION. Please note that this pattern is specific to resources. Under each plugin directory, one finds a configuration file (config.xml) and optional files. For instance, the GOBY_DEV resource directory contains:

ls server-conf/plugins/resources/GOBY_DEV
config.xml	goby.jar

The file config.xml contains the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resourceConfig>
    <name>Goby</name>
    <id>GOBY</id>
    <help>Goby framework and toolbox. See http://goby.campagnelab.org.</help>
    <version>20111024133413</version>
    <files>
        <file>
            <id>GOBY_JAR</id>
            <filename>goby.jar</filename>
        </file>
    </files>
</resourceConfig>

This config file defines a resource called Goby, with identifier GOBY and version number 20111024133413. A help message is given that can be presented to the end user. This resource defines one file, with identifier GOBY_JAR and name goby.jar. The identifier can be used to import the resource in other plugins.

For instance, these statements in an aligner or analysis plugin definition file will cause the GOBY resource to be imported if such a resource can be found with version number larger or equal to 20111021144833:

<requires>
        <resource>
            <id>GOBY</id>
            <version-at-least>20111021144833</version-at-least>
        </resource>
</requires>

Version numbers have the general format long (. long )+, so  20111021144833 is a valid number, as well as 1.2.0.0.1. Version numbers are compared such that 1.2.0.1.0 is a larger version number as 1.2.0.0.1, as would be expected.

 Aligners

Aligner plugins take a read file and produce an alignment against a reference genome indexed and available to GobyWeb. Similarly to resources, aligner plugins are defined in a file called config.xml, directly under the server-conf/plugins/aligners directory.

For instance, the distribution of GobyWeb may contain:

ls server-conf/plugins/aligners/
BWA_BAM		BWA_GOBY	GSNAP_BAM	GSNAP_GOBY	LASTAG_GOBY	LAST_GOBY

In the BWA_BAM directory, you can see:

ls server-conf/plugins/aligners/BWA_BAM/
config.xml	script.sh

In addition to config.xml, there is a bash script called script.sh (by convention).

Two types of aligner plugins can be developed and are explained separately:

  • Aligners that produce BAM output. These aligners run in a node-parallel mode [see BWA_BAM discussion].
  • Aligner that produce Goby output. These aligners run in a grid-parallel mode [see GSNAP_GOBY discussion]

Follow the links to learn more about how to create each type of plugin.