From 436f6eb52ba9a279a6c3af63749bfe92ad4e925c Mon Sep 17 00:00:00 2001
From: Christopher Hartl <chartl@broadinstitute.org>
Date: Wed, 7 Sep 2011 08:53:30 -0400
Subject: [PATCH] Reverting Eric's change and pushing in some
 command-line-option documentation.

---
 .../coverage/DepthOfCoverageWalker.java       | 45 +++++++++++++++++--
 .../validation/ValidationAmplicons.java       | 19 +++++---
 2 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverageWalker.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverageWalker.java
index 4537f06f8..3a18fe610 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverageWalker.java
+++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/coverage/DepthOfCoverageWalker.java
@@ -60,9 +60,6 @@ import java.util.*;
  * and/or percentage of bases covered to or beyond a threshold.
  * Additionally, reads and bases can be filtered by mapping or base quality score.
  *
- * <b>If any of the command-line arguments for this tool are not clear to you,
- * please email chartl at broadinstitute dot org and he will gladly explain them in more detail.</b>
- *
  * <h2>Input</h2>
  * <p>
  * One or more bam files (with proper headers) to be analyzed for coverage statistics
@@ -108,10 +105,19 @@ public class DepthOfCoverageWalker extends LocusWalker<Map<DoCOutputType.Partiti
     @Multiplex(value=DoCOutputMultiplexer.class,arguments={"partitionTypes","refSeqGeneList","omitDepthOutput","omitIntervals","omitSampleSummary","omitLocusTable"})
     Map<DoCOutputType,PrintStream> out;
     
+    /**
+     * Sets the low-coverage cutoff for granular binning. All loci with depth < START are counted in the first bin.
+     */
     @Argument(fullName = "start", doc = "Starting (left endpoint) for granular binning", required = false)
     int start = 1;
+    /**
+     * Sets the high-coverage cutoff for granular binning. All loci with depth > END are counted in the last bin.
+     */
     @Argument(fullName = "stop", doc = "Ending (right endpoint) for granular binning", required = false)
     int stop = 500;
+    /**
+     * Sets the number of bins for granular binning
+     */
     @Argument(fullName = "nBins", doc = "Number of bins to use for granular binning", required = false)
     int nBins = 499;
     @Argument(fullName = "minMappingQuality", shortName = "mmq", doc = "Minimum mapping quality of reads to count towards depth. Defaults to -1.", required = false)
@@ -122,28 +128,59 @@ public class DepthOfCoverageWalker extends LocusWalker<Map<DoCOutputType.Partiti
     byte minBaseQuality = -1;
     @Argument(fullName = "maxBaseQuality", doc = "Maximum quality of bases to count towards depth. Defaults to 127 (Byte.MAX_VALUE).", required = false)
     byte maxBaseQuality = Byte.MAX_VALUE;
+    /**
+     * Instead of reporting depth, report the base pileup at each locus
+     */
     @Argument(fullName = "printBaseCounts", shortName = "baseCounts", doc = "Will add base counts to per-locus output.", required = false)
     boolean printBaseCounts = false;
+    /**
+     * Do not tabulate locus statistics (# loci covered by sample by coverage)
+     */
     @Argument(fullName = "omitLocusTable", shortName = "omitLocusTable", doc = "Will not calculate the per-sample per-depth counts of loci, which should result in speedup", required = false)
     boolean omitLocusTable = false;
+    /**
+     * Do not tabulate interval statistics (mean, median, quartiles AND # intervals by sample by coverage)
+     */
     @Argument(fullName = "omitIntervalStatistics", shortName = "omitIntervals", doc = "Will omit the per-interval statistics section, which should result in speedup", required = false)
     boolean omitIntervals = false;
+    /**
+     * Do not print the total coverage at every base
+     */
     @Argument(fullName = "omitDepthOutputAtEachBase", shortName = "omitBaseOutput", doc = "Will omit the output of the depth of coverage at each base, which should result in speedup", required = false)
     boolean omitDepthOutput = false;
     @Argument(fullName = "printBinEndpointsAndExit", doc = "Prints the bin values and exits immediately. Use to calibrate what bins you want before running on data.", required = false)
     boolean printBinEndpointsAndExit = false;
+    /**
+     * Do not tabulate the sample summary statistics (total, mean, median, quartile coverage per sample)
+     */
     @Argument(fullName = "omitPerSampleStats", shortName = "omitSampleSummary", doc = "Omits the summary files per-sample. These statistics are still calculated, so this argument will not improve runtime.", required = false)
     boolean omitSampleSummary = false;
