Tagged with #gatkdocs
97 documentation articles | 0 announcements | 3 forum discussions


Comments (0)

The GATK discovers walker documentation by reading it out of the Javadoc, Sun's design pattern for providing documentation for packages and classes. This page will provide an extremely brief explanation of how to write Javadoc; more information on writing javadoc comments can be found in Sun's documentation.

1. Adding walker and package descriptions to the help text

The GATK's build system uses the javadoc parser to extract the javadoc for classes and packages and embed the contents of that javadoc in the help system. If you add Javadoc to your package or walker, it will automatically appear in the help. The javadoc parser will pick up on 'standard' javadoc comments, such as the following, taken from PrintReadsWalker:

/**
 * This walker prints out the input reads in SAM format.  Alternatively, the walker can write reads into a specified BAM file.
 */

You can add javadoc to your package by creating a special file, package-info.java, in the package directory. This file should consist of the javadoc for your package plus a package descriptor line. One such example follows:

/**
 * @help.display.name Miscellaneous walkers (experimental)
 */
package org.broadinstitute.sting.playground.gatk.walkers;

Additionally, the GATK provides two extra custom tags for overriding the information that ultimately makes it into the help.

  • @help.display.name Changes the name of the package as it appears in help. Note that the name of the walker cannot be changed as it is required to be passed verbatim to the -T argument.

  • @help.summary Changes the description which appears on the right-hand column of the help text. This is useful if you'd like to provide a more concise description of the walker that should appear in the help.

  • @help.description Changes the description which appears at the bottom of the help text with -T <your walker> --help is specified. This is useful if you'd like to present a more complete description of your walker.

2. Hiding experimental walkers (use sparingly, please!)

Walkers can be hidden from the documentation system by adding the @Hidden annotation to the top of each walker. @Hidden walkers can still be run from the command-line, but their documentation will not be visible to end users. Please use this functionality sparingly to avoid walkers with hidden command-line options that are required for production use.

3. Disabling building of help

Because the building of our help text is actually heavyweight and can dramatically increase compile time on some systems, we have a mechanism to disable help generation.

Compile with the following command:

ant -Ddisable.help=true

to disable generation of help.

Comments (0)

The GATKDocs are what we call "Technical Documentation" in the Guide section of this website. The HTML pages are generated automatically at build time from specific blocks of documentation in the source code.

The best place to look for example documentation for a GATK walker is GATKDocsExample walker in org.broadinstitute.sting.gatk.examples. This is available here.

Below is the reproduction of that file from August 11, 2011:

/**
 * [Short one sentence description of this walker]
 *
 * <p>
 * [Functionality of this walker]
 * </p>
 *
 * <h2>Input</h2>
 * <p>
 * [Input description]
 * </p>
 *
 * <h2>Output</h2>
 * <p>
 * [Output description]
 * </p>
 *
 * <h2>Examples</h2>
 * PRE-TAG
 *    java
 *      -jar GenomeAnalysisTK.jar
 *      -T $WalkerName
 * PRE-TAG
 *
 * @category Walker Category
 * @author Your Name
 * @since Date created
 */
public class GATKDocsExample extends RodWalker<Integer, Integer> {
    /**
     * Put detailed documentation about the argument here.  No need to duplicate the summary information
     * in doc annotation field, as that will be added before this text in the documentation page.
     *
     * Notes:
     * <ul>
     *     <li>This field can contain HTML as a normal javadoc</li>
     *     <li>Don't include information about the default value, as gatkdocs adds this automatically</li>
     *     <li>Try your best to describe in detail the behavior of the argument, as ultimately confusing
     *          docs here will just result in user posts on the forum</li>
     * </ul>
     */
    @Argument(fullName="full", shortName="short", doc="Brief summary of argument [~ 80 characters of text]", required=false)
    private boolean myWalkerArgument = false;

    public Integer map(RefMetaDataTracker tracker, ReferenceContext ref, AlignmentContext context) { return 0; }
    public Integer reduceInit() { return 0; }
    public Integer reduce(Integer value, Integer sum) { return value + sum; }
    public void onTraversalDone(Integer result) { }
}
Comments (2)

A new tool has been released!

Check out the documentation at Yamagishi.

Comments (19)

A new tool has been released!

Check out the documentation at VariantsToVCF.

Comments (2)

A new tool has been released!

Check out the documentation at VariantsToTable.

Comments (0)

A new tool has been released!

Check out the documentation at VariantsToPED.

Comments (0)

A new tool has been released!

Check out the documentation at VariantAnnotator.

Comments (0)

A new tool has been released!

Check out the documentation at VariantEval.

