From 95a9ed853dc4ee1642a581decfe8c1a6e5a2ecdd Mon Sep 17 00:00:00 2001 From: Geraldine Van der Auwera Date: Fri, 15 Mar 2013 13:26:05 -0400 Subject: [PATCH 1/3] Made some documentation updates & fixes --Mostly doc block tweaks --Added @DocumentedGATKFeature to some walkers that were undocumented because they were ending up in "uncategorized". Very important for GSA: if a walker is in public or protected, it HAS to be properly tagged-in. If it's not ready for the public, it should be in private. --- .../gatk/walkers/annotator/Coverage.java | 3 ++- .../gatk/walkers/annotator/FisherStrand.java | 13 ++++++++---- .../gatk/walkers/annotator/GCContent.java | 2 +- .../bqsr/RecalibrationArgumentCollection.java | 6 +++--- .../bqsr/RecalibrationPerformance.java | 14 +++++++++++-- .../targets/BaseCoverageDistribution.java | 14 ++++++++----- .../sting/utils/recalibration/RecalUtils.java | 2 +- .../walkers/coverage/DepthOfCoverage.java | 2 +- .../diagnostics/CoveredByNSamplesSites.java | 14 +++++++++---- .../variantutils/GenotypeConcordance.java | 20 +++++++++++-------- 10 files changed, 60 insertions(+), 30 deletions(-) diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/Coverage.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/Coverage.java index 5138ac9af..5c48417ac 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/Coverage.java +++ b/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 + *

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 + *

