readGroupBlackList = null;
// --------------------------------------------------------------------------------------------------------------
@@ -433,7 +513,7 @@ public class GATKArgumentCollection {
/**
* How strict should we be in parsing the PED files?
*/
- @Argument(fullName="pedigreeValidationType", shortName = "pedValidationType", doc="How strict should we be in validating the pedigree information?",required=false)
+ @Argument(fullName="pedigreeValidationType", shortName = "pedValidationType", doc="Validation strictness for pedigree information",required=false)
public PedigreeValidationType pedigreeValidationType = PedigreeValidationType.STRICT;
// --------------------------------------------------------------------------------------------------------------
@@ -441,8 +521,10 @@ public class GATKArgumentCollection {
// BAM indexing and sharding arguments
//
// --------------------------------------------------------------------------------------------------------------
-
- @Argument(fullName="allow_intervals_with_unindexed_bam",doc="Allow interval processing with an unsupported BAM. NO INTEGRATION TESTS are available. Use at your own risk.",required=false)
+ /**
+ * NO INTEGRATION TESTS are available. Use at your own risk.
+ */
+ @Argument(fullName="allow_intervals_with_unindexed_bam",doc="Allow interval processing with an unsupported BAM",required=false)
@Hidden
public boolean allowIntervalsWithUnindexedBAM = false;
@@ -451,8 +533,10 @@ public class GATKArgumentCollection {
// testing BCF2
//
// --------------------------------------------------------------------------------------------------------------
-
- @Argument(fullName="generateShadowBCF",shortName = "generateShadowBCF",doc="If provided, whenever we create a VCFWriter we will also write out a BCF file alongside it, for testing purposes",required=false)
+ /**
+ * If provided, whenever we create a VCFWriter we will also write out a BCF file alongside it, for testing purposes.
+ */
+ @Argument(fullName="generateShadowBCF",shortName = "generateShadowBCF",doc="Write a BCF copy of the output VCF",required=false)
@Hidden
public boolean generateShadowBCF = false;
// TODO -- remove all code tagged with TODO -- remove me when argument generateShadowBCF is removed
@@ -471,12 +555,13 @@ public class GATKArgumentCollection {
* DYNAMIC_SEEK attempts to optimize for minimal seek time by choosing an appropriate strategy and parameter (user-supplied parameter is ignored)
* DYNAMIC_SIZE attempts to optimize for minimal index size by choosing an appropriate strategy and parameter (user-supplied parameter is ignored)
*/
-
- @Argument(fullName="variant_index_type",shortName = "variant_index_type",doc="which type of IndexCreator to use for VCF/BCF indices",required=false)
+ @Argument(fullName="variant_index_type",shortName = "variant_index_type",doc="Type of IndexCreator to use for VCF/BCF indices",required=false)
@Advanced
public GATKVCFIndexType variant_index_type = GATKVCFUtils.DEFAULT_INDEX_TYPE;
-
- @Argument(fullName="variant_index_parameter",shortName = "variant_index_parameter",doc="the parameter (bin width or features per bin) to pass to the VCF/BCF IndexCreator",required=false)
+ /**
+ * This is either the bin width or the number of features per bin, depending on the indexing strategy
+ */
+ @Argument(fullName="variant_index_parameter",shortName = "variant_index_parameter",doc="Parameter to pass to the VCF/BCF IndexCreator",required=false)
@Advanced
public int variant_index_parameter = GATKVCFUtils.DEFAULT_INDEX_PARAMETER;
}
diff --git a/public/java/src/org/broadinstitute/sting/gatk/executive/MicroScheduler.java b/public/java/src/org/broadinstitute/sting/gatk/executive/MicroScheduler.java
index 7077db49c..405c07392 100644
--- a/public/java/src/org/broadinstitute/sting/gatk/executive/MicroScheduler.java
+++ b/public/java/src/org/broadinstitute/sting/gatk/executive/MicroScheduler.java
@@ -147,7 +147,7 @@ public abstract class MicroScheduler implements MicroSchedulerMBean {
if ( threadAllocation.getNumDataThreads() > 1 ) {
if (walker.isReduceByInterval())
- throw new UserException.BadArgumentValue("nt", String.format("The analysis %s aggregates results by interval. Due to a current limitation of the GATK, analyses of this type do not currently support parallel execution. Please run your analysis without the -nt option.", engine.getWalkerName(walker.getClass())));
+ throw new UserException.BadArgumentValue("nt", String.format("This run of %s is set up to aggregate results by interval. Due to a current limitation of the GATK, analyses of this type do not currently support parallel execution. Please run your analysis without the -nt option or check if this tool has an option to disable per-interval calculations.", engine.getWalkerName(walker.getClass())));
if ( ! (walker instanceof TreeReducible) ) {
throw badNT("nt", engine, walker);
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 ca3255097..3a51a9a6a 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
@@ -57,10 +57,10 @@ import java.io.PrintStream;
import java.util.*;
/**
- * Toolbox for assessing sequence coverage by a wide array of metrics, partitioned by sample, read group, or library
+ * Assess sequence coverage by a wide array of metrics, partitioned by sample, read group, or library
*
*
- * Coverage processes a set of bam files to determine coverage at different levels of partitioning and
+ * This tool processes a set of bam files to determine coverage at different levels of partitioning and
* aggregation. Coverage can be analyzed per locus, per interval, per gene, or in total; can be partitioned by
* sample, by read group, by technology, by center, or by library; and can be summarized by mean, median, quartiles,
* and/or percentage of bases covered to or beyond a threshold.
@@ -73,7 +73,7 @@ import java.util.*;
*
*(Optional) A REFSEQ Rod to aggregate coverage to the gene level
*
- * (for information about creating the REFSEQ Rod, please consult the RefSeqCodec documentation)
+ * (for information about creating the REFSEQ Rod, please consult the online documentation)
*
* Output
*
@@ -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_QC, extraDocs = {CommandLineGATK.class} )
+@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_QC, extraDocs = {CommandLineGATK.class}, gotoDev = HelpConstants.MC)
@By(DataSource.REFERENCE)
@PartitionBy(PartitionType.NONE)
@Downsample(by= DownsampleType.NONE, toCoverage=Integer.MAX_VALUE)
@@ -125,53 +125,63 @@ public class DepthOfCoverage extends LocusWalker out;
-
- @Argument(fullName = "minMappingQuality", shortName = "mmq", doc = "Minimum mapping quality of reads to count towards depth. Defaults to -1.", required = false)
+ /**
+ * Reads with mapping quality values lower than this threshold will be skipped. This is set to -1 by default to disable the evaluation and ignore this threshold.
+ */
+ @Argument(fullName = "minMappingQuality", shortName = "mmq", doc = "Minimum mapping quality of reads to count towards depth", required = false, minValue = 0, maxValue = Integer.MAX_VALUE)
int minMappingQuality = -1;
- @Argument(fullName = "maxMappingQuality", doc = "Maximum mapping quality of reads to count towards depth. Defaults to 2^31-1 (Integer.MAX_VALUE).", required = false)
+ /**
+ * Reads with mapping quality values higher than this threshold will be skipped. The default value is the largest number that can be represented as an integer by the program.
+ */
+ @Argument(fullName = "maxMappingQuality", doc = "Maximum mapping quality of reads to count towards depth", required = false, minValue = 0, maxValue = Integer.MAX_VALUE)
int maxMappingQuality = Integer.MAX_VALUE;
-
- @Argument(fullName = "minBaseQuality", shortName = "mbq", doc = "Minimum quality of bases to count towards depth. Defaults to -1.", required = false)
+ /**
+ * Bases with quality scores lower than this threshold will be skipped. This is set to -1 by default to disable the evaluation and ignore this threshold.
+ */
+ @Argument(fullName = "minBaseQuality", shortName = "mbq", doc = "Minimum quality of bases to count towards depth", required = false, minValue = 0, maxValue = Byte.MAX_VALUE)
byte minBaseQuality = -1;
- @Argument(fullName = "maxBaseQuality", doc = "Maximum quality of bases to count towards depth. Defaults to 127 (Byte.MAX_VALUE).", required = false)
+ /**
+ * Bases with quality scores higher than this threshold will be skipped. The default value is the largest number that can be represented as a byte.
+ */
+ @Argument(fullName = "maxBaseQuality", doc = "Maximum quality of bases to count towards depth", required = false, minValue = 0, maxValue = Byte.MAX_VALUE)
byte maxBaseQuality = Byte.MAX_VALUE;
@Argument(fullName = "countType", doc = "How should overlapping reads from the same fragment be handled?", required = false)
CoverageUtils.CountPileupType countType = CoverageUtils.CountPileupType.COUNT_READS;
/**
- * Instead of reporting depth, report the base pileup at each locus
+ * Instead of reporting depth, the program will report the base pileup at each locus
*/
- @Argument(fullName = "printBaseCounts", shortName = "baseCounts", doc = "Will add base counts to per-locus output.", required = false)
+ @Argument(fullName = "printBaseCounts", shortName = "baseCounts", doc = "Add base counts to per-locus output", required = false)
boolean printBaseCounts = false;
/**
- * Do not tabulate locus statistics (# loci covered by sample by coverage)
+ * Disabling the tabulation of locus statistics (# loci covered by sample by coverage) should speed up processing.
*/
- @Argument(fullName = "omitLocusTable", shortName = "omitLocusTable", doc = "Will not calculate the per-sample per-depth counts of loci, which should result in speedup", required = false)
+ @Argument(fullName = "omitLocusTable", shortName = "omitLocusTable", doc = "Do not calculate per-sample per-depth counts of loci", required = false)
boolean omitLocusTable = false;
/**
- * Do not tabulate interval statistics (mean, median, quartiles AND # intervals by sample by coverage)
+ * Disabling the tabulation of interval statistics (mean, median, quartiles AND # intervals by sample by coverage) should speed up processing. This option is required in order to use -nt parallelism.
*/
- @Argument(fullName = "omitIntervalStatistics", shortName = "omitIntervals", doc = "Will omit the per-interval statistics section, which should result in speedup", required = false)
+ @Argument(fullName = "omitIntervalStatistics", shortName = "omitIntervals", doc = "Do not calculate per-interval statistics", required = false)
boolean omitIntervals = false;
/**
- * Do not print the total coverage at every base
+ * Disabling the tabulation of total coverage at every base should speed up processing.
*/
- @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)
+ @Argument(fullName = "omitDepthOutputAtEachBase", shortName = "omitBaseOutput", doc = "Do not output depth of coverage at each base", required = false)
boolean omitDepthOutput = false;
/**
- * Path to the RefSeq file for use in aggregating coverage statistics over genes
+ * Specify a 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)
+ @Argument(fullName = "calculateCoverageOverGenes", shortName = "geneList", doc = "Calculate coverage statistics over this list of genes", required = false)
File refSeqGeneList = null;
/**
- * The format of the output file
+ * Output file format (e.g. csv, table, rtable); defaults to r-readable table.
*/
- @Argument(fullName = "outputFormat", doc = "the format of the output file (e.g. csv, table, rtable); defaults to r-readable table", required = false)
+ @Argument(fullName = "outputFormat", doc = "The format of the output file", required = false)
String outputFormat = "rtable";
@@ -180,42 +190,47 @@ public class DepthOfCoverage extends LocusWalker END are counted in the last bin.
+ * Sets the high-coverage cutoff for granular binning. All loci with depth > STOP are counted in the last bin.
*/
@Advanced
- @Argument(fullName = "stop", doc = "Ending (right endpoint) for granular binning", required = false)
+ @Argument(fullName = "stop", doc = "Ending (right endpoint) for granular binning", required = false, minValue = 1)
int stop = 500;
/**
* Sets the number of bins for granular binning
*/
@Advanced
- @Argument(fullName = "nBins", doc = "Number of bins to use for granular binning", required = false)
+ @Argument(fullName = "nBins", doc = "Number of bins to use for granular binning", required = false, minValue = 0, minRecommendedValue = 1)
int nBins = 499;
/**
- * Do not tabulate the sample summary statistics (total, mean, median, quartile coverage per sample)
+ * This option simply disables writing separate files for per-sample summary statistics (total, mean, median, quartile coverage per sample). These statistics are still calculated internally, so enabling this option will not improve runtime.
*/
- @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)
+ @Argument(fullName = "omitPerSampleStats", shortName = "omitSampleSummary", doc = "Do not output the summary files per-sample", required = false)
boolean omitSampleSummary = false;
/**
- * A way of partitioning reads into groups. Can be sample, readgroup, or library.
+ * By default, coverage is partitioning by sample, but it can be any combination of sample, readgroup and/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)
+ @Argument(fullName = "partitionType", shortName = "pt", doc = "Partition type for depth of coverage", required = false)
Set partitionTypes = EnumSet.of(DoCOutputType.Partition.sample);
/**
@@ -230,10 +245,10 @@ public class DepthOfCoverage extends LocusWalker= CT for each sample)
+ * For summary file outputs, report the percentage of bases covered to an amount equal to or greater than this number (e.g. % bases >= CT for each sample). Defaults to 15; can take multiple arguments.
*/
@Advanced
- @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)
+ @Argument(fullName = "summaryCoverageThreshold", shortName = "ct", doc = "Coverage threshold (in percent) for summarizing statistics", required = false)
int[] coverageThresholds = {15};
String[] OUTPUT_FORMATS = {"table","rtable","csv"};
@@ -425,7 +440,7 @@ public class DepthOfCoverage extends LocusWalker implements TreeReducible, NanoSchedulable {
@Input(fullName="exception", shortName = "E", doc="Java class of exception to throw", required=true)
public String exceptionToThrow;
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 724578a09..8c8961cb5 100755
--- a/public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java
+++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/variantutils/GenotypeConcordance.java
@@ -51,23 +51,50 @@ import java.util.*;
*
*
* 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
+ * and for each sample, the genotype-by-genotype counts (e.g. 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
*
* 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. Typically, the EVAL callset is an experimental set you want to evaluate, while the
+ * COMP callset is a previously existing set used as a standard for comparison (taken to represent "truth").
+ *
+ *
* (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 file (via -o) , consisting of multiple tables of counts
- * and proportions. These tables may be optionally moltenized via the -moltenize argument. That is, the standard table
+ *
+ * Genotype Concordance writes a GATK report to the specified file (via -o), consisting of multiple tables of counts
+ * and proportions. These tables are constructed on a per-sample basis, and include counts of EVAL vs COMP genotype states, and the
+ * number of times the alternate alleles between the EVAL and COMP sample did not match up.
+ *
+ *
+ * Term and metrics definitions
+ *
+ *
+ * - HET: heterozygous
+ * - HOM_REF: homozygous reference
+ * - HOM_VAR: homozygous variant
+ * - MIXED: something like ./1
+ * - ALLELES_MATCH: counts of calls at the same site where the alleles match
+ * - ALLELES_DO_NOT_MATCH: counts of calls at the same location with different alleles, such as the eval set calling a 'G' alternate allele, and the comp set calling a 'T' alternate allele
+ * - EVAL_ONLY: counts of sites present only in the EVAL set, not in the COMP set
+ * - TRUTH_ONLY: counts of sites present only in the COMP set, not in the EVAL set
+ * - Non-Reference_Discrepancy (NRD): genotype concordance excluding concordant reference sites
+ * - Non-Reference_Sensitivity (NRS): sensitivity of the EVAL calls to polymorphic calls in the COMP set, calculated by (# true positive)/(# true polymorphic)
+ * - Overall_Genotype_Concordance: overall concordance calculated by (# concordant genotypes)/(# genotypes)
+ *
+ *
+ *
+ * Moltenized tables
+ *
+ * These tables may be optionally moltenized via the -moltenize argument. That is, the standard table
*
*
* Sample NO_CALL_HOM_REF NO_CALL_HET NO_CALL_HOM_VAR (...)
@@ -87,30 +114,32 @@ import java.util.*;
* (...)
*
*
+ * Site-level allelic concordance
*
- * These tables are constructed on a per-sample basis, and include counts of eval vs comp genotype states, and the
- * number of times the alternate alleles between the eval and comp sample did not match up.
- *
- * In addition, Genotype Concordance produces site-level allelic concordance. For strictly bi-allelic VCFs,
- * only the ALLELES_MATCH, EVAL_ONLY, TRUTH_ONLY fields will be populated, but where multi-allelic sites are involved
- * counts for EVAL_SUBSET_TRUTH and EVAL_SUPERSET_TRUTH will be generated.
- *
+ *
+ * For strictly bi-allelic VCFs, only the ALLELES_MATCH, EVAL_ONLY, TRUTH_ONLY fields will be populated,
+ * but where multi-allelic sites are involved counts for EVAL_SUBSET_TRUTH and EVAL_SUPERSET_TRUTH will be generated.
+ *
+ *
* For example, in the following situation
*
* eval: ref - A alt - C
* comp: ref - A alt - C,T
*
* then the site is tabulated as EVAL_SUBSET_TRUTH. Were the situation reversed, it would be EVAL_SUPERSET_TRUTH.
- * However, in the case where eval has both C and T alternate alleles, both must be observed in the genotypes
+ * However, in the case where EVAL has both C and T alternate alleles, both must be observed in the genotypes
* (that is, there must be at least one of (0/1,1/1) and at least one of (0/2,1/2,2/2) in the genotype field). If
- * one of the alleles has no observations in the genotype fields of the eval, the site-level concordance is
+ * one of the alleles has no observations in the genotype fields of the EVAL, the site-level concordance is
* tabulated as though that allele were not present in the record.
+ *
*
- * Monomorphic Records
+ * Monomorphic Records
+ *
* A site which has an alternate allele, but which is monomorphic in samples, is treated as not having been
- * discovered, and will be recorded in the TRUTH_ONLY column (if a record exists in the comp VCF), or not at all
- * (if no record exists in the comp VCF).
- *
+ * discovered, and will be recorded in the TRUTH_ONLY column (if a record exists in the COMP set), or not at all
+ * (if no record exists in the COMP set).
+ *
+ *
* That is, in the situation
*
* eval: ref - A alt - C genotypes - 0/0 0/0 0/0 ... 0/0
@@ -121,14 +150,18 @@ import java.util.*;
* eval: ref - A alt - . genotypes - 0/0 0/0 0/0 ... 0/0
* comp: ref - A alt - C ... 0/0 0/0 ...
*
- *
- * When a record is present in the comp VCF the *genotypes* for the monomorphic site will still be used to evaluate
+ *
+ *
+ * When a record is present in the COMP set the *genotypes* for the monomorphic site will still be used to evaluate
* per-sample genotype concordance counts.
+ *
*
- * Filtered Records
+ * Filtered Records
* Filtered records are treated as though they were not present in the VCF, unless -ignoreSiteFilters is provided,
* in which case all records are used. There is currently no way to assess concordance metrics on filtered sites
* exclusively. SelectVariants can be used to extract filtered sites, and VariantFiltration used to un-filter them.
+ *
+
*/
@DocumentedGATKFeature( groupName = HelpConstants.DOCS_CAT_VARMANIP, extraDocs = {CommandLineGATK.class} )
public class GenotypeConcordance extends RodWalker>,ConcordanceMetrics> {
diff --git a/public/java/src/org/broadinstitute/sting/utils/exceptions/DynamicClassResolutionException.java b/public/java/src/org/broadinstitute/sting/utils/exceptions/DynamicClassResolutionException.java
index 4d280423e..0f1b473c3 100644
--- a/public/java/src/org/broadinstitute/sting/utils/exceptions/DynamicClassResolutionException.java
+++ b/public/java/src/org/broadinstitute/sting/utils/exceptions/DynamicClassResolutionException.java
@@ -29,10 +29,6 @@ import java.lang.reflect.InvocationTargetException;
/**
* Class for handling common failures of dynamic class resolution
- *
- * User: depristo
- * Date: Sep 3, 2010
- * Time: 2:24:09 PM
*/
public class DynamicClassResolutionException extends UserException {
public DynamicClassResolutionException(Class c, Exception ex) {
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 40a730029..4db6e3d69 100644
--- a/public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java
+++ b/public/java/src/org/broadinstitute/sting/utils/exceptions/UserException.java
@@ -42,10 +42,6 @@ import java.io.File;
* Represents the common user errors detected by Sting / GATK
*
* Root class for all GATK user errors, as well as the container for errors themselves
- *
- * User: depristo
- * Date: Sep 3, 2010
- * Time: 2:24:09 PM
*/
@DocumentedGATKFeature(
groupName = HelpConstants.DOCS_CAT_USRERR,
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
index 0390e32d7..0afcdae02 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
@@ -37,7 +37,7 @@ import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface DocumentedGATKFeature {
- /** Should we actually document this feature, even through it's annotated? */
+ /** Should we actually document this feature, even though it's annotated? */
public boolean enable() default true;
/** The overall group name (walkers, readfilters) this feature is associated with */
public String groupName();
@@ -45,4 +45,6 @@ public @interface DocumentedGATKFeature {
public String summary() default "";
/** Are there links to other docs that we should include? CommandLineGATK.class for walkers, for example? */
public Class[] extraDocs() default {};
+ /** Who is the go-to developer for operation/documentation issues? */
+ public String gotoDev() default "NA";
}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
index 7d6819f39..ad0959bfe 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
@@ -36,19 +36,20 @@ class DocumentedGATKFeatureObject {
private final Class classToDoc;
/** Are we enabled? */
private final boolean enable;
- private final String groupName, summary;
+ private final String groupName, summary, gotoDev;
private final Class[] extraDocs;
- public DocumentedGATKFeatureObject(Class classToDoc, final boolean enable, final String groupName, final String summary, final Class[] extraDocs) {
+ public DocumentedGATKFeatureObject(Class classToDoc, final boolean enable, final String groupName, final String summary, final Class[] extraDocs, final String gotoDev) {
this.classToDoc = classToDoc;
this.enable = enable;
this.groupName = groupName;
this.summary = summary;
this.extraDocs = extraDocs;
+ this.gotoDev = gotoDev;
}
- public DocumentedGATKFeatureObject(Class classToDoc, final String groupName, final String summary) {
- this(classToDoc, true, groupName, summary, new Class[]{});
+ public DocumentedGATKFeatureObject(Class classToDoc, final String groupName, final String summary, final String gotoDev) {
+ this(classToDoc, true, groupName, summary, new Class[]{}, gotoDev);
}
public Class getClassToDoc() { return classToDoc; }
@@ -56,4 +57,5 @@ class DocumentedGATKFeatureObject {
public String groupName() { return groupName; }
public String summary() { return summary; }
public Class[] extraDocs() { return extraDocs; }
+ public String gotoDev() { return gotoDev; }
}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
index 63cb0900a..6468fe51d 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
@@ -118,7 +118,8 @@ public class GATKDoclet {
static {
STATIC_DOCS.add(new DocumentedGATKFeatureObject(FeatureCodec.class,
HelpConstants.DOCS_CAT_RODCODECS,
- "Tribble codecs for reading reference ordered data (ROD) files such as VCF or BED"));
+ "Tribble codecs for reading reference ordered data (ROD) files such as VCF or BED",
+ "NA"));
}
@@ -332,11 +333,11 @@ public class GATKDoclet {
if (docClass.isAnnotationPresent(DocumentedGATKFeature.class)) {
DocumentedGATKFeature f = docClass.getAnnotation(DocumentedGATKFeature.class);
- return new DocumentedGATKFeatureObject(docClass, f.enable(), f.groupName(), f.summary(), f.extraDocs());
+ return new DocumentedGATKFeatureObject(docClass, f.enable(), f.groupName(), f.summary(), f.extraDocs(), f.gotoDev());
} else {
for (DocumentedGATKFeatureObject staticDocs : STATIC_DOCS) {
if (staticDocs.getClassToDoc().isAssignableFrom(docClass)) {
- return new DocumentedGATKFeatureObject(docClass, staticDocs.enable(), staticDocs.groupName(), staticDocs.summary(), staticDocs.extraDocs());
+ return new DocumentedGATKFeatureObject(docClass, staticDocs.enable(), staticDocs.groupName(), staticDocs.summary(), staticDocs.extraDocs(), staticDocs.gotoDev());
}
}
return null;
@@ -446,6 +447,7 @@ public class GATKDoclet {
if (annotation.groupName().endsWith(" Tools")) supercatValue = "tools";
else if (annotation.groupName().endsWith(" Utilities")) supercatValue = "utilities";
else if (annotation.groupName().startsWith("Engine ")) supercatValue = "engine";
+ else if (annotation.groupName().endsWith(" (DevZone)")) supercatValue = "dev";
else supercatValue = "other";
root.put("supercat", supercatValue);
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
index 893a8349b..06c0e1c26 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
@@ -123,6 +123,8 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
for (Tag tag : toProcess.classDoc.tags()) {
root.put(tag.name(), tag.text());
}
+
+ root.put("gotoDev", toProcess.annotation.gotoDev());
}
/**
@@ -160,17 +162,29 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
try {
// loop over all of the arguments according to the parsing engine
for (final ArgumentSource argumentSource : parsingEngine.extractArgumentSources(DocletUtils.getClassForDoc(toProcess.classDoc))) {
- // todo -- why can you have multiple ones?
ArgumentDefinition argDef = argumentSource.createArgumentDefinitions().get(0);
FieldDoc fieldDoc = getFieldDoc(toProcess.classDoc, argumentSource.field.getName());
Map argBindings = docForArgument(fieldDoc, argumentSource, argDef);
if (!argumentSource.isHidden() || getDoclet().showHiddenFeatures()) {
final String kind = docKindOfArg(argumentSource);
-
+ // Retrieve default value
final Object value = argumentValue(toProcess.clazz, argumentSource);
if (value != null)
argBindings.put("defaultValue", prettyPrintValueString(value));
-
+ // Retrieve min and max / hard and soft value thresholds for numeric args
+ if (value instanceof Number) {
+ if (argumentSource.field.isAnnotationPresent(Argument.class)) {
+ argBindings.put("minValue", argumentSource.field.getAnnotation(Argument.class).minValue());
+ argBindings.put("maxValue", argumentSource.field.getAnnotation(Argument.class).maxValue());
+ if (argumentSource.field.getAnnotation(Argument.class).minRecommendedValue() != Double.NEGATIVE_INFINITY) {
+ argBindings.put("minRecValue", argumentSource.field.getAnnotation(Argument.class).minRecommendedValue());
+ }
+ if (argumentSource.field.getAnnotation(Argument.class).maxRecommendedValue() != Double.POSITIVE_INFINITY) {
+ argBindings.put("maxRecValue", argumentSource.field.getAnnotation(Argument.class).maxRecommendedValue());
+ }
+ }
+ }
+ // Finalize argument bindings
args.get(kind).add(argBindings);
args.get("all").add(argBindings);
}
@@ -742,8 +756,14 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
/**
* Returns a Pair of (main, synonym) names for argument with fullName s1 and
- * shortName s2. The main is selected to be the longest of the two, provided
- * it doesn't exceed MAX_DISPLAY_NAME, in which case the shorter is taken.
+ * shortName s2.
+ *
+ * Previously we had it so the main name was selected to be the longest of the two, provided
+ * it didn't exceed MAX_DISPLAY_NAME, in which case the shorter was taken. But we now disable
+ * the length-based name rearrangement in order to maintain consistency in the GATKDocs table.
+ *
+ * This may cause messed up spacing in the CLI-help display but we don't care as much about that
+ * since more users use the online GATKDocs for looking up arguments.
*
* @param s1 the short argument name without -, or null if not provided
* @param s2 the long argument name without --, or null if not provided
@@ -758,13 +778,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
if (s1 == null) return new Pair(s2, null);
if (s2 == null) return new Pair(s1, null);
- String l = s1.length() > s2.length() ? s1 : s2;
- String s = s1.length() > s2.length() ? s2 : s1;
-
- if (l.length() > MAX_DISPLAY_NAME)
- return new Pair(s, l);
- else
- return new Pair(l, s);
+ return new Pair(s2, s1);
}
/**
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 2ed35d848..783e7aa90 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java
@@ -50,15 +50,34 @@ public class HelpConstants {
public final static String DOCS_CAT_RF = "Read Filters";
public final static String DOCS_CAT_REFUTILS = "Reference Utilities";
public final static String DOCS_CAT_RODCODECS = "ROD Codecs";
- public final static String DOCS_CAT_USRERR = "User Exceptions";
+ public final static String DOCS_CAT_USRERR = "User Exceptions (DevZone)";
public final static String DOCS_CAT_VALIDATION = "Validation Utilities";
public final static String DOCS_CAT_ANNOT = "Variant Annotations";
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_TOY = "Toy Walkers (DevZone)";
public final static String DOCS_CAT_HELPUTILS = "Help Utilities";
public static String forumPost(String post) {
return GATK_FORUM_URL + post;
}
+
+ /**
+ * Go-to developer name codes for tracking and display purposes. Only current team members should be in this list.
+ * When someone leaves, their charges should be redistributed. The actual string should be closest to the dev's
+ * abbreviated name or two/three-letter nickname as possible. The code can be something else if necessary to
+ * disambiguate from other variable.
+ */
+ public final static String MC = "MC"; // Mauricio Carneiro
+ public final static String EB = "EB"; // Eric Banks
+ public final static String RP = "RP"; // Ryan Poplin
+ public final static String GVDA = "GG"; // Geraldine Van der Auwera
+ public final static String VRR = "VRR"; // Valentin Ruano-Rubio
+ public final static String ALM = "ALM"; // Ami Levy-Moonshine
+ public final static String BH = "BH"; // Bertrand Haas
+ public final static String JoT = "JT"; // Joel Thibault
+ public final static String DR = "DR"; // David Roazen
+ public final static String KS = "KS"; // Khalid Shakir
+
+
}
\ No newline at end of file
diff --git a/settings/helpTemplates/common.html b/settings/helpTemplates/common.html
index f4fb74af1..ff9df5eea 100644
--- a/settings/helpTemplates/common.html
+++ b/settings/helpTemplates/common.html
@@ -86,7 +86,13 @@
Support Forum
- GATK version ${version} built at ${timestamp}.
+ GATK version ${version} built at ${timestamp}.
+ <#-- closing P tag in next macro -->
+
+
+ <#macro footerClose>
+ <#-- ugly little hack to enable adding tool-specific info inline -->
+
<#macro pageFooter>
diff --git a/settings/helpTemplates/generic.index.template.html b/settings/helpTemplates/generic.index.template.html
index a5650d55e..0398b829d 100644
--- a/settings/helpTemplates/generic.index.template.html
+++ b/settings/helpTemplates/generic.index.template.html
@@ -58,7 +58,7 @@
${version}
- <#assign seq = ["engine", "tools", "utilities", "other"]>
+ <#assign seq = ["engine", "tools", "utilities", "other", "dev"]>
<#list seq as supercat>
<#list groups?sort_by("name") as group>
@@ -70,4 +70,5 @@
<@footerInfo />
+<@footerClose />
<@pageFooter />
diff --git a/settings/helpTemplates/generic.template.html b/settings/helpTemplates/generic.template.html
index eea741669..d4aa7c7f9 100644
--- a/settings/helpTemplates/generic.template.html
+++ b/settings/helpTemplates/generic.template.html
@@ -31,45 +31,70 @@
<#list myargs as arg>
- | ${arg.name} |
- ${arg.type} |
+ ${arg.name}
+ <#if arg.synonyms??>
+ <#if arg.name[2..] != arg.synonyms[1..]>
+ ${arg.synonyms}
+
+
+ |
+
${arg.defaultValue!"NA"} |
${arg.summary} |
- <#--
- <
- td>${arg.required}
- -->
<#macro argumentDetails arg>
- ${arg.name}
- <#if arg.synonyms??> / ${arg.synonyms}
-
- (
- <#if arg.attributes??>${arg.attributes}
- ${arg.type}
- <#if arg.defaultValue??> with default value ${arg.defaultValue}
- )
-
-
- ${arg.summary}. ${arg.fulltext}
- <#if arg.rodTypes??>${arg.name} binds reference ordered data. This argument supports ROD files of the
- following types: ${arg.rodTypes}
-
- <#if arg.options??>
-
- The ${arg.name} argument is an enumerated type (${arg.type}), which can have one of the following values:
-
- <#list arg.options as option>
- - ${option.name}
- - ${option.summary}
-
-
-
-
+
+ ${arg.name}
+ <#if arg.synonyms??> / ${arg.synonyms}
+
+
+ ${arg.summary}
+ ${arg.fulltext}
+
+
+
+ <#if arg.rodTypes??>
+ ${arg.name} binds reference ordered data. This argument supports ROD files of the following types: ${arg.rodTypes}
+
+ <#if arg.options??>
+
+ The ${arg.name} argument is an enumerated type (${arg.type}), which can have one of the following values:
+
+ <#list arg.options as option>
+ - ${option.name}
+ - ${option.summary}
+
+
+
+
+ <#if arg.required??>
+ <#if arg.required == "yes">
+ R
+
+
+ ${arg.type}
+ <#if arg.defaultValue??>
+ ${arg.defaultValue}
+
+ <#if arg.minValue??>
+ [ [ ${arg.minValue}
+
+ <#if arg.minRecValue??>
+ [ ${arg.minRecValue}
+
+ <#if arg.maxRecValue??>
+ ${arg.maxRecValue} ]
+
+ <#if arg.maxValue??>
+ ${arg.maxValue} ] ]
+
+
<#macro relatedByType name type>
<#list relatedDocs as relatedDoc>
@@ -103,11 +128,12 @@
${name}
${summary}
+ <#-- using goto dev annotation instead, see above footer
<#if author??>
Author
${author}
-
+ -->
<#if group?? >
Category
${group}
@@ -229,12 +255,12 @@
<#-- Create the argument summary -->
<#if arguments.all?size != 0>
${name} specific arguments
-
This table summarizes the command-line arguments that are specific to this tool. For details, see the list further down below the table.
+ This table summarizes the command-line arguments that are specific to this tool. For more details on each argument, see the list further down below the table or click on an argument name to jump directly to that entry in the list.
- | Name |
- Type |
+ Argument name(s) |
+
Default value |
Summary |
@@ -267,6 +293,11 @@
<@argumentDetails arg=arg/>
-
+
<@footerInfo />
+ <#-- Specify go-to developer (for internal use) -->
+ <#if gotoDev??>
+ GTD: ${gotoDev}
+
+ <@footerClose />
<@pageFooter />
\ No newline at end of file