Merge pull request #117 from broadinstitute/gg_handling_deprecated_tools_45941819

gg handling deprecated tools 45941819

protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/Coverage.java

@@ -70,10 +70,11 @@ import java.util.Map;
 /**
  * Total (unfiltered) depth over all samples.
  *
- * While the sample-level (FORMAT) DP field describes the total depth of reads that passed the Unified Genotyper's
+ * <p>While the sample-level (FORMAT) DP field describes the total depth of reads that passed the caller's
  * internal quality control metrics (like MAPQ > 17, for example), the INFO field DP represents the unfiltered depth
  * over all samples.  Note though that the DP is affected by downsampling (-dcov), so the max value one can obtain for
  * N samples with -dcov D is N * D
+ * </p>
  */
 public class Coverage extends InfoFieldAnnotation implements StandardAnnotation, ActiveRegionBasedAnnotation {
 

protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/FisherStrand.java

@@ -69,10 +69,15 @@ import java.util.*;
 
 
 /**
- * Phred-scaled p-value using Fisher's Exact Test to detect strand bias (the variation
+ * Phred-scaled p-value using Fisher's Exact Test to detect strand bias
- * being seen on only the forward or only the reverse strand) in the reads? More bias is
+ *
- * indicative of false positive calls.  Note that the fisher strand test may not be
+ * <p>Phred-scaled p-value using Fisher's Exact Test to detect strand bias (the variation
- * calculated for certain complex indel cases or for multi-allelic sites.
+ * being seen on only the forward or only the reverse strand) in the reads. More bias is
+ * indicative of false positive calls.
+ * </p>
+ *
+ * <h3>Caveat</h3>
+ * <p>The Fisher Strand test may not be calculated for certain complex indel cases or for multi-allelic sites.</p>
  */
 public class FisherStrand extends InfoFieldAnnotation implements StandardAnnotation, ActiveRegionBasedAnnotation {
     private final static Logger logger = Logger.getLogger(FisherStrand.class);

protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/GCContent.java

@@ -68,7 +68,7 @@ import java.util.Map;
 
 
 /**
- * GC content of the reference around this site
+ * GC content of the reference around the given site
  *
  * <p>The GC content is the number of GC bases relative to the total number of bases (# GC bases / # all bases) around this site on the reference.</p>
  *

protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationArgumentCollection.java

@@ -61,7 +61,7 @@ import java.util.List;
  * User: rpoplin
  * Date: Nov 27, 2009
  *
- * A collection of the arguments that are common to both CovariateCounterWalker and TableRecalibrationWalker.
+ * A collection of the arguments that are used for BQSR. Used to be common to both CovariateCounterWalker and TableRecalibrationWalker.
  * This set of arguments will also be passed to the constructor of every Covariate when it is instantiated.
  */
 
@@ -131,14 +131,14 @@ public class RecalibrationArgumentCollection {
     public boolean RUN_WITHOUT_DBSNP = false;
 
     /**
-     * CountCovariates and TableRecalibration accept a --solid_recal_mode <MODE> flag which governs how the recalibrator handles the
+     * BaseRecalibrator accepts a --solid_recal_mode <MODE> flag which governs how the recalibrator handles the
      * reads which have had the reference inserted because of color space inconsistencies.
      */
     @Argument(fullName = "solid_recal_mode", shortName = "sMode", required = false, doc = "How should we recalibrate solid bases in which the reference was inserted? Options = DO_NOTHING, SET_Q_ZERO, SET_Q_ZERO_BASE_N, or REMOVE_REF_BIAS")
     public RecalUtils.SOLID_RECAL_MODE SOLID_RECAL_MODE = RecalUtils.SOLID_RECAL_MODE.SET_Q_ZERO;
 
     /**
-     * CountCovariates and TableRecalibration accept a --solid_nocall_strategy <MODE> flag which governs how the recalibrator handles
+     * BaseRecalibrator accepts a --solid_nocall_strategy <MODE> flag which governs how the recalibrator handles
      * no calls in the color space tag. Unfortunately because of the reference inserted bases mentioned above, reads with no calls in
      * their color space tag can not be recalibrated.
      */

protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationPerformance.java

@@ -47,6 +47,7 @@
 package org.broadinstitute.sting.gatk.walkers.bqsr;
 
 import org.broadinstitute.sting.commandline.*;
+import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.filters.*;
@@ -55,18 +56,27 @@ import org.broadinstitute.sting.gatk.report.GATKReport;
 import org.broadinstitute.sting.gatk.report.GATKReportTable;
 import org.broadinstitute.sting.gatk.walkers.*;
 import org.broadinstitute.sting.utils.exceptions.ReviewedStingException;
+import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
+import org.broadinstitute.sting.utils.help.HelpConstants;
 import org.broadinstitute.sting.utils.recalibration.*;
 
 import java.io.*;
 
 /**
+ * Evaluate the performance of the base recalibration process
+ *
+ * <p>This tool aims to evaluate the results of the Base Quality Score Recalibration (BQSR) process.</p>
+ *
+ * <h3>Caveat</h3>
+ * <p>This tool is currently experimental. We do not provide documentation nor support for its operation.</p>
+ *
  */
-
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} )
 @ReadFilters({MappingQualityZeroFilter.class, MappingQualityUnavailableFilter.class, UnmappedReadFilter.class, NotPrimaryAlignmentFilter.class, DuplicateReadFilter.class, FailsVendorQualityCheckFilter.class})
 @PartitionBy(PartitionType.READ)
 public class RecalibrationPerformance extends RodWalker<Integer, Integer> implements NanoSchedulable {
 
-    @Output(doc="Write output to this file")
+    @Output
     public PrintStream out;
 
     @Input(fullName="recal", shortName="recal", required=false, doc="The input covariates table file")

protected/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/targets/BaseCoverageDistribution.java

@@ -48,6 +48,7 @@ package org.broadinstitute.sting.gatk.walkers.diagnostics.targets;
 
 import org.broadinstitute.sting.commandline.Argument;
 import org.broadinstitute.sting.commandline.Output;
+import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
@@ -55,6 +56,8 @@ import org.broadinstitute.sting.gatk.report.GATKReport;
 import org.broadinstitute.sting.gatk.walkers.LocusWalker;
 import org.broadinstitute.sting.utils.GenomeLoc;
 import org.broadinstitute.sting.utils.GenomeLocParser;
+import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
+import org.broadinstitute.sting.utils.help.HelpConstants;
 
 import java.io.PrintStream;
 import java.util.ArrayList;
@@ -63,11 +66,11 @@ import java.util.LinkedList;
 import java.util.Map;
 
 /**
- * Simple walker to plot the coverage distribution per base.
+ * Simple walker to plot the coverage distribution per base
  *
  * <p>
  *  Features of this walker:
- *  <li>includes a smart counting of uncovered bases without visiting the uncovered loci.</li>
+ *  <li>includes a smart counting of uncovered bases without visiting the uncovered loci</li>
  *  <li>includes reads with deletions in the loci (optionally can be turned off)</li>
  * </p>
  *
@@ -91,10 +94,11 @@ import java.util.Map;
  *   -fd \
  *   -o report.grp
  * </pre>
- * User: carneiro
+ *
- * Date: 1/27/13
+ * @author carneiro
- * Time: 11:16 AM
+ * @since 1/27/13
  */
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} )
 public class BaseCoverageDistribution extends LocusWalker<ArrayList<Integer>, Map<Integer, ArrayList<Long>>> {
     /**
      * The output GATK Report table

protected/java/src/org/broadinstitute/sting/utils/recalibration/RecalUtils.java

@@ -82,7 +82,7 @@ import java.util.*;
  *
  * This helper class holds the data HashMap as well as submaps that represent the marginal distributions collapsed over all needed dimensions.
  * It also has static methods that are used to perform the various solid recalibration modes that attempt to correct the reference bias.
- * This class holds the parsing methods that are shared between CountCovariates and TableRecalibration.
+ * This class holds the parsing methods that are shared between BaseRecalibrator and PrintReads.
  */
 
 public class RecalUtils {

public/java/src/org/broadinstitute/sting/gatk/GenomeAnalysisEngine.java

@@ -67,6 +67,9 @@ import java.io.File;
 import java.util.*;
 import java.util.concurrent.TimeUnit;
 
+import static org.broadinstitute.sting.utils.DeprecatedToolChecks.getWalkerDeprecationInfo;
+import static org.broadinstitute.sting.utils.DeprecatedToolChecks.isDeprecatedWalker;
+
 /**
  * A GenomeAnalysisEngine that runs a specified walker.
  */
@@ -288,40 +291,6 @@ public class GenomeAnalysisEngine {
         //return result;
     }
 
-    // TODO -- Let's move this to a utility class in unstable - but which one?
-    // **************************************************************************************
-    // *                            Handle Deprecated Walkers                               *
-    // **************************************************************************************
-
-    // Mapping from walker name to major version number where the walker first disappeared
-    private static Map<String, String> deprecatedGATKWalkers = new HashMap<String, String>();
-    static {
-        deprecatedGATKWalkers.put("CountCovariates", "2.0");
-        deprecatedGATKWalkers.put("TableRecalibration", "2.0");
-        deprecatedGATKWalkers.put("AlignmentWalker", "2.2");
-        deprecatedGATKWalkers.put("CountBestAlignments", "2.2");
-    }
-
-    /**
-     * Utility method to check whether a given walker has been deprecated in a previous GATK release
-     *
-     * @param walkerName   the walker class name (not the full package) to check
-     */
-    public static boolean isDeprecatedWalker(final String walkerName) {
-        return deprecatedGATKWalkers.containsKey(walkerName);
-    }
-
-    /**
-     * Utility method to check whether a given walker has been deprecated in a previous GATK release
-     *
-     * @param walkerName   the walker class name (not the full package) to check
-     */
-    public static String getDeprecatedMajorVersionNumber(final String walkerName) {
-        return deprecatedGATKWalkers.get(walkerName);
-    }
-
-    // **************************************************************************************
-
     /**
      * Retrieves an instance of the walker based on the walker name.
      *
@@ -333,7 +302,7 @@ public class GenomeAnalysisEngine {
             return walkerManager.createByName(walkerName);
         } catch ( UserException e ) {
             if ( isDeprecatedWalker(walkerName) ) {
-                e = new UserException.DeprecatedWalker(walkerName, getDeprecatedMajorVersionNumber(walkerName));
+                e = new UserException.DeprecatedWalker(walkerName, getWalkerDeprecationInfo(walkerName));
             }
             throw e;
         }
@@ -565,6 +534,8 @@ public class GenomeAnalysisEngine {
         if ( intervals != null && intervals.isEmpty() ) {
             logger.warn("The given combination of -L and -XL options results in an empty set.  No intervals to process.");
         }
+
+        // TODO: add a check for ActiveRegion walkers to prevent users from passing an entire contig/chromosome
     }
 
     /**

public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java

@@ -36,18 +36,18 @@ import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
 import org.broadinstitute.sting.gatk.walkers.*;
 import org.broadinstitute.sting.gatk.walkers.annotator.interfaces.*;
 import org.broadinstitute.sting.utils.help.HelpConstants;
+import org.broadinstitute.sting.utils.help.HelpUtils;
 import org.broadinstitute.sting.utils.variant.GATKVCFUtils;
 import org.broadinstitute.sting.utils.BaseUtils;
 import org.broadinstitute.sting.utils.SampleUtils;
-import org.broadinstitute.sting.utils.classloader.PluginManager;
 import org.broadinstitute.variant.vcf.*;
 import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
 import org.broadinstitute.variant.variantcontext.VariantContext;
 import org.broadinstitute.variant.variantcontext.writer.VariantContextWriter;
+import it.unimi.dsi.fastutil.objects.ObjectOpenHashSet;
 
 import java.util.*;
 
-
 /**
  * Annotates variant calls with context information.
  *
@@ -156,7 +156,7 @@ public class VariantAnnotator extends RodWalker<Integer, Integer> implements Ann
      * If multiple records in the rod overlap the given position, one is chosen arbitrarily.
      */
     @Argument(fullName="expression", shortName="E", doc="One or more specific expressions to apply to variant calls; see documentation for more details", required=false)
-    protected List<String> expressionsToUse = new ArrayList<String>();
+    protected Set<String> expressionsToUse = new ObjectOpenHashSet();
 
     /**
      * Note that the -XL argument can be used along with this one to exclude annotations.
@@ -165,7 +165,7 @@ public class VariantAnnotator extends RodWalker<Integer, Integer> implements Ann
     protected Boolean USE_ALL_ANNOTATIONS = false;
 
     /**
-     * Note that the --list argument requires a fully resolved and correct command-line to work.
+     * Note that the --list argument requires a fully resolved and correct command-line to work. As a simpler alternative, you can use ListAnnotations (see Help Utilities).
      */
     @Argument(fullName="list", shortName="ls", doc="List the available annotations and exit", required=false)
     protected Boolean LIST = false;
@@ -177,7 +177,7 @@ public class VariantAnnotator extends RodWalker<Integer, Integer> implements Ann
     protected Boolean ALWAYS_APPEND_DBSNP_ID = false;
     public boolean alwaysAppendDbsnpId() { return ALWAYS_APPEND_DBSNP_ID; }
 
-    @Argument(fullName="MendelViolationGenotypeQualityThreshold",shortName="mvq",required=false,doc="The genotype quality treshold in order to annotate mendelian violation ratio")
+    @Argument(fullName="MendelViolationGenotypeQualityThreshold",shortName="mvq",required=false,doc="The genotype quality threshold in order to annotate mendelian violation ratio")
     public double minGenotypeQualityP = 0.0;
 
     @Argument(fullName="requireStrictAlleleMatch", shortName="strict", doc="If provided only comp tracks that exactly match both reference and alternate alleles will be counted as concordant", required=false)
@@ -185,33 +185,15 @@ public class VariantAnnotator extends RodWalker<Integer, Integer> implements Ann
 
     private VariantAnnotatorEngine engine;
 
-
-    private void listAnnotationsAndExit() {
-        System.out.println("\nStandard annotations in the list below are marked with a '*'.");
-        List<Class<? extends InfoFieldAnnotation>> infoAnnotationClasses = new PluginManager<InfoFieldAnnotation>(InfoFieldAnnotation.class).getPlugins();
-        System.out.println("\nAvailable annotations for the VCF INFO field:");
-        for (int i = 0; i < infoAnnotationClasses.size(); i++)
-            System.out.println("\t" + (StandardAnnotation.class.isAssignableFrom(infoAnnotationClasses.get(i)) ? "*" : "") + infoAnnotationClasses.get(i).getSimpleName());
-        System.out.println();
-        List<Class<? extends GenotypeAnnotation>> genotypeAnnotationClasses = new PluginManager<GenotypeAnnotation>(GenotypeAnnotation.class).getPlugins();
-        System.out.println("\nAvailable annotations for the VCF FORMAT field:");
-        for (int i = 0; i < genotypeAnnotationClasses.size(); i++)
-            System.out.println("\t" + (StandardAnnotation.class.isAssignableFrom(genotypeAnnotationClasses.get(i)) ? "*" : "") + genotypeAnnotationClasses.get(i).getSimpleName());
-        System.out.println();
-        System.out.println("\nAvailable classes/groups of annotations:");
-        for ( Class c : new PluginManager<AnnotationType>(AnnotationType.class).getInterfaces() )
-            System.out.println("\t" + c.getSimpleName());
-        System.out.println();
-        System.exit(0);
-    }
-
     /**
      * Prepare the output file and the list of available features.
      */
     public void initialize() {
 
-        if ( LIST )
+        if ( LIST ) {
-            listAnnotationsAndExit();
+            HelpUtils.listAnnotations();
+            System.exit(0);
+        }
 
         // get the list of all sample names from the variant VCF input rod, if applicable
         List<String> rodName = Arrays.asList(variantCollection.variants.getName());

public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotatorEngine.java

@@ -104,7 +104,7 @@ public class VariantAnnotatorEngine {
     }
 
     // select specific expressions to use
-    public void initializeExpressions(List<String> expressionsToUse) {
+    public void initializeExpressions(Set<String> expressionsToUse) {
         // set up the expressions
         for ( String expression : expressionsToUse )
             requestedExpressions.add(new VAExpression(expression, walker.getResourceRodBindings()));

public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/interfaces/AnnotationInterfaceManager.java

@@ -25,6 +25,7 @@
 
 package org.broadinstitute.sting.gatk.walkers.annotator.interfaces;
 
+import org.broadinstitute.sting.utils.DeprecatedToolChecks;
 import org.broadinstitute.sting.utils.classloader.PluginManager;
 import org.broadinstitute.sting.utils.exceptions.UserException;
 
@@ -58,7 +59,7 @@ public class AnnotationInterfaceManager {
                 if ( interfaceClass == null )
                     interfaceClass = classMap.get(group + "Annotation");
                 if ( interfaceClass == null )
-                    throw new UserException.BadArgumentValue("group", "Class " + group + " is not found; please check that you have specified the class name correctly");
+                    throw new UserException.BadArgumentValue("group", "Annotation group " + group + " was not found; please check that you have specified the group name correctly");
             }
         }
 
@@ -67,8 +68,13 @@ public class AnnotationInterfaceManager {
             Class annotationClass = classMap.get(annotation);
             if ( annotationClass == null )
                 annotationClass = classMap.get(annotation + "Annotation");
-            if ( annotationClass == null )
+            if ( annotationClass == null ) {
-                throw new UserException.BadArgumentValue("annotation", "Class " + annotation + " is not found; please check that you have specified the class name correctly");
+                if (DeprecatedToolChecks.isDeprecatedAnnotation(annotation) ) {
+                    throw new UserException.DeprecatedAnnotation(annotation, DeprecatedToolChecks.getAnnotationDeprecationInfo(annotation));
+                } else {
+                    throw new UserException.BadArgumentValue("annotation", "Annotation " + annotation + " was not found; please check that you have specified the annotation name correctly");
+                }
+            }
         }
     }
 

public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverage.java

@@ -117,7 +117,7 @@ import java.util.*;
 // todo -- alter logarithmic scaling to spread out bins more
 // todo -- allow for user to set linear binning (default is logarithmic)
 // todo -- formatting --> do something special for end bins in getQuantile(int[] foo), this gets mushed into the end+-1 bins for now
-@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_DATA, extraDocs = {CommandLineGATK.class} )
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} )
 @By(DataSource.REFERENCE)
 @PartitionBy(PartitionType.NONE)
 @Downsample(by= DownsampleType.NONE, toCoverage=Integer.MAX_VALUE)