*/ public class Coverage extends InfoFieldAnnotation implements StandardAnnotation, ActiveRegionBasedAnnotation { diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/FisherStrand.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/FisherStrand.java index 39fdcb707..7960a3ce2 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/FisherStrand.java +++ b/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 - * 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 - * calculated for certain complex indel cases or for multi-allelic sites. + * Phred-scaled p-value using Fisher's Exact Test to detect strand bias + * + *

Phred-scaled p-value using Fisher's Exact Test to detect strand bias (the variation + * being seen on only the forward or only the reverse strand) in the reads. More bias is + * indicative of false positive calls. + *

+ * + *

Caveat

+ *

The Fisher Strand test may not be calculated for certain complex indel cases or for multi-allelic sites.

*/ public class FisherStrand extends InfoFieldAnnotation implements StandardAnnotation, ActiveRegionBasedAnnotation { private final static Logger logger = Logger.getLogger(FisherStrand.class); diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/GCContent.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/GCContent.java index a4b1b1b49..827e39c11 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/annotator/GCContent.java +++ b/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 * *

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.

* diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationArgumentCollection.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationArgumentCollection.java index 447569643..0a4899f1c 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationArgumentCollection.java +++ b/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 flag which governs how the recalibrator handles the + * BaseRecalibrator accepts a --solid_recal_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 flag which governs how the recalibrator handles + * BaseRecalibrator accepts a --solid_nocall_strategy 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. */ diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationPerformance.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationPerformance.java index d0af08d90..271617059 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/bqsr/RecalibrationPerformance.java +++ b/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 + * + *

This tool aims to evaluate the results of the Base Quality Score Recalibration (BQSR) process.

+ * + *

Caveat

+ *

This tool is currently experimental. We do not provide documentation nor support for its operation.

+ * */ - +@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 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") diff --git a/protected/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/targets/BaseCoverageDistribution.java b/protected/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/targets/BaseCoverageDistribution.java index b70581dd3..53b7cebaa 100644 --- a/protected/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/targets/BaseCoverageDistribution.java +++ b/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 * *

* Features of this walker: - *

  • includes a smart counting of uncovered bases without visiting the uncovered loci.
    • + *
  • includes a smart counting of uncovered bases without visiting the uncovered loci
    • *
  • includes reads with deletions in the loci (optionally can be turned off)
    • *

    * @@ -91,10 +94,11 @@ import java.util.Map; * -fd \ * -o report.grp * - * User: carneiro - * Date: 1/27/13 - * Time: 11:16 AM + * + * @author carneiro + * @since 1/27/13 */ +@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} ) public class BaseCoverageDistribution extends LocusWalker, Map>> { /** * The output GATK Report table diff --git a/protected/java/src/org/broadinstitute/sting/utils/recalibration/RecalUtils.java b/protected/java/src/org/broadinstitute/sting/utils/recalibration/RecalUtils.java index ce2869e94..ae6b56e19 100644 --- a/protected/java/src/org/broadinstitute/sting/utils/recalibration/RecalUtils.java +++ b/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 { diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverage.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverage.java index 61574d947..29016af43 100644 --- a/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverage.java +++ b/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) diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/CoveredByNSamplesSites.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/CoveredByNSamplesSites.java index 92034da70..506ef2c72 100644 --- a/public/java/src/org/broadinstitute/sting/gatk/walkers/diagnostics/CoveredByNSamplesSites.java +++ b/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 * *

    - * 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. + *

    + * *

    Input

    *

    * A variant file and optionally min coverage and sample percentage values. @@ -60,7 +66,7 @@ import java.util.Collection; * An intervals file. *

    * - *

    Examples

    + *

    Example

    * 
      * java -Xmx2g -jar GenomeAnalysisTK.jar \
  *   -R ref.fasta \
@@ -71,7 +77,7 @@ import java.util.Collection;
  *
    * */ - +@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class} ) @By(DataSource.REFERENCE_ORDERED_DATA) public class CoveredByNSamplesSites extends RodWalker implements TreeReducible { diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java index 048c7ef77..35213af34 100644 --- a/public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java +++ b/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 - * per-sample and aggregate counts and frequencies, a summary table for NRD/NRS, and a table for site allele overlaps. + * Genotype concordance (per-sample and aggregate counts and frequencies, NRD/NRS and site allele overlaps) between two callsets * *

    - * 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). * - *

    INPUT

    + *

    Input

    *

    * 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. + * * (Optional) Jexl expressions for genotype-level filtering of EVAL or COMP genotypes, specified via the -gfe and * -cfe arguments, respectively. + *

    * - *

    OUTPUT

    - * Genotype Concordance writes a GATK report to the specified (via -o) file, consisting of multiple tables of counts + *

    Output

    + * 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>,ConcordanceMetrics> { /** From 6b4d88ebe96d3383a0778c6f8a3bbf6bd88ccaee Mon Sep 17 00:00:00 2001 From: Geraldine Van der Auwera Date: Fri, 15 Mar 2013 16:34:29 -0400 Subject: [PATCH 2/3] Created ListAnnotations utility (extends CommandLineProgram) --Refactored listAnnotations basic method out of VA into HelpUtils --HelpUtils.listAnnotations() is now called by both VA and the new ListAnnotations utility (lives in sting.tools) --This way we keep the VA --list option but we also offer a way to list annotations without a full valid VA command-line, which was a pain users continually complained about --We could get rid of the VA --list option altogether ...? --- .../walkers/annotator/VariantAnnotator.java | 30 ++----- .../sting/tools/CatVariants.java | 15 ++-- .../sting/tools/ListAnnotations.java | 85 +++++++++++++++++++ .../sting/utils/help/HelpConstants.java | 1 + .../sting/utils/help/HelpUtils.java | 29 +++++++ 5 files changed, 129 insertions(+), 31 deletions(-) create mode 100644 public/java/src/org/broadinstitute/sting/tools/ListAnnotations.java diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java index 330d29c79..301baaba3 100644 --- a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java +++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java @@ -36,10 +36,10 @@ 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; @@ -47,7 +47,6 @@ import org.broadinstitute.variant.variantcontext.writer.VariantContextWriter; import java.util.*; - /** * Annotates variant calls with context information. * @@ -165,7 +164,7 @@ public class VariantAnnotator extends RodWalker 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 +176,7 @@ public class VariantAnnotator extends RodWalker 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 +184,14 @@ public class VariantAnnotator extends RodWalker implements Ann private VariantAnnotatorEngine engine; - - private void listAnnotationsAndExit() { - System.out.println("\nStandard annotations in the list below are marked with a '*'."); - List> infoAnnotationClasses = new PluginManager(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> genotypeAnnotationClasses = new PluginManager(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.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 ) - listAnnotationsAndExit(); + HelpUtils.listAnnotations(); + System.exit(0); // get the list of all sample names from the variant VCF input rod, if applicable List rodName = Arrays.asList(variantCollection.variants.getName()); diff --git a/public/java/src/org/broadinstitute/sting/tools/CatVariants.java b/public/java/src/org/broadinstitute/sting/tools/CatVariants.java index e1dd2c255..ad77b2548 100644 --- a/public/java/src/org/broadinstitute/sting/tools/CatVariants.java +++ b/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 * *

    * 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> * + *

    Important note

    + *

    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.

    * - *

    Examples

    + *

    Example

    * 
    - * 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    [sorted (optional)]");
+        System.err.println("Usage: java -cp dist/GenomeAnalysisTK.jar org.broadinstitute.sting.tools.CatVariants    [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)");
diff --git a/public/java/src/org/broadinstitute/sting/tools/ListAnnotations.java b/public/java/src/org/broadinstitute/sting/tools/ListAnnotations.java
new file mode 100644
index 000000000..fabcf828a
--- /dev/null
+++ b/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
+ *
+ * 
    This is a very simple utility tool that retrieves available annotations for use with tools such as
+ * UnifiedGenotyper, HaplotypeCaller and VariantAnnotator.
    
+ *
+ * 
    Important note
    
+ * 
    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.
    
+ *
+ * 
    Usage
    
+ * 
    java -cp GenomeAnalysisTK.jar org.broadinstitute.sting.tools.ListAnnotations
    
+ *
+ * @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);
+        }
+    }
+}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java b/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java
index f99ff7538..2ed35d848 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java
+++ b/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;
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java b/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java
index 81606d2f3..9a23fd022 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java
+++ b/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> infoAnnotationClasses = new PluginManager(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> genotypeAnnotationClasses = new PluginManager(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.class).getInterfaces() )
+            System.out.println("\t" + c.getSimpleName());
+        System.out.println();
+    }
+
 }
\ No newline at end of file

From d70bf647379cc8f1eb9a2018d539ec88a86f4702 Mon Sep 17 00:00:00 2001
From: Geraldine Van der Auwera 
Date: Fri, 15 Mar 2013 16:41:14 -0400
Subject: [PATCH 3/3] Created new DeprecatedToolChecks class 	--Based on
 existing code in GenomeAnalysisEngine 	--Hashmaps hold mapping of deprecated
 tool name to version number and recommended replacement (if any) 
 --Using FastUtils for maps; specifically Object2ObjectMap but there could be
 a better type for Strings... 	--Added user exception for deprecated
 annotations 	--Added deprecation check to
 AnnotationInterfaceManager.validateAnnotations 	--Run when annotations
 are initialized 	--Made annotation sets instead of lists

---
 .../sting/gatk/GenomeAnalysisEngine.java      | 41 ++------
 .../walkers/annotator/VariantAnnotator.java   |  6 +-
 .../annotator/VariantAnnotatorEngine.java     |  2 +-
 .../AnnotationInterfaceManager.java           | 12 ++-
 .../sting/utils/DeprecatedToolChecks.java     | 95 +++++++++++++++++++
 .../sting/utils/exceptions/UserException.java |  8 +-
 6 files changed, 121 insertions(+), 43 deletions(-)
 create mode 100644 public/java/src/org/broadinstitute/sting/utils/DeprecatedToolChecks.java

diff --git a/public/java/src/org/broadinstitute/sting/gatk/GenomeAnalysisEngine.java b/public/java/src/org/broadinstitute/sting/gatk/GenomeAnalysisEngine.java
index e45a750ba..2d8b9cd9a 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/GenomeAnalysisEngine.java
+++ b/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 deprecatedGATKWalkers = new HashMap();
-    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
     }
 
     /**
diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java
index 301baaba3..f2bd6c14c 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java
+++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotator.java
@@ -44,6 +44,7 @@ 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.*;
 
@@ -155,7 +156,7 @@ public class VariantAnnotator extends RodWalker 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 expressionsToUse = new ArrayList();
+    protected Set expressionsToUse = new ObjectOpenHashSet();
 
     /**
      * Note that the -XL argument can be used along with this one to exclude annotations.
@@ -189,9 +190,10 @@ public class VariantAnnotator extends RodWalker implements Ann
      */
     public void initialize() {
 
-        if ( LIST )
+        if ( LIST ) {
             HelpUtils.listAnnotations();
             System.exit(0);
+        }
 
         // get the list of all sample names from the variant VCF input rod, if applicable
         List rodName = Arrays.asList(variantCollection.variants.getName());
diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotatorEngine.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotatorEngine.java
index c5703afc8..695868bb1 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/VariantAnnotatorEngine.java
+++ b/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 expressionsToUse) {
+    public void initializeExpressions(Set expressionsToUse) {
         // set up the expressions
         for ( String expression : expressionsToUse )
             requestedExpressions.add(new VAExpression(expression, walker.getResourceRodBindings()));
diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/interfaces/AnnotationInterfaceManager.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/interfaces/AnnotationInterfaceManager.java
index 221887158..59b4b1b3b 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/interfaces/AnnotationInterfaceManager.java
+++ b/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 )
-                throw new UserException.BadArgumentValue("annotation", "Class " + annotation + " is not found; please check that you have specified the class name correctly");
+            if ( annotationClass == null ) {
+                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");
+                }
+            }
         }
     }
 
diff --git a/public/java/src/org/broadinstitute/sting/utils/DeprecatedToolChecks.java b/public/java/src/org/broadinstitute/sting/utils/DeprecatedToolChecks.java
new file mode 100644
index 000000000..e20872c5b
--- /dev/null
+++ b/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();
+    }
+
+}
diff --git a/public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java b/public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java
index b3c5bd2c7..fcc132ffe 100644
--- a/public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java
+++ b/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));