Merge branch 'stable'

public/java/src/org/broadinstitute/sting/gatk/examples/GATKDocsExample.java

@@ -26,6 +26,7 @@ package org.broadinstitute.sting.gatk.examples;
 
 import org.broadinstitute.sting.commandline.Argument;
 import org.broadinstitute.sting.commandline.ArgumentCollection;
+import org.broadinstitute.sting.commandline.Hidden;
 import org.broadinstitute.sting.gatk.arguments.StandardVariantContextInputArgumentCollection;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
@@ -59,6 +60,7 @@ import org.broadinstitute.sting.gatk.walkers.RodWalker;
  * @author Your Name
  * @since Date created
  */
+@Hidden
 public class GATKDocsExample extends RodWalker<Integer, Integer> {
     /**
      * Put detailed documentation about the argument here.  No need to duplicate the summary information

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

@@ -43,6 +43,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * The allele balance (fraction of ref bases over ref + alt bases) across all bialleleic het-called samples
+ */
 public class AlleleBalance extends InfoFieldAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -16,6 +16,9 @@ import org.broadinstitute.sting.utils.variantcontext.VariantContext;
 import java.util.*;
 
 
+/**
+ * The allele balance (fraction of ref bases over ref + alt bases) separately for each bialleleic het-called sample
+ */
 public class AlleleBalanceBySample extends GenotypeAnnotation implements ExperimentalAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, AlignmentContext stratifiedContext, VariantContext vc, Genotype g) {

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

@@ -6,8 +6,9 @@ import org.broadinstitute.sting.utils.variantcontext.Genotype;
 
 import java.util.Map;
 
-
+/**
-
+ * Abstract base class for all annotations that are normalized by depth
+ */
 public abstract class AnnotationByDepth extends InfoFieldAnnotation {
 
 

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

@@ -47,6 +47,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Count of A, C, G, T bases across all samples
+ */
 public class BaseCounts extends InfoFieldAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -13,6 +13,9 @@ import java.util.LinkedHashMap;
 import java.util.List;
 
 
+/**
+ * The phred-scaled p-value (u-based z-approximation) from the Mann-Whitney Rank Sum Test for base qualities (ref bases vs. bases of the alternate allele)
+ */
 public class BaseQualityRankSumTest extends RankSumTest {
     public List<String> getKeyNames() { return Arrays.asList("BaseQRankSum"); }
 

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

@@ -44,6 +44,11 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Allele count in genotypes, for each ALT allele, in the same order as listed;
+ * allele Frequency, for each ALT allele, in the same order as listed; total number
+ * of alleles in called genotypes.
+ */
 public class ChromosomeCounts extends InfoFieldAnnotation implements StandardAnnotation {
 
     private String[] keyNames = { VCFConstants.ALLELE_NUMBER_KEY, VCFConstants.ALLELE_COUNT_KEY, VCFConstants.ALLELE_FREQUENCY_KEY };

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

@@ -16,7 +16,12 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * Total (unfiltered) depth over all samples.
+ *
+ * Affected by downsampling (-dcov) though, so the max value one can obtain for N samples with -dcov D
+ * is N * D
+ */
 public class DepthOfCoverage extends InfoFieldAnnotation implements StandardAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -23,6 +23,25 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * The depth of coverage of each VCF allele in this sample
+ *
+ * Complementary fields that two important ways of thinking about the depth of the data for this sample
+ * at this site. The DP field describe the total depth of reads that passed the Unified Genotypers internal
+ * quality control metrics (like MAPQ > 17, for example), whatever base was present in the read at this site.
+ * The AD values (one for each of REF and ALT fields) is the count of all reads that carried with them the
+ * REF and ALT alleles. The reason for this distinction is that the DP is in some sense reflective of the
+ * power I have to determine the genotype of the sample at this site, while the AD tells me how many times
+ * I saw each of the REF and ALT alleles in the reads, free of any bias potentially introduced by filtering
+ * the reads. If, for example, I believe there really is a an A/T polymorphism at a site, then I would like
+ * to know the counts of A and T bases in this sample, even for reads with poor mapping quality that would
+ * normally be excluded from the statistical calculations going into GQ and QUAL. Please note, however, that
+ * the AD isn't necessarily calculated exactly for indels (it counts as non-reference only those indels that
+ * are actually present and correctly left-aligned in the alignments themselves). Because of this fact and
+ * because the AD includes reads and bases that were filtered by the Unified Genotyper, one should not base
+ * assumptions about the underlying genotype based on it; instead, the genotype likelihoods (PLs) are what
+ * determine the genotype calls (see below).
+ */
 public class DepthPerAlleleBySample extends GenotypeAnnotation implements StandardAnnotation {
 
     private static String REF_ALLELE = "REF";

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

@@ -43,6 +43,11 @@ import org.broadinstitute.sting.utils.variantcontext.VariantContext;
 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.
+ */
 public class FisherStrand extends InfoFieldAnnotation implements StandardAnnotation {
     private static final String FS = "FS";
     private static final double MIN_PVALUE = 1E-320;

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

@@ -17,6 +17,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * The GC content (# GC bases / # all bases) of the reference within 50 bp +/- this site
+ */
 public class GCContent extends InfoFieldAnnotation implements ExperimentalAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -49,6 +49,10 @@ import org.broadinstitute.sting.utils.variantcontext.VariantContext;
 
 import java.util.*;
 
+/**
+ * Consistency of the site with two (and only two) segregating haplotypes. Higher scores
+ * are indicative of regions with bad alignments, often leading to artifactual SNP and indel calls.
+ */
 public class HaplotypeScore extends InfoFieldAnnotation implements StandardAnnotation {
     private final static boolean DEBUG = false;
     private final static int MIN_CONTEXT_WING_SIZE = 10;

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

@@ -19,6 +19,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Phred-scaled P value of genotype-based (using GT field) test for Hardy-Weinberg test for disequilibrium
+ */
 public class HardyWeinberg extends InfoFieldAnnotation implements WorkInProgressAnnotation {
 
     private static final int MIN_SAMPLES = 10;

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

@@ -16,7 +16,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * Largest contiguous homopolymer run of the variant allele in either direction on the reference.
+ */
 public class HomopolymerRun extends InfoFieldAnnotation implements StandardAnnotation {
 
     private boolean ANNOTATE_INDELS = true;

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

@@ -17,14 +17,15 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-/**
- * Created by IntelliJ IDEA.
- * User: rpoplin
- * Date: 5/16/11
- */
 
-// A set of annotations calculated directly from the GLs
+/**
-public class GLstats extends InfoFieldAnnotation implements StandardAnnotation {
+ * Likelihood-based (using PL field) test for the inbreeding among samples.
+ *
+ * A continuous generalization of the Hardy-Weinberg test for disequilibrium that works
+ * well with limited coverage per sample.  See the 1000 Genomes Phase I release for
+ * more information.
+ */
+public class InbreedingCoeff extends InfoFieldAnnotation implements StandardAnnotation {
 
     private static final int MIN_SAMPLES = 10;
 

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

@@ -14,11 +14,7 @@ import org.broadinstitute.sting.utils.variantcontext.VariantContext;
 import java.util.*;
 
 /**
- * Created by IntelliJ IDEA.
+ * Rough category of indel type (insertion, deletion, multi-allelic, other)
- * User: delangel
- * Date: Mar 11, 2011
- * Time: 11:47:33 AM
- * To change this template use File | Settings | File Templates.
  */
 public class IndelType extends InfoFieldAnnotation implements ExperimentalAnnotation {
 

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

@@ -17,6 +17,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Triplet annotation: fraction of MAQP == 0, MAPQ < 10, and count of all mapped reads
+ */
 public class LowMQ extends InfoFieldAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -14,6 +14,9 @@ import java.util.LinkedHashMap;
 import java.util.List;
 
 
+/**
+ * The phred-scaled p-value (u-based z-approximation) from the Mann-Whitney Rank Sum Test for mapping qualities (reads with ref bases vs. those with the alternate allele)
+ */
 public class MappingQualityRankSumTest extends RankSumTest {
 
     public List<String> getKeyNames() { return Arrays.asList("MQRankSum"); }

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

@@ -19,6 +19,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Total count across all samples of mapping quality zero reads
+ */
 public class MappingQualityZero extends InfoFieldAnnotation implements StandardAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -44,11 +44,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Created by IntelliJ IDEA.
+ * Count for each sample of mapping quality zero reads
- * User: asivache
- * Date: Feb 4, 2011
- * Time: 6:46:25 PM
- * To change this template use File | Settings | File Templates.
  */
 public class MappingQualityZeroBySample extends GenotypeAnnotation {
     public Map<String, Object> annotate(RefMetaDataTracker tracker,

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

@@ -17,8 +17,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
-
+ * Fraction of all reads across samples that have mapping quality zero
+ */
 public class MappingQualityZeroFraction extends InfoFieldAnnotation implements ExperimentalAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -17,11 +17,8 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Created by IntelliJ IDEA.
+ * The number of N bases, counting only SOLiD data
- * User: rpoplin
- * Date: 5/16/11
  */
-
 public class NBaseCount extends InfoFieldAnnotation {
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {
         if( stratifiedContexts.size() == 0 )

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

@@ -1,5 +1,6 @@
 package org.broadinstitute.sting.gatk.walkers.annotator;
 
+import org.broadinstitute.sting.commandline.Hidden;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
@@ -15,7 +16,11 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * Variant confidence (given as (AB+BB)/AA from the PLs) / unfiltered depth.
+ *
+ * Low scores are indicative of false positive calls and artifacts.
+ */
 public class QualByDepth extends AnnotationByDepth implements StandardAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -21,6 +21,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Root Mean Square of the mapping quality of the reads across all samples.
+ */
 public class RMSMappingQuality extends InfoFieldAnnotation implements StandardAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -21,7 +21,9 @@ import java.util.List;
 import java.util.Map;
 
 
-
+/**
+ * Abstract root for all RankSum based annotations
+ */
 public abstract class RankSumTest extends InfoFieldAnnotation implements StandardAnnotation {
     static final double INDEL_LIKELIHOOD_THRESH = 0.1;
     static final boolean DEBUG = false;

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

@@ -25,6 +25,7 @@
 
 package org.broadinstitute.sting.gatk.walkers.annotator;
 
+import org.broadinstitute.sting.commandline.Hidden;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
@@ -47,12 +48,9 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Created by IntelliJ IDEA.
+ * Unsupported
- * User: asivache
- * Date: Feb 4, 2011
- * Time: 3:59:27 PM
- * To change this template use File | Settings | File Templates.
  */
+@Hidden
 public class ReadDepthAndAllelicFractionBySample extends GenotypeAnnotation {
 
         private static String REF_ALLELE = "REF";

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

@@ -19,11 +19,8 @@ import java.util.LinkedHashMap;
 import java.util.List;
 
 /**
- * Created by IntelliJ IDEA.
+ * The phred-scaled p-value (u-based z-approximation) from the Mann-Whitney Rank Sum Test for the distance from the end of the read for reads with the alternate allele; if the alternate allele is only seen near the ends of reads this is indicative of error).
- * User: rpoplin
- * Date: 3/30/11
  */
-
 public class ReadPosRankSumTest extends RankSumTest {
 
     public List<String> getKeyNames() { return Arrays.asList("ReadPosRankSum"); }

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

@@ -15,8 +15,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
-
+ * SB annotation value by depth of alt containing samples
+ */
 public class SBByDepth extends AnnotationByDepth {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -41,7 +41,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * List all of the samples in the info field
+ */
 public class SampleList extends InfoFieldAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -17,6 +17,9 @@ import java.util.List;
 import java.util.Map;
 
 
+/**
+ * Fraction of reads containing spanning deletions at this site.
+ */
 public class SpanningDeletions extends InfoFieldAnnotation implements StandardAnnotation {
 
     public Map<String, Object> annotate(RefMetaDataTracker tracker, AnnotatorCompatibleWalker walker, ReferenceContext ref, Map<String, AlignmentContext> stratifiedContexts, VariantContext vc) {

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

@@ -1,5 +1,6 @@
 package org.broadinstitute.sting.gatk.walkers.annotator;
 
+import org.broadinstitute.sting.commandline.Hidden;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
@@ -19,12 +20,9 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Created by IntelliJ IDEA.
+ * Counts of bases from SLX, 454, and SOLiD at this site
- * User: delangel
- * Date: 6/29/11
- * Time: 3:14 PM
- * To change this template use File | Settings | File Templates.
  */
+@Hidden
 public class TechnologyComposition extends InfoFieldAnnotation implements ExperimentalAnnotation {
     private String nSLX = "NumSLX";
     private String n454 ="Num454";

public/java/src/org/broadinstitute/sting/gatk/walkers/qc/DocumentationTest.java

@@ -42,6 +42,7 @@ import java.util.*;
  *
  * <p>Body test</p>
  */
+@Hidden
 public class DocumentationTest extends RodWalker<Integer, Integer> {
     // the docs for the arguments are in the collection
     @ArgumentCollection protected StandardVariantContextInputArgumentCollection variantCollection = new StandardVariantContextInputArgumentCollection();

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

@@ -66,7 +66,8 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
     public boolean includeInDocs(ClassDoc doc) {
         try {
             Class type = HelpUtils.getClassForDoc(doc);
-            return JVMUtils.isConcrete(type);
+            boolean hidden = ! getDoclet().showHiddenFeatures() && type.isAnnotationPresent(Hidden.class);
+            return ! hidden && JVMUtils.isConcrete(type);
         } catch ( ClassNotFoundException e ) {
             return false;
         }