+    /**
+     * A way of partitioning reads into groups. Can be sample, readgroup, or library.
+     */
     @Argument(fullName = "partitionType", shortName = "pt", doc = "Partition type for depth of coverage. Defaults to sample. Can be any combination of sample, readgroup, library.", required = false)
     Set<DoCOutputType.Partition> partitionTypes = EnumSet.of(DoCOutputType.Partition.sample);
+    /**
+     * Consider a spanning deletion as contributing to coverage. Also enables deletion counts in per-base output.
+     */
     @Argument(fullName = "includeDeletions", shortName = "dels", doc = "Include information on deletions", required = false)
     boolean includeDeletions = false;
     @Argument(fullName = "ignoreDeletionSites", doc = "Ignore sites consisting only of deletions", required = false)
     boolean ignoreDeletionSites = false;
+    
+    /**
+     * Path to the RefSeq file for use in aggregating coverage statistics over genes
+     */
     @Argument(fullName = "calculateCoverageOverGenes", shortName = "geneList", doc = "Calculate the coverage statistics over this list of genes. Currently accepts RefSeq.", required = false)
     File refSeqGeneList = null;
+    /**
+     * The format of the output file
+     */
     @Argument(fullName = "outputFormat", doc = "the format of the output file (e.g. csv, table, rtable); defaults to r-readable table", required = false)
     String outputFormat = "rtable";
+    /**
+     * A coverage threshold for summarizing (e.g. % bases >= CT for each sample)
+     */
     @Argument(fullName = "summaryCoverageThreshold", shortName = "ct", doc = "for summary file outputs, report the % of bases coverd to >= this number. Defaults to 15; can take multiple arguments.", required = false)
     int[] coverageThresholds = {15};
 
@@ -966,4 +1003,4 @@ class CoveragePartitioner {
     public Map<DoCOutputType.Partition,List<String>> getIdentifiersByType() {
         return identifiersByType;
     }
-}
\ No newline at end of file
+}
diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/validation/ValidationAmplicons.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/validation/ValidationAmplicons.java
index 178b4c177..01e8cd321 100755
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/validation/ValidationAmplicons.java
+++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/validation/ValidationAmplicons.java
@@ -39,9 +39,6 @@ import java.util.List;
  * reasons why the site may fail validation (nearby variation, for example).
  * </p>
  *
- * <b>If any of the command-line arguments for this tool are not clear to you,
- * please email chartl at broadinstitute dot org and he will gladly explain them in more detail.</b>
- *
  * <h2>Input</h2>
  * <p>
  * Requires a VCF containing alleles to design amplicons towards, a VCF of variants to mask out of the amplicons, and an
@@ -96,20 +93,30 @@ import java.util.List;
  */
 @Requires(value={DataSource.REFERENCE})
 public class ValidationAmplicons extends RodWalker<Integer,Integer> {
+    /**
+     * A Table-formatted file listing amplicon contig, start, stop, and a name for the amplicon (or probe)
+     */
     @Input(fullName = "ProbeIntervals", doc="A collection of intervals in table format with optional names that represent the "+
                                             "intervals surrounding the probe sites amplicons should be designed for", required=true)
     RodBinding<TableFeature> probeIntervals;
-
+    /**
+     * A VCF file containing the bi-allelic sites for validation. Filtered records will prompt a warning, and will be flagged as filtered in the output fastq.
+     */
     @Input(fullName = "ValidateAlleles", doc="A VCF containing the sites and alleles you want to validate. Restricted to *BI-Allelic* sites", required=true)
     RodBinding<VariantContext> validateAlleles;
-
+    /**
+     * A VCF file containing variants to be masked. A mask variant overlapping a validation site will be ignored at the validation site.
+     */
     @Input(fullName = "MaskAlleles", doc="A VCF containing the sites you want to MASK from the designed amplicon (e.g. by Ns or lower-cased bases)", required=true)
     RodBinding<VariantContext> maskAlleles;
 
-
     @Argument(doc="Lower case SNPs rather than replacing with 'N'",fullName="lowerCaseSNPs",required=false)
     boolean lowerCaseSNPs = false;
 
+    /**
+     * BWA single-end alignment is used as a primer specificity proxy. Low-complexity regions (that don't align back to themselves as a best hit) are lowercased.
+     * This changes the size of the k-mer used for alignment.
+     */
     @Argument(doc="Size of the virtual primer to use for lower-casing regions with low specificity",fullName="virtualPrimerSize",required=false)
     int virtualPrimerSize = 20;