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. + *
+ * + *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_modeThis tool aims to evaluate the results of the Base Quality Score Recalibration (BQSR) process.
+ * + *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* Features of this walker: - *
- * 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. + *
+ * ** A variant file and optionally min coverage and sample percentage values. @@ -60,7 +66,7 @@ import java.util.Collection; * An intervals file. *
* - ** 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
- * 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). * - *
* 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. + *
* - ** 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> * + *
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.
* - *
- * 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/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));
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