Your first walker

From GSA

Contents 1 Introduction 2 Creating a Walker 3 Examples 4 External walkers and the 'external' directory 4.1 Getting started with external walkers 5 Caveats if using the checked-out codebase

Introduction

The core concept behind GATK is the walker, a class that implements the three core operations: filtering, mapping, and reducing.

filter

reduces the size of the dataset by applying a predicate.

map

Applies a function to each individual element in a dataset, effectively 'mapping' it to a new element.

reduce

Inductively combines the elements of a list. The base case is supplied by the reduceInit() function, and the inductive step is performed by the reduce() function.

Users of the GATK will provide a walker to run their analyses. The engine will produce a result by first filtering the dataset, running a map operation, and finally reducing the map operation to a single result.

Creating a Walker

To be loaded by GATK, the walker must satisfy the following properties:

• It must subclass one of the basic walkers in the org.broadinstitute.sting.gatk.walkers package, most likely ReadWalker or LociWalker.
  • Locus walkers present all the reads, reference bases, and reference-ordered data that overlap a single base in the reference. Locus walkers are best used for analyses that look at each locus independently, such as genotyping.
  • Read walkers present only one read at a time, as well as the reference bases and reference-ordered data that overlap that read.
  • Besides read walkers and locus walkers, the GATK features several other data access patterns, described here.
• The compiled class or jar must be on the current classpath. The Java classpath can be controlled using either the $CLASSPATH environment variable or the JVM's -cp option.

Examples

The best way to get started with the GATK is to explore the walkers we've written. Here are the best walkers to look at when getting started:

• CountLoci ($STING_HOME/java/src/org/broadinstitute/sting/gatk/walkers/qc/CountLociWalker.java) - the simplest locus walker in our codebase. Counts the number of loci walked over in a single run of the GATK.
• CountReads ($STING_HOME/java/src/org/broadinstitute/sting/gatk/walkers/qc/CountReadsWalker.java) - the simplest read walker in our codebase. Counts the number of reads walked over in a single run of the GATK.

For a more sophisticated example taken from our recent paper in Genome Research (and an example using our ReadBackedPileup to select and filter reads):

• GATKPaperGenotyper ($STING_HOME/java/src/org/broadinstitute/sting/gatk/examples/papergenotyper/GATKPaperGenotyper.java - an extremely basic Bayesian genotyper.

Please note that the walker above is NOT the UnifiedGenotyper, our flagship genotyper. While conceptually similar to the UnifiedGenotyper, the GATKPaperGenotyper uses a much simpler calling model for increased clarity and readability.

External walkers and the 'external' directory

The GATK can absorb external walkers placed in a directory of your choosing. By default, that directory is called 'external' and is relative to the Sting svn root directory (for example, ~/src/Sting/external). However, you can choose to place that directory anywhere on the filesystem and specify its complete path using the ant external.dir property.

ant -Dexternal.dir=~/src/external

The GATK will check each directory under the external directory (but not the external directory itself!) for small build scripts. These build scripts must contain at least a 'compile' target that compiles your walker and places the resulting class file into the GATK's class file output directory. The following is a sample compile target:

    <target name="compile" depends="init">
        <javac srcdir="." destdir="${build.dir}" classpath="${gatk.classpath}" />
    </target>

As a convenience, the 'build.dir' ant property will be predefined to be the GATK's class file output directory and the gatk.classpath property will be predefined to be the GATK's core classpath. Once this structure is defined, any invocation of the ant build scripts will build the contents of the external directory as well as the GATK itself.

Getting started with external walkers

We've prepared a Google code project as a demonstration of how to use the 'external' directory. To view this sample code:

• Install the Mercurial distributed version control client, if it is not already present on your system.
• Pull down the example code using the following command:

hg clone https://gatk-community.googlecode.com/hg/ external

• Compile the GATK using 'ant dist'.
• Run the GATK using the following command:

 java -jar dist/GenomeAnalysisTK.jar -T Hello

You should see help for the 'Hello' walker's special set of command-line arguments.

Arguments for Hello:
 -o,--out <out>   An output file presented to the walker.  Will overwrite contents if file exists.

Description:
     An example walker for illustrative purposes.

Caveats if using the checked-out codebase

If you are using checked-out code, there are other examples which are slightly more complicated but demonstrate real uses of the GATK. For a simple implementation (though not to be used for analysis) of a Bayesian genotyper, view the GATKPaperGenotyper.java in the playground section of the code. This walker is a simple genotyper that calls variants using naive Bayesian approach, but demonstrates how to output data to a stream and execute simple base operations.