public/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/CoveredByNSamplesSites.java

@@ -29,12 +29,15 @@ package org.broadinstitute.sting.gatk.walkers.diagnostics;
 import org.broadinstitute.sting.commandline.Argument;
 import org.broadinstitute.sting.commandline.ArgumentCollection;
 import org.broadinstitute.sting.commandline.Output;
+import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.gatk.arguments.StandardVariantContextInputArgumentCollection;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
 import org.broadinstitute.sting.gatk.walkers.*;
 import org.broadinstitute.sting.utils.GenomeLoc;
+import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
+import org.broadinstitute.sting.utils.help.HelpConstants;
 import org.broadinstitute.variant.variantcontext.Genotype;
 import org.broadinstitute.variant.variantcontext.GenotypesContext;
 import org.broadinstitute.variant.variantcontext.VariantContext;
@@ -44,12 +47,15 @@ import java.io.*;
 import java.util.Collection;
 
 /**
- * print intervals file with all the variant sites that have "most" ( >= 90% by default) of the samples with "good" (>= 10 by default)coverage ("most" and "good" can be set in the command line).
+ * Print intervals file with all the variant sites for which most of the samples have good coverage
  *
  * <p>
- * CoveredByNSamplesSites is a GATK tool for filter out sites based on their coverage.
+ * CoveredByNSamplesSites is a GATK tool for filtering out sites based on their coverage.
  * The sites that pass the filter are printed out to an intervals file.
  *
+ * See argument defaults for what constitutes "most" samples and "good" coverage. These parameters can be modified from the command line.
+ * </p>
+ *
  * <h3>Input</h3>
  * <p>
  * A variant file and optionally min coverage and sample percentage values.
@@ -60,7 +66,7 @@ import java.util.Collection;
  * An intervals file.
  * </p>
  *
- * <h3>Examples</h3>
+ * <h3>Example</h3>
  * <pre>
  * java -Xmx2g -jar GenomeAnalysisTK.jar \
  *   -R ref.fasta \
@@ -71,7 +77,7 @@ import java.util.Collection;
  * </pre>
  *
  */
