zzh
/
gatk-3.8
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Cleanup of the doc system, and introduce Kiran's concept of a detailed summary 

below the specific command-line arguments for the walker.  Also introduced
@help.summary to override summary descriptions if required.


git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@2337 348d0f76-0448-11de-a6fe-93d51630548a
This commit is contained in:
hanna 2009-12-12 04:04:37 +00:00
parent cdfe204d19
commit 6955b5bf53
11 changed files with 261 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java
View File

@ -117,22 +117,40 @@ public class CommandLineGATK extends CommandLineExecutable {
String additionalHelp = "";
// If no analysis name is present, fill in extra help on the walkers.
WalkerManager walkerManager = GATKEngine.getWalkerManager();
String analysisName = getAnalysisName();
if(analysisName == null || !GATKEngine.getWalkerManager().exists(getAnalysisName()))
additionalHelp = getWalkerHelp();
if(analysisName != null && walkerManager.exists(getAnalysisName()))
additionalHelp = getWalkerHelp(walkerManager.getWalkerClassByName(getAnalysisName()));
else
additionalHelp = getAllWalkerHelp();
return additionalHelp;
}
private static final int PACKAGE_INDENT = 1;
private static final int WALKER_INDENT = 3;
private static final String FIELD_SEPARATOR = " ";
private String getWalkerHelp(Class<Walker> walkerType) {
// Construct a help string to output details on this walker.
StringBuilder additionalHelp = new StringBuilder();
Formatter formatter = new Formatter(additionalHelp);
formatter.format("Description:%n");
WalkerManager walkerManager = GATKEngine.getWalkerManager();
String walkerHelpText = walkerManager.getWalkerDescriptionText(walkerType);
printDescriptorLine(formatter,WALKER_INDENT,"",WALKER_INDENT,FIELD_SEPARATOR,walkerHelpText,TextFormattingUtils.DEFAULT_LINE_WIDTH);
return additionalHelp.toString();
}
/**
* Load in additional help information about all available walkers.
* @return A string representation of the additional help.
*/
private String getWalkerHelp() {
final int PACKAGE_INDENT = 1;
final int WALKER_INDENT = 3;
final String FIELD_SEPARATOR = " ";
private String getAllWalkerHelp() {
// Construct a help string to output available walkers.
StringBuilder additionalHelp = new StringBuilder();
Formatter formatter = new Formatter(additionalHelp);
@ -152,7 +170,7 @@ public class CommandLineGATK extends CommandLineExecutable {
// Get the display name.
String packageName = walkersByPackage.getKey();
String packageDisplayName = walkerManager.getPackageDisplayName(walkersByPackage.getKey());
String packageHelpText = walkerManager.getPackageHelpText(packageName);
String packageHelpText = walkerManager.getPackageSummaryText(packageName);
// Compute statistics about which names is longest.
longestPackageName = Math.max(longestPackageName,packageDisplayName.length());
@ -161,7 +179,7 @@ public class CommandLineGATK extends CommandLineExecutable {
for(Class<? extends Walker> walkerType: walkersByPackage.getValue()) {
String walkerName = walkerType.getName();
String walkerDisplayName = walkerManager.getName(walkerType);
String walkerHelpText = walkerManager.getWalkerHelpText(walkerType);
String walkerHelpText = walkerManager.getWalkerSummaryText(walkerType);
longestWalkerName = Math.max(longestWalkerName,walkerManager.getName(walkerType).length());
@ -176,10 +194,10 @@ public class CommandLineGATK extends CommandLineExecutable {
for(HelpEntry packageHelp: helpText) {
printDescriptorLine(formatter,PACKAGE_INDENT,packageHelp.displayName,headerWidth,FIELD_SEPARATOR,packageHelp.description,TextFormattingUtils.DEFAULT_LINE_WIDTH);
printDescriptorLine(formatter,PACKAGE_INDENT,packageHelp.displayName,headerWidth,FIELD_SEPARATOR,packageHelp.summary,TextFormattingUtils.DEFAULT_LINE_WIDTH);
for(HelpEntry walkerHelp: packageHelp.children)
printDescriptorLine(formatter,WALKER_INDENT,walkerHelp.displayName,headerWidth,FIELD_SEPARATOR,walkerHelp.description,TextFormattingUtils.DEFAULT_LINE_WIDTH);
printDescriptorLine(formatter,WALKER_INDENT,walkerHelp.displayName,headerWidth,FIELD_SEPARATOR,walkerHelp.summary,TextFormattingUtils.DEFAULT_LINE_WIDTH);
// Print a blank line between sets of walkers.
printDescriptorLine(formatter,0,"",headerWidth,FIELD_SEPARATOR,"", TextFormattingUtils.DEFAULT_LINE_WIDTH);
@ -213,36 +231,36 @@ public class CommandLineGATK extends CommandLineExecutable {
}
/**
* Represents a given help entry; contains a display name, a description and optionally some children.
* Represents a given help entry; contains a display name, a summary and optionally some children.
*/
class HelpEntry {
public final String uid;
public final String displayName;
public final String description;
public final String summary;
public final SortedSet<HelpEntry> children;
/**
* Create a new help entry with the given display name, description and children.
* Create a new help entry with the given display name, summary and children.
* @param uid a unique identifier. Usually, the java package.
* @param displayName display name for this help entry.
* @param description description for this help entry.
* @param summary summary for this help entry.
* @param children children for this help entry.
*/
public HelpEntry(String uid, String displayName, String description, SortedSet<HelpEntry> children) {
public HelpEntry(String uid, String displayName, String summary, SortedSet<HelpEntry> children) {
this.uid = uid;
this.displayName = displayName;
this.description = description;
this.summary = summary;
this.children = children;
}
/**
* Create a new help entry with the given display name, description and children.
* Create a new help entry with the given display name, summary and children.
* @param uid a unique identifier. Usually, the java package.
* @param displayName display name for this help entry.
* @param description description for this help entry.
* @param summary summary for this help entry.
*/
public HelpEntry(String uid, String displayName, String description) {
this(uid,displayName,description,null);
public HelpEntry(String uid, String displayName, String summary) {
this(uid,displayName,summary,null);
}
}

48
java/src/org/broadinstitute/sting/gatk/WalkerManager.java
View File

@ -36,6 +36,8 @@ import org.broadinstitute.sting.gatk.filters.FilterManager;
import org.broadinstitute.sting.utils.StingException;
import org.broadinstitute.sting.utils.PluginManager;
import org.broadinstitute.sting.utils.help.DisplayNameTaglet;
import org.broadinstitute.sting.utils.help.DescriptionTaglet;
import org.broadinstitute.sting.utils.help.SummaryTaglet;
import org.apache.log4j.Logger;
import net.sf.picard.filter.SamRecordFilter;
@ -95,14 +97,17 @@ public class WalkerManager extends PluginManager<Walker> {
*/
public String getPackageDisplayName(String packageName) {
// Try to find an override for the display name of this package.
String displayName = helpText.getProperty(packageName+"."+ DisplayNameTaglet.NAME);
// If no override exists...
if(displayName == null) {
String displayNameKey = String.format("%s.%s",packageName,DisplayNameTaglet.NAME);
String displayName = null;
if(helpText.containsKey(displayNameKey)) {
displayName = helpText.getProperty(displayNameKey);
}
else {
// If no override exists...
// ...try to compute the override from the text of the package name, while accounting for
// unpackaged walkers.
displayName = packageName.substring(packageName.lastIndexOf('.')+1);
if(displayName.trim().equals("")) displayName = "<unpackaged>";
}
return displayName;
}
@ -112,22 +117,35 @@ public class WalkerManager extends PluginManager<Walker> {
* @param packageName Package for which to search for help text.
* @return Package help text, or "" if none exists.
*/
public String getPackageHelpText(String packageName) {
if(!helpText.containsKey(packageName))
public String getPackageSummaryText(String packageName) {
String key = String.format("%s.%s",packageName,SummaryTaglet.NAME);
if(!helpText.containsKey(key))
return "";
return helpText.getProperty(packageName);
return helpText.getProperty(key);
}
/**
* Gets the help text associated with a given walker type.
* Gets the summary help text associated with a given walker type.
* @param walkerType Type of walker for which to search for help text.
* @return Package help text, or "" if none exists.
* @return Walker summary description, or "" if none exists.
*/
public String getWalkerHelpText(Class<? extends Walker> walkerType) {
String walkerName = walkerType.getName();
if(!helpText.containsKey(walkerName))
public String getWalkerSummaryText(Class<? extends Walker> walkerType) {
String walkerSummary = String.format("%s.%s",walkerType.getName(), SummaryTaglet.NAME);
if(!helpText.containsKey(walkerSummary))
return "";
return helpText.getProperty(walkerName);
return helpText.getProperty(walkerSummary);
}
/**
* Gets the descriptive help text associated with a given walker type.
* @param walkerType Type of walker for which to search for help text.
* @return Walker full description, or "" if none exists.
*/
public String getWalkerDescriptionText(Class<? extends Walker> walkerType) {
String walkerDescription = String.format("%s.%s",walkerType.getName(), DescriptionTaglet.NAME);
if(!helpText.containsKey(walkerDescription))
return "";
return helpText.getProperty(walkerDescription);
}
/**
@ -135,8 +153,8 @@ public class WalkerManager extends PluginManager<Walker> {
* @param walkerName Name of the walker.
* @return Class representing the walker.
*/
public Class getWalkerClassByName(String walkerName) {
return pluginsByName.get(walkerName);
public Class<Walker> getWalkerClassByName(String walkerName) {
return (Class<Walker>)pluginsByName.get(walkerName);
}
/**

12
java/src/org/broadinstitute/sting/gatk/walkers/PileupWalker.java
View File

@ -36,9 +36,7 @@ import org.broadinstitute.sting.utils.Utils;
import java.util.ArrayList;
/**
* samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list] [-iscg] [-T theta] [-N nHap] [-r pairDiffRate] <in.alignment>
*
* Print the alignment in the pileup format. In the pileup format, each line represents a genomic position,
* Prints the alignment in the pileup format. In the pileup format, each line represents a genomic position,
* consisting of chromosome name, coordinate, reference base, read bases, read qualities and alignment mapping
* qualities. Information on match, mismatch, indel, strand, mapping quality and start and end of a read are all
* encoded at the read base column. At this column, a dot stands for a match to the reference base on the forward strand,
@ -52,12 +50,8 @@ import java.util.ArrayList;
* separated by 'N/S/H' CIGAR operations. The ASCII of the character following '^' minus 33 gives the mapping quality.
* A symbol '$' marks the end of a read segment.
*
* @help.description Prints the alignment in the pileup format. In the pileup format, each line represents a genomic position,
* consisting of chromosome name, coordinate, reference base, read bases, read qualities and alignment mapping
* qualities. Information on match, mismatch, indel, strand, mapping quality and start and end of a read are all
* encoded at the read base column. At this column, a dot stands for a match to the reference base on the forward strand,
* a comma for a match on the reverse strand, 'ACGTN' for a mismatch on the forward strand and 'acgtn' for a mismatch on the
* reverse strand.
* Associated command:
* samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list] [-iscg] [-T theta] [-N nHap] [-r pairDiffRate] <in.alignment>
*/
public class PileupWalker extends LocusWalker<Integer, Integer> implements TreeReducible<Integer> {
@Argument(fullName="alwaysShowSecondBase",doc="If true, prints dummy bases for the second bases in the BAM file where they are missing",required=false)

8
java/src/org/broadinstitute/sting/gatk/walkers/recalibration/CovariateCounterWalker.java
View File

@ -46,10 +46,6 @@ import net.sf.samtools.SAMRecord;
*/
/**
* Created by IntelliJ IDEA.
* User: rpoplin
* Date: Nov 3, 2009
*
* This walker is designed to work as the first pass in a two-pass processing step.
* It does a by-locus traversal operating only at sites that are not in dbSNP.
* We assume that all reference mismatches we see are therefore errors and indicitive of poor base quality.
@ -62,7 +58,9 @@ import net.sf.samtools.SAMRecord;
* Note: ReadGroupCovariate and QualityScoreCovariate are required covariates and must be at the start of the list.
* Note: This walker is designed to be used in conjunction with TableRecalibrationWalker.
*
* @help.description First pass of the recalibration. Generates recalibration table based on various user-specified covariates (such as reported quality score, cycle, and dinucleotide).
* @author rpoplin
* @since Nov 3, 2009
* @help.summary First pass of the recalibration. Generates recalibration table based on various user-specified covariates (such as reported quality score, cycle, and dinucleotide).
*/
@By( DataSource.READS ) // Only look at covered loci, not every loci of the reference file

8
java/src/org/broadinstitute/sting/gatk/walkers/recalibration/TableRecalibrationWalker.java
View File

@ -43,10 +43,6 @@ import java.io.FileNotFoundException;
*/
/**
* Created by IntelliJ IDEA.
* User: rpoplin
* Date: Nov 3, 2009
*
* This walker is designed to work as the second pass in a two-pass processing step, doing a by-read traversal.
* For each base in each read this walker calculates various user-specified covariates (such as read group, reported quality score, cycle, and dinuc)
@ -56,7 +52,9 @@ import java.io.FileNotFoundException;
* Note: This walker expects as input the recalibration table file generated previously by CovariateCounterWalker.
* Note: This walker is designed to be used in conjunction with CovariateCounterWalker.
*
* @help.description Second pass of the recalibration. Uses the table generated by CountCovariates to update the base quality scores of the input bam file using a sequential table calculation making the base quality scores more accurately reflect the actual quality of the bases as mesaured by reference mismatch rate.
* @author rpoplin
* @since Nov 3, 2009
* @help.summary Second pass of the recalibration. Uses the table generated by CountCovariates to update the base quality scores of the input bam file using a sequential table calculation making the base quality scores more accurately reflect the actual quality of the bases as mesaured by reference mismatch rate.
*/
@WalkerName("TableRecalibration")

7
java/src/org/broadinstitute/sting/playground/gatk/walkers/papergenotyper/GATKPaperGenotyper.java
View File

@ -14,11 +14,10 @@ import java.io.PrintStream;
/**
* @author aaron
* A simple Bayesian genotyper, that output a text based call format. Intended to be used only as an
* A simple Bayesian genotyper, that outputs a text based call format. Intended to be used only as an
* example in the GATK publication.
*
* @help.description A simple, naive Bayesian genotyper that is used as an example locus walker in the GATK paper. THIS IS NOT TO BE USED FOR ANY ANALYSIS
* @author aaron
* @help.summary A simple, naive Bayesian genotyper that is used as an example locus walker in the GATK paper. THIS IS NOT TO BE USED FOR ANY ANALYSIS
*/
public class GATKPaperGenotyper extends LocusWalker<SimpleCall, Integer> implements TreeReducible<Integer> {

68
java/src/org/broadinstitute/sting/utils/help/DescriptionTaglet.java
View File

@ -11,7 +11,7 @@ import java.util.Map;
* @author mhanna
* @version 0.1
*/
public class DescriptionTaglet implements Taglet {
public class DescriptionTaglet extends HelpTaglet {
/**
* The key tag for this taglet.
*/
@ -20,42 +20,17 @@ public class DescriptionTaglet implements Taglet {
/**
* Return the name of this custom tag.
*/
@Override
public String getName() {
return NAME;
}
/**
* Will return false since this tag cannot be applied
* to a field.
* @return false since this tag cannot be applied to a field.
*/
public boolean inField() {
return false;
}
/**
* Will return false since this tag cannot be applied
* to a constructor.
* @return false since this tag cannot be applied to a constructor.
*/
public boolean inConstructor() {
return false;
}
/**
* Will return false since this tag cannot be applied
* to a method.
* @return false since this tag cannot be applied to a method.
*/
public boolean inMethod() {
return false;
}
/**
* Will return false since overviews are always named
* by the <code>@WalkerName</code> tag.
* @return false always
*/
@Override
public boolean inOverview() {
return true;
}
@ -65,30 +40,11 @@ public class DescriptionTaglet implements Taglet {
* description.
* @return true always
*/
@Override
public boolean inPackage() {
return true;
}
/**
* Will return false indicating that types cannot be given
* alternate description.
* @return false always.
*/
public boolean inType() {
return false;
}
/**
* Will return false since <code>@todo</code>
* is not an inline tag.
* @return false since <code>@todo</code>
* is not an inline tag.
*/
public boolean isInlineTag() {
return false;
}
/**
* Register this Taglet.
* @param tagletMap the map to register this tag to.
@ -101,20 +57,4 @@ public class DescriptionTaglet implements Taglet {
}
tagletMap.put(tag.getName(), tag);
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag tag) {
return null;
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag[] tags) {
return null;
}
}

76
java/src/org/broadinstitute/sting/utils/help/DisplayNameTaglet.java
View File

@ -11,7 +11,7 @@ import java.util.Map;
* @author mhanna
* @version 0.1
*/
public class DisplayNameTaglet implements Taglet {
public class DisplayNameTaglet extends HelpTaglet {
/**
* The display name for this taglet.
*/
@ -20,75 +20,21 @@ public class DisplayNameTaglet implements Taglet {
/**
* Return the name of this custom tag.
*/
@Override
public String getName() {
return NAME;
}
/**
* Will return false since this tag cannot be applied
* to a field.
* @return false since this tag cannot be applied to a field.
*/
public boolean inField() {
return false;
}
/**
* Will return false since this tag cannot be applied
* to a constructor.
* @return false since this tag cannot be applied to a constructor.
*/
public boolean inConstructor() {
return false;
}
/**
* Will return false since this tag cannot be applied
* to a method.
* @return false since this tag cannot be applied to a method.
*/
public boolean inMethod() {
return false;
}
/**
* Will return false since overviews are always named
* by the <code>@WalkerName</code> tag.
* @return false always
*/
public boolean inOverview() {
return false;
}
/**
* Will return true to indicate that packages can be given useful
* display text.
* @return true always
*/
@Override
public boolean inPackage() {
return true;
}
/**
* Will return false indicating that types cannot be given
* alternate display names.
* @return false always.
*/
public boolean inType() {
return false;
}
/**
* Will return false since <code>@todo</code>
* is not an inline tag.
* @return false since <code>@todo</code>
* is not an inline tag.
*/
public boolean isInlineTag() {
return false;
}
/**
* Register this Taglet.
* @param tagletMap the map to register this tag to.
@ -101,20 +47,4 @@ public class DisplayNameTaglet implements Taglet {
}
tagletMap.put(tag.getName(), tag);
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag tag) {
return null;
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag[] tags) {
return null;
}
}

28
java/src/org/broadinstitute/sting/utils/help/HelpExtractorDoclet.java
View File

@ -71,26 +71,34 @@ public class HelpExtractorDoclet {
*/
private static void renderHelpText(String elementName, Doc element, PrintStream out) {
// Extract overrides from the doc tags.
String overrideName = null;
String overrideDescription = element.firstSentenceTags().length > 0 ? element.firstSentenceTags()[0].text() : "";
String name = null;
StringBuilder summaryBuilder = new StringBuilder();
for(Tag tag: element.firstSentenceTags())
summaryBuilder.append(tag.text());
String summary = summaryBuilder.toString();
String description = element.commentText();
for(Tag tag: element.tags()) {
if(tag.name().equals("@"+DisplayNameTaglet.NAME)) {
if(overrideName != null)
if(name != null)
throw new StingException("Only one display name tag can be used per package / walker.");
overrideName = tag.text();
name = tag.text();
}
else if(tag.name().equals("@"+SummaryTaglet.NAME))
summary = tag.text();
else if(tag.name().equals("@"+DescriptionTaglet.NAME))
overrideDescription = tag.text();
description = tag.text();
}
// Write out an alternate element name, if exists.
if(overrideName != null)
out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,overrideName);
if(name != null)
out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,name);
// Write out an alternate element summary, if exists.
out.printf("%s.%s=%s%n",elementName,SummaryTaglet.NAME,formatText(summary));
// Write out an alternate description, if present.
String description = formatText(overrideDescription);
if(description.length() > 0)
out.printf("%s=%s%n",elementName,description);
out.printf("%s.%s=%s%n",elementName,DescriptionTaglet.NAME,formatText(description));
}
/**

93
java/src/org/broadinstitute/sting/utils/help/HelpTaglet.java 100644
View File

@ -0,0 +1,93 @@
package org.broadinstitute.sting.utils.help;
import com.sun.tools.doclets.Taglet;
import com.sun.javadoc.Tag;
import java.util.Map;
/**
* Basic functionality for the help taglet.
*
* @author mhanna
* @version 0.1
*/
public abstract class HelpTaglet implements Taglet {
/**
* Return the name of this custom tag.
*/
public abstract String getName();
/**
* Will return false since this tag cannot be applied
* to a field.
* @return false since this tag cannot be applied to a field.
*/
public boolean inField() {
return false;
}
/**
* Will return false since by default, help tags cannot be applied to a constructor.
* @return false since by default, help tags cannot be applied to a constructor.
*/
public boolean inConstructor() {
return false;
}
/**
* Will return false since by default, help tags cannot be applied to a method.
* @return false since by default, this tag cannot be applied to a method.
*/
public boolean inMethod() {
return false;
}
/**
* Will return false since by default, help tags cannot be applied to an overview.
* @return false since by default, help tags cannot be applied to an overview.
*/
public boolean inOverview() {
return false;
}
/**
* Will return false since by default, help tags cannot be applied to a package.
* description.
* @return false since by default, help tags cannot be applied to a package.
*/
public boolean inPackage() {
return false;
}
/**
* Will return false since help tags are by default not inline.
* @return false since help tags are by default not inline.
*/
public boolean inType() {
return false;
}
/**
* Will return false since help tags are by default not inline.
* @return false since help tags are by default not inline.
*/
public boolean isInlineTag() {
return false;
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag tag) {
return null;
}
/**
* Create a string representation of this tag. Since this tag is only
* used by the help system, don't output any HTML.
*/
public String toString(Tag[] tags) {
return null;
}
}

59
java/src/org/broadinstitute/sting/utils/help/SummaryTaglet.java 100644
View File

@ -0,0 +1,59 @@
package org.broadinstitute.sting.utils.help;
import com.sun.tools.doclets.Taglet;
import com.sun.javadoc.Tag;
import java.util.Map;
/**
* Provide an alternate brief summary for this walker / package.
* Acts as an alternative to the first sentence employed by default.
* @author mhanna
* @version 0.1
*/
public class SummaryTaglet extends HelpTaglet {
/**
* The key tag for this taglet.
*/
public static final String NAME = "help.summary";
/**
* Return the name of this custom tag.
*/
@Override
public String getName() {
return NAME;
}
/**
* Will return false since overviews are always named
* by the <code>@WalkerName</code> tag.
* @return false always
*/
@Override
public boolean inOverview() {
return true;
}
/**
* Will return true to indicate that packages can be given useful summary.
* @return true always
*/
@Override
public boolean inPackage() {
return true;
}
/**
* Register this Taglet.
* @param tagletMap the map to register this tag to.
*/
public static void register(Map tagletMap) {
SummaryTaglet tag = new SummaryTaglet();
Taglet t = (Taglet)tagletMap.get(tag.getName());
if (t != null) {
tagletMap.remove(tag.getName());
}
tagletMap.put(tag.getName(), tag);
}
}