Comments (0)

A new tool has been released!

Check out the documentation at ValidatingPileup.

Comments (0)

A new tool has been released!

Check out the documentation at ValidateVariants.

Comments (0)

A new tool has been released!

Check out the documentation at VCFCodec.

Comments (0)

A new tool has been released!

Check out the documentation at ValidateBAQ.

Comments (0)

A new tool has been released!

Check out the documentation at VCF3Codec.

Comments (0)

A new tool has been released!

Check out the documentation at UserException.

Comments (8)

A new tool has been released!

Check out the documentation at UnifiedGenotyper.

Comments (0)

A new tool has been released!

Check out the documentation at UGCallVariants.

Comments (0)

A new tool has been released!

Check out the documentation at TestReadFishing.

Comments (0)

A new tool has been released!

Check out the documentation at TableToVCF.

Comments (0)

A new tool has been released!

Check out the documentation at TableCodec.

Comments (0)

A new tool has been released!

Check out the documentation at SplitSamFile.

Comments (0)

A new tool has been released!

Check out the documentation at SoapSNPCodec.

Comments (2)

A new tool has been released!

Check out the documentation at SnpEff.

Comments (2)

A new tool has been released!

Check out the documentation at SelectVariants.

Comments (0)

A new tool has been released!

Check out the documentation at SelectHeaders.

Comments (0)

A new tool has been released!

Check out the documentation at ScoreSeq.

Comments (0)

A new tool has been released!

Check out the documentation at SampleList.

Comments (0)

A new tool has been released!

Check out the documentation at SampleFilter.

Comments (0)

A new tool has been released!

Check out the documentation at SNPDensity.

Comments (0)

A new tool has been released!

Check out the documentation at SAMReadCodec.

Comments (2)

### This tool is not currently available to the public, sorry.
Comments (0)

A new tool has been released!

Check out the documentation at SAMPileupCodec.

Comments (0)

A new tool has been released!

Check out the documentation at RefSeqCodec.

Comments (1)

A new tool has been released!

Check out the documentation at ReduceReads.

Comments (0)

A new tool has been released!

Check out the documentation at ReadStrandFilter.

Comments (0)

A new tool has been released!

Check out the documentation at ReadValidation.

Comments (0)

A new tool has been released!

Check out the documentation at ReadNameFilter.

Comments (0)

A new tool has been released!

Check out the documentation at RawHapMapCodec.

Comments (0)

A new tool has been released!

Check out the documentation at QuantizeQuals.

Comments (0)

A new tool has been released!

Check out the documentation at QualByDepth.

Comments (0)

A new tool has been released!

Check out the documentation at QCRef.

Comments (0)

A new tool has been released!

Check out the documentation at ProfileRodSystem.

Comments (0)

A new tool has been released!

Check out the documentation at PrintReads.

Comments (0)

A new tool has been released!

Check out the documentation at PlatformFilter.

Comments (2)

A new tool has been released!

Check out the documentation at FlagStat.

Comments (2)

A new tool has been released!

Check out the documentation at FastaReference.

Comments (2)

A new tool has been released!

Check out the documentation at DepthOfCoverage.

Comments (6)

A new tool has been released!

Check out the documentation at CombineVariants.

Comments (7)

A new tool has been released!

Check out the documentation at CGVarToVCF.

Comments (6)

A new tool has been released!

Check out the documentation at BaseRecalibrator.

No posts found with the requested search criteria.
Comments (4)

There are at least two images in the Guide Book that stop Adobe and give an error message. One is on page 94 the other is one page 130 Adobe says "Try..." and then gives an URL with a 32 character random alphanumeric string. LOL I am human, cannot cut and paste it (it vanishes when I try), and cannot possible type 32 random characters with our error. Could you post good URLs to these two images. Thanks

Comments (4)

Having the "Table of Contents" in the back of the GATK Guide Book, caused me considerable time and trouble. I spent hours scanning through pages, looking for topics, for several days, before I found the Table of Contents in the back. I would be surprised if I am the only one this has happened to. Could I respectfully request that you move it to the front?

Comments (4)

I'm looking to find all the entries that change between two calls to UG on the same data. I would like to find all the entries where the call in the variant tract are different from those in the comparison track. So in effect I want those entries that would not be result from -using -conc in SelectVariants. From the documentation is is unclear if the -disc option does this:

A site is considered discordant if there exists some sample in the variant track that has a non-reference genotype and either the site isn't present in this track, the sample isn't present in this track, or the sample is called reference in this track.

What if the comp is HOM_VAR and the variant track is HET? Or if they are both HET but disagree on the specific allele?

Thanks.