-
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} )
 @By(DataSource.REFERENCE_ORDERED_DATA)
 public class CoveredByNSamplesSites extends RodWalker<GenomeLoc, Integer> implements TreeReducible<Integer> {
 

public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java

@@ -26,6 +26,7 @@
 package org.broadinstitute.sting.gatk.walkers.variantutils;
 
 import org.broadinstitute.sting.commandline.*;
+import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
@@ -33,6 +34,8 @@ import org.broadinstitute.sting.gatk.report.GATKReport;
 import org.broadinstitute.sting.gatk.report.GATKReportTable;
 import org.broadinstitute.sting.gatk.walkers.RodWalker;
 import org.broadinstitute.sting.utils.collections.Pair;
+import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
+import org.broadinstitute.sting.utils.help.HelpConstants;
 import org.broadinstitute.sting.utils.variant.GATKVCFUtils;
 import org.broadinstitute.variant.variantcontext.*;
 import org.broadinstitute.variant.vcf.VCFHeader;
@@ -41,29 +44,30 @@ import java.io.PrintStream;
 import java.util.*;
 
 /**
- * A simple walker for performing genotype concordance calculations between two callsets. Outputs a GATK table with
+ * Genotype concordance (per-sample and aggregate counts and frequencies, NRD/NRS and site allele overlaps) between two callsets
- * per-sample and aggregate counts and frequencies, a summary table for NRD/NRS, and a table for site allele overlaps.
  *
  * <p>
- *  Genotype concordance takes in two callsets (vcfs) and tabulates the number of sites which overlap and share alleles,
+ *  GenotypeConcordance takes in two callsets (vcfs) and tabulates the number of sites which overlap and share alleles,
  *  and for each sample, the genotype-by-genotype counts (for instance, the number of sites at which a sample was
  *  called homozygous reference in the EVAL callset, but homozygous variant in the COMP callset). It outputs these
  *  counts as well as convenient proportions (such as the proportion of het calls in the EVAL which were called REF in
  *  the COMP) and metrics (such as NRD and NRS).
  *
- *  <h2> INPUT </h2>
+ *  <h3>Input</h3>
  *  <p>
  *  Genotype concordance requires two callsets (as it does a comparison): an EVAL and a COMP callset, specified via
- *  the -eval and -comp arguments
+ *  the -eval and -comp arguments.
- *  <p>
+ *
  *  (Optional) Jexl expressions for genotype-level filtering of EVAL or COMP genotypes, specified via the -gfe and
  *  -cfe arguments, respectively.
+ *  </p>
  *
- *  <h2> OUTPUT </h2>
+ *  <h3>Output</h3>
- *  Genotype Concordance writes a GATK report to the specified (via -o) file, consisting of multiple tables of counts
+ *  Genotype Concordance writes a GATK report to the specified file (via -o) , consisting of multiple tables of counts
  *  and proportions. These tables may be optionally moltenized via the -moltenize argument.
  *
  */
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_VARMANIP, extraDocs = {CommandLineGATK.class} )
 public class GenotypeConcordance extends RodWalker<List<Pair<VariantContext,VariantContext>>,ConcordanceMetrics> {
 
     /**

public/java/src/org/broadinstitute/sting/tools/CatVariants.java

@@ -35,7 +35,6 @@ import org.broadinstitute.sting.commandline.Argument;
 import org.broadinstitute.sting.commandline.Input;
 import org.broadinstitute.sting.commandline.Output;
 import org.broadinstitute.sting.commandline.CommandLineProgram;
-import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
 import org.broadinstitute.sting.utils.help.HelpConstants;
 import org.broadinstitute.variant.bcf2.BCF2Codec;
@@ -54,7 +53,7 @@ import java.util.*;
 
 /**
  *
- * Concatenates VCF files of non-overlapped genome intervals, all with the same set of samples.
+ * Concatenates VCF files of non-overlapped genome intervals, all with the same set of samples
  *
  * <p>
  * The main purpose of this tool is to speed up the gather function when using scatter-gather parallelization.
@@ -80,10 +79,14 @@ import java.util.*;
  * A combined VCF. The output file should be 'name.vcf' or 'name.VCF'.
  * <\p>
  *
+ * <h3>Important note</h3>
+ * <p>This is a command-line utility that bypasses the GATK engine. As a result, the command-line you must use to
+ * invoke it is a little different from other GATK tools (see example below), and it does not accept any of the
+ * classic "CommandLineGATK" arguments.</p>
  *
- * <h3>Examples</h3>
+ * <h3>Example</h3>
  * <pre>
- * java -cp dist/GenomeAnalysisTK.jar org.broadinstitute.sting.tools.CatVariants \
+ * java -cp GenomeAnalysisTK.jar org.broadinstitute.sting.tools.CatVariants \
  *    -R ref.fasta \
  *    -V input1.vcf \
  *    -V input2.vcf \
@@ -95,7 +98,7 @@ import java.util.*;
  * @since Jan 2012
  */
 
-@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_VARMANIP, extraDocs = {CommandLineGATK.class} )
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_VARMANIP )
 public class CatVariants extends CommandLineProgram {
     // setup the logging system, used by some codecs
     private static org.apache.log4j.Logger logger = org.apache.log4j.Logger.getRootLogger();
@@ -124,7 +127,7 @@ public class CatVariants extends CommandLineProgram {
      * print usage information
      */
     private static void printUsage() {
-        System.err.println("Usage: java -cp dist/GenomeAnalysisTK.jar org.broadinstitute.sting.tools.AppendVariants <reference> <input VCF or BCF files> <outputFile> [sorted (optional)]");
+        System.err.println("Usage: java -cp dist/GenomeAnalysisTK.jar org.broadinstitute.sting.tools.CatVariants <reference> <input VCF or BCF files> <outputFile> [sorted (optional)]");
         System.err.println("    The input files can be of type: VCF (ends in .vcf or .VCF)");
         System.err.println("                                    BCF2 (ends in .bcf or .BCF)");
         System.err.println("    Output file must be vcf or bcf file (.vcf or .bcf)");

public/java/src/org/broadinstitute/sting/tools/ListAnnotations.java

@@ -0,0 +1,85 @@
+/*
+* Copyright (c) 2012 The Broad Institute
+* 
+* Permission is hereby granted, free of charge, to any person
+* obtaining a copy of this software and associated documentation
+* files (the "Software"), to deal in the Software without
+* restriction, including without limitation the rights to use,
+* copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following
+* conditions:
+* 
+* The above copyright notice and this permission notice shall be
+* included in all copies or substantial portions of the Software.
+* 
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+* THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+package org.broadinstitute.sting.tools;
+
+import org.broadinstitute.sting.commandline.CommandLineProgram;
+import org.broadinstitute.sting.utils.exceptions.UserException;
+import org.broadinstitute.sting.utils.help.DocumentedGATKFeature;
+import org.broadinstitute.sting.utils.help.HelpConstants;
+import org.broadinstitute.sting.utils.help.HelpUtils;
+
+/**
+ * Utility program to print a list of available annotations
+ *
+ * <p>This is a very simple utility tool that retrieves available annotations for use with tools such as
+ * UnifiedGenotyper, HaplotypeCaller and VariantAnnotator.</p>
+ *
+ * <h3>Important note</h3>
+ * <p>This is a command-line utility that bypasses the GATK engine. As a result, the command-line you must use to
+ * invoke it is a little different from other GATK tools (see usage below), and it does not accept any of the
+ * classic "CommandLineGATK" arguments.</p>
+ *
+ * <h3>Usage</h3>
+ * <pre>java -cp GenomeAnalysisTK.jar org.broadinstitute.sting.tools.ListAnnotations</pre>
+ *
+ * @author vdauwera
+ * @since 3/14/13
+ */
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_HELPUTILS )
+public class ListAnnotations extends CommandLineProgram {
+
+    /*
+     * Print usage information
+     *
+     * TODO: would be more convenient if we could just call the program by name instead of the full classpath
+     */
+    private static void printUsage() {
+        System.err.println("Usage: java -cp dist/GenomeAnalysisTK.jar org.broadinstitute.sting.tools.ListAnnotations");
+        System.err.println("    Prints a list of available annotations and exits.");
+    }
+
+    // TODO: override CommandLineProgram bit that offers version, logging etc arguments. We don't need that stuff here and it makes the doc confusing.
+
+    @Override
+    protected int execute() throws Exception {
+
+        HelpUtils.listAnnotations();
+        return 0;
+    }
+
+    public static void main(String[] args){
+        try {
+            ListAnnotations instance = new ListAnnotations();
+            start(instance, args);
+            System.exit(CommandLineProgram.result);
+        } catch ( UserException e ) {
+            printUsage();
+            exitSystemWithUserError(e);
+        } catch ( Exception e ) {
+            exitSystemWithError(e);
+        }
+    }
+}

public/java/src/org/broadinstitute/sting/utils/DeprecatedToolChecks.java

@@ -0,0 +1,95 @@
+/*
+* Copyright (c) 2012 The Broad Institute
+* 
+* Permission is hereby granted, free of charge, to any person
+* obtaining a copy of this software and associated documentation
+* files (the "Software"), to deal in the Software without
+* restriction, including without limitation the rights to use,
+* copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following
+* conditions:
+* 
+* The above copyright notice and this permission notice shall be
+* included in all copies or substantial portions of the Software.
+* 
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+* THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+package org.broadinstitute.sting.utils;
+
+import it.unimi.dsi.fastutil.objects.Object2ObjectMap;
+import it.unimi.dsi.fastutil.objects.Object2ObjectOpenHashMap;
+
+import java.util.*;
+
+/**
+ * Utility class for handling deprecated tools gracefully
+ *
+ * @author vdauwera
+ * @since 3/11/13
+ */
+public class DeprecatedToolChecks {
+
+    // Mapping from walker name to major version number where the walker first disappeared and optional replacement options
+    private static Object2ObjectMap deprecatedGATKWalkers = new Object2ObjectOpenHashMap();
+    static {
+        // Indicate recommended replacement in parentheses if applicable
+        deprecatedGATKWalkers.put("CountCovariates", "2.0 (use BaseRecalibrator instead; see documentation for usage)");
+        deprecatedGATKWalkers.put("AnalyzeCovariates", "2.0 (use BaseRecalibrator instead; see documentation for usage)");
+        deprecatedGATKWalkers.put("TableRecalibration", "2.0 (use PrintReads with -BQSR instead; see documentation for usage)");
+        deprecatedGATKWalkers.put("AlignmentWalker", "2.2 (no replacement)");
+        deprecatedGATKWalkers.put("CountBestAlignments", "2.2 (no replacement)");
+    }
+
+    // Mapping from walker name to major version number where the walker first disappeared and optional replacement options
+    private static Object2ObjectMap deprecatedGATKAnnotations = new Object2ObjectOpenHashMap();
+    static {
+        // Same comments as for walkers
+        deprecatedGATKAnnotations.put("DepthOfCoverage", "2.4 (renamed to Coverage)");
+    }
+
+    /**
+     * Utility method to check whether a given walker has been deprecated in a previous GATK release
+     *
+     * @param walkerName   the walker class name (not the full package) to check
+     */
+    public static boolean isDeprecatedWalker(final String walkerName) {
+        return deprecatedGATKWalkers.containsKey(walkerName);
+    }
+
+    /**
+     * Utility method to check whether a given annotation has been deprecated in a previous GATK release
+     *
+     * @param annotationName   the annotation class name (not the full package) to check
+     */
+    public static boolean isDeprecatedAnnotation(final String annotationName) {
+        return deprecatedGATKAnnotations.containsKey(annotationName);
+    }
+
+    /**
+     * Utility method to pull up the version number at which a walker was deprecated and the suggested replacement, if any
+     *
+     * @param walkerName   the walker class name (not the full package) to check
+     */
+    public static String getWalkerDeprecationInfo(final String walkerName) {
+        return deprecatedGATKWalkers.get(walkerName).toString();
+    }
+
+    /**
+     * Utility method to pull up the version number at which an annotation was deprecated and the suggested replacement, if any
+     *
+     * @param annotationName   the annotation class name (not the full package) to check
+     */
+    public static String getAnnotationDeprecationInfo(final String annotationName) {
+        return deprecatedGATKAnnotations.get(annotationName).toString();
+    }
+
+}

public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java

@@ -371,14 +371,18 @@ public class UserException extends ReviewedStingException {
         }
     }
 
-
-
     public static class DeprecatedWalker extends UserException {
         public DeprecatedWalker(String walkerName, String version) {
             super(String.format("Walker %s is no longer available in the GATK; it has been deprecated since version %s", walkerName, version));
         }
     }
 
+    public static class DeprecatedAnnotation extends UserException {
+        public DeprecatedAnnotation(String annotationName, String version) {
+            super(String.format("Annotation %s is no longer available in the GATK; it has been deprecated since version %s", annotationName, version));
+        }
+    }
+
     public static class CannotExecuteQScript extends UserException {
         public CannotExecuteQScript(String message) {
             super(String.format("Unable to execute QScript: " + message));

public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java

@@ -56,6 +56,7 @@ public class HelpConstants {
     public final static String DOCS_CAT_VARDISC = "Variant Discovery Tools";
     public final static String DOCS_CAT_VARMANIP = "Variant Evaluation and Manipulation Tools";
     public final static String DOCS_CAT_TEST = "Testing Tools";
+    public final static String DOCS_CAT_HELPUTILS = "Help Utilities";
 
     public static String forumPost(String post) {
     	return GATK_FORUM_URL + post;

public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java

@@ -28,9 +28,15 @@ package org.broadinstitute.sting.utils.help;
 import com.sun.javadoc.FieldDoc;
 import com.sun.javadoc.PackageDoc;
 import com.sun.javadoc.ProgramElementDoc;
+import org.broadinstitute.sting.gatk.walkers.annotator.interfaces.AnnotationType;
+import org.broadinstitute.sting.gatk.walkers.annotator.interfaces.GenotypeAnnotation;
+import org.broadinstitute.sting.gatk.walkers.annotator.interfaces.InfoFieldAnnotation;
+import org.broadinstitute.sting.gatk.walkers.annotator.interfaces.StandardAnnotation;
 import org.broadinstitute.sting.utils.classloader.JVMUtils;
+import org.broadinstitute.sting.utils.classloader.PluginManager;
 
 import java.lang.reflect.Field;
+import java.util.List;
 
 public class HelpUtils {
 
@@ -70,4 +76,27 @@ public class HelpUtils {
                 String.format("%s", doc.name());
     }
 
+    /**
+     * Simple method to print a list of available annotations.
+     */
+    public static void listAnnotations() {
+        System.out.println("\nThis is a list of available Variant Annotations for use with tools such as UnifiedGenotyper, HaplotypeCaller and VariantAnnotator. Please see the Technical Documentation for more details about these annotations:");
+        System.out.println("http://www.broadinstitute.org/gatk/gatkdocs/");
+        System.out.println("\nStandard annotations in the list below are marked with a '*'.");
+        List<Class<? extends InfoFieldAnnotation>> infoAnnotationClasses = new PluginManager<InfoFieldAnnotation>(InfoFieldAnnotation.class).getPlugins();
+        System.out.println("\nAvailable annotations for the VCF INFO field:");
+        for (int i = 0; i < infoAnnotationClasses.size(); i++)
+            System.out.println("\t" + (StandardAnnotation.class.isAssignableFrom(infoAnnotationClasses.get(i)) ? "*" : "") + infoAnnotationClasses.get(i).getSimpleName());
+        System.out.println();
+        List<Class<? extends GenotypeAnnotation>> genotypeAnnotationClasses = new PluginManager<GenotypeAnnotation>(GenotypeAnnotation.class).getPlugins();
+        System.out.println("\nAvailable annotations for the VCF FORMAT field:");
+        for (int i = 0; i < genotypeAnnotationClasses.size(); i++)
+            System.out.println("\t" + (StandardAnnotation.class.isAssignableFrom(genotypeAnnotationClasses.get(i)) ? "*" : "") + genotypeAnnotationClasses.get(i).getSimpleName());
+        System.out.println();
+        System.out.println("\nAvailable classes/groups of annotations:");
+        for ( Class c : new PluginManager<AnnotationType>(AnnotationType.class).getInterfaces() )
+            System.out.println("\t" + c.getSimpleName());
+        System.out.println();
+    }
+
 }