Merge pull request #52 from broadinstitute/gg_more_gatkdocs_improvements_GSATDG-66-67
This commit is contained in:
MauricioCarneiro
commit
a954cf3c01
|
|
@ -30,12 +30,13 @@ import com.google.java.contract.Requires;
|
|||
import com.sun.javadoc.ClassDoc;
|
||||
import com.sun.javadoc.FieldDoc;
|
||||
import com.sun.javadoc.Tag;
|
||||
import org.apache.commons.lang.StringUtils;
|
||||
import org.apache.log4j.Logger;
|
||||
import org.broad.tribble.Feature;
|
||||
import org.broadinstitute.sting.commandline.*;
|
||||
import org.broadinstitute.sting.gatk.CommandLineGATK;
|
||||
import org.broadinstitute.sting.gatk.refdata.tracks.FeatureManager;
|
||||
import org.broadinstitute.sting.gatk.walkers.ReadFilters;
|
||||
import org.broadinstitute.sting.gatk.walkers.*;
|
||||
import org.broadinstitute.sting.utils.Utils;
|
||||
import org.broadinstitute.sting.utils.classloader.JVMUtils;
|
||||
import org.broadinstitute.sting.utils.collections.Pair;
|
||||
|
|
@ -288,26 +289,207 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
|
|||
final Object instance = makeInstanceIfPossible(classToProcess);
|
||||
if (instance != null) {
|
||||
final Class myClass = instance.getClass();
|
||||
// TODO: get top relevant superclass (last before object? abstract?)
|
||||
// TODO: get parallelism options (TreeReducible or Nanoschedulable)
|
||||
// Get read filter annotations (ReadFilters)
|
||||
final HashSet<HashMap<String, Object>> bucket= new HashSet<HashMap<String, Object>>();
|
||||
bucket.addAll(getReadFilters(myClass, bucket));
|
||||
// Get parallelism options
|
||||
final HashSet<HashMap<String, Object>> parallelOptions = getParallelism(myClass, new HashSet<HashMap<String, Object>>());
|
||||
root.put("parallel", parallelOptions);
|
||||
// Get annotation info (what type of annotation, standard etc.)
|
||||
final HashSet<String> annotInfo = getAnnotInfo(myClass, new HashSet<String>());
|
||||
root.put("annotinfo", StringUtils.join(annotInfo, ", "));
|
||||
// Get walker type if applicable
|
||||
root.put("walkertype", getWalkerType(myClass));
|
||||
// Get partition type if applicable
|
||||
root.put("partitiontype", getPartitionType(myClass));
|
||||
// Get read filter annotations (ReadFilters) if applicable
|
||||
final HashSet<HashMap<String, Object>> bucket= getReadFilters(myClass, new HashSet<HashMap<String, Object>>());
|
||||
root.put("readfilters", bucket);
|
||||
// TODO: get annotators (AnnotatorCompatible)
|
||||
// Get default downsampling settings
|
||||
final HashMap<String, Object> dsSettings = getDownSamplingSettings(myClass, new HashMap<String, Object>());
|
||||
root.put("downsampling", dsSettings);
|
||||
// Get reference window size settings
|
||||
final HashMap<String, Object> refwindow = getRefWindow(myClass, new HashMap<String, Object>());
|
||||
root.put("refwindow", refwindow);
|
||||
// Get ActiveRegion size settings
|
||||
final HashMap<String, Object> activeRegion = getActiveRegion(myClass, new HashMap<String, Object>());
|
||||
root.put("activeregion", activeRegion);
|
||||
// anything else?
|
||||
} else {
|
||||
root.put("readfilters", new ArrayList<HashMap<String, Object>>()); // put empty list to avoid blowups
|
||||
// put empty items to avoid blowups
|
||||
root.put("parallel", new HashSet<String>());
|
||||
root.put("annotinfo", "");
|
||||
root.put("walkertype", "");
|
||||
root.put("partitiontype", "");
|
||||
root.put("readfilters", new HashSet<HashMap<String, Object>>());
|
||||
root.put("downsampling", new HashMap<String, Object>());
|
||||
root.put("refwindow", new HashMap<String, Object>());
|
||||
root.put("activeregion", new HashMap<String, Object>());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that checks which parallelism options are available for an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the interfaces
|
||||
* @param parallelOptions an empty HashSet in which to collect the info
|
||||
* @return a hash set of parallelism options, otherwise an empty set
|
||||
*/
|
||||
private HashSet<HashMap<String, Object>> getParallelism(Class myClass, HashSet<HashMap<String, Object>> parallelOptions) {
|
||||
//
|
||||
// Retrieve interfaces
|
||||
Class[] implementedInterfaces = myClass.getInterfaces();
|
||||
for (Class intfClass : implementedInterfaces) {
|
||||
final HashMap<String, Object> nugget = new HashMap<String, Object>();
|
||||
if (intfClass.getSimpleName().equals("TreeReducible")) {
|
||||
nugget.put("name", intfClass.getSimpleName());
|
||||
nugget.put("arg", HelpConstants.ARG_TREEREDUCIBLE);
|
||||
nugget.put("link", HelpConstants.CMDLINE_GATK_URL + "#" + HelpConstants.ARG_TREEREDUCIBLE);
|
||||
} else if (intfClass.getSimpleName().equals("NanoSchedulable")) {
|
||||
nugget.put("name", intfClass.getSimpleName());
|
||||
nugget.put("arg", HelpConstants.ARG_NANOSCHEDULABLE);
|
||||
nugget.put("link", HelpConstants.CMDLINE_GATK_URL + "#" + HelpConstants.ARG_NANOSCHEDULABLE);
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
parallelOptions.add(nugget);
|
||||
}
|
||||
// Look up superclasses recursively
|
||||
final Class mySuperClass = myClass.getSuperclass();
|
||||
if (mySuperClass.getSimpleName().equals("Object")) {
|
||||
return parallelOptions;
|
||||
}
|
||||
return getParallelism(mySuperClass, parallelOptions);
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the annotation type for an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the interfaces
|
||||
* @param annotInfo an empty HashSet in which to collect the info
|
||||
* @return a hash set of the annotation types, otherwise an empty set
|
||||
*/
|
||||
private HashSet<String> getAnnotInfo(Class myClass, HashSet<String> annotInfo) {
|
||||
//
|
||||
// Retrieve interfaces
|
||||
Class[] implementedInterfaces = myClass.getInterfaces();
|
||||
for (Class intfClass : implementedInterfaces) {
|
||||
if (intfClass.getName().contains("Annotation")) {
|
||||
annotInfo.add(intfClass.getSimpleName());
|
||||
}
|
||||
}
|
||||
// Look up superclasses recursively
|
||||
final Class mySuperClass = myClass.getSuperclass();
|
||||
if (mySuperClass.getSimpleName().equals("Object")) {
|
||||
return annotInfo;
|
||||
}
|
||||
return getAnnotInfo(mySuperClass, annotInfo);
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the default downsampling settings for an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the settings
|
||||
* @param dsSettings an empty HashMap in which to collect the info
|
||||
* @return a hash set of the downsampling settings, otherwise an empty set
|
||||
*/
|
||||
private HashMap<String, Object> getDownSamplingSettings(Class myClass, HashMap<String, Object> dsSettings) {
|
||||
//
|
||||
// Retrieve annotation
|
||||
if (myClass.isAnnotationPresent(Downsample.class)) {
|
||||
final Annotation thisAnnotation = myClass.getAnnotation(Downsample.class);
|
||||
if(thisAnnotation instanceof Downsample) {
|
||||
final Downsample dsAnnotation = (Downsample) thisAnnotation;
|
||||
dsSettings.put("by", dsAnnotation.by().toString());
|
||||
dsSettings.put("to_cov", dsAnnotation.toCoverage());
|
||||
}
|
||||
}
|
||||
return dsSettings;
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the reference window size for an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the settings
|
||||
* @param refWindow an empty HashMap in which to collect the info
|
||||
* @return a HashMap of the window start and stop, otherwise an empty HashMap
|
||||
*/
|
||||
private HashMap<String, Object> getRefWindow(Class myClass, HashMap<String, Object> refWindow) {
|
||||
//
|
||||
// Retrieve annotation
|
||||
if (myClass.isAnnotationPresent(Reference.class)) {
|
||||
final Annotation thisAnnotation = myClass.getAnnotation(Reference.class);
|
||||
if(thisAnnotation instanceof Reference) {
|
||||
final Reference refAnnotation = (Reference) thisAnnotation;
|
||||
refWindow.put("start", refAnnotation.window().start());
|
||||
refWindow.put("stop", refAnnotation.window().stop());
|
||||
}
|
||||
}
|
||||
return refWindow;
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the ActiveRegion settings for an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the settings
|
||||
* @param activeRegion an empty HashMap in which to collect the info
|
||||
* @return a HashMap of the ActiveRegion parameters, otherwise an empty HashMap
|
||||
*/
|
||||
private HashMap<String, Object> getActiveRegion(Class myClass, HashMap<String, Object> activeRegion) {
|
||||
//
|
||||
// Retrieve annotation
|
||||
if (myClass.isAnnotationPresent(ActiveRegionTraversalParameters.class)) {
|
||||
final Annotation thisAnnotation = myClass.getAnnotation(ActiveRegionTraversalParameters.class);
|
||||
if(thisAnnotation instanceof ActiveRegionTraversalParameters) {
|
||||
final ActiveRegionTraversalParameters arAnnotation = (ActiveRegionTraversalParameters) thisAnnotation;
|
||||
activeRegion.put("ext", arAnnotation.extension());
|
||||
activeRegion.put("max", arAnnotation.maxRegion());
|
||||
activeRegion.put("min", arAnnotation.minRegion());
|
||||
}
|
||||
}
|
||||
return activeRegion;
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the partition type of an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the annotation
|
||||
* @return the partition type if applicable, otherwise an empty string
|
||||
*/
|
||||
private String getPartitionType(Class myClass) {
|
||||
//
|
||||
// Retrieve annotation
|
||||
if (myClass.isAnnotationPresent(PartitionBy.class)) {
|
||||
final Annotation thisAnnotation = myClass.getAnnotation(PartitionBy.class);
|
||||
if(thisAnnotation instanceof PartitionBy) {
|
||||
final PartitionBy partAnnotation = (PartitionBy) thisAnnotation;
|
||||
return partAnnotation.value().toString();
|
||||
}
|
||||
}
|
||||
return "";
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that determines the type of walker subclassed by an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the annotation
|
||||
* @return the type of walker if applicable, otherwise an empty string
|
||||
*/
|
||||
private String getWalkerType(Class myClass) {
|
||||
//
|
||||
// Look up superclasses recursively until we find either Walker or Object
|
||||
final Class mySuperClass = myClass.getSuperclass();
|
||||
if (mySuperClass.getSimpleName().equals("Walker")) {
|
||||
return myClass.getSimpleName();
|
||||
} else if (mySuperClass.getSimpleName().equals("Object")) {
|
||||
return "";
|
||||
}
|
||||
return getWalkerType(mySuperClass);
|
||||
}
|
||||
|
||||
/**
|
||||
* Utility function that finds the values of ReadFilters annotation applied to an instance of class c.
|
||||
*
|
||||
* @param myClass the class to query for the annotation
|
||||
* @param bucket a container in which we store the annotations collected
|
||||
* @return a list of values, otherwise null
|
||||
* @return a hash set of values, otherwise an empty set
|
||||
*/
|
||||
private HashSet<HashMap<String, Object>> getReadFilters(Class myClass, HashSet<HashMap<String, Object>> bucket) {
|
||||
//
|
||||
|
|
|
|||
|
|
@ -32,6 +32,13 @@ public class HelpConstants {
|
|||
public final static String GATK_FORUM_URL = "http://gatkforums.broadinstitute.org/";
|
||||
public final static String GATK_FORUM_API_URL = "https://gatkforums.broadinstitute.org/api/v1/";
|
||||
|
||||
/**
|
||||
* Arguments for parallelism options
|
||||
*/
|
||||
public final static String ARG_TREEREDUCIBLE = "-nt";
|
||||
public final static String ARG_NANOSCHEDULABLE = "-nct";
|
||||
public final static String CMDLINE_GATK_URL = GATK_DOCS_URL + "org_broadinstitute_sting_gatk_CommandLineGATK.html";
|
||||
|
||||
/**
|
||||
* Definition of the group names / categories of tools.
|
||||
* The names get parsed to make supercategories in the doc index,
|
||||
|
|
|
|||
|
|
@ -113,80 +113,141 @@
|
|||
<small> ${group}</small>
|
||||
</h3>
|
||||
</#if>
|
||||
<br/>
|
||||
<#if walkertype != "">
|
||||
<h3>Traversal
|
||||
<small>${walkertype}</small>
|
||||
</h3>
|
||||
</#if>
|
||||
<#if walkertype != "">
|
||||
<h3>PartitionBy
|
||||
<small>${partitiontype}</small>
|
||||
</h3>
|
||||
</#if>
|
||||
<#if annotinfo != "" >
|
||||
<h3>Annotation type
|
||||
<small>${annotinfo}</small>
|
||||
</h3>
|
||||
</#if>
|
||||
|
||||
<hr>
|
||||
<h2>Introduction</h2>
|
||||
${description}
|
||||
|
||||
<#-- Create references to additional capabilities if appropriate -->
|
||||
<#if readfilters?size != 0 || parallel?size != 0>
|
||||
<hr>
|
||||
<h2>Additional Information</h2>
|
||||
<p></p>
|
||||
</#if>
|
||||
<#if readfilters?size != 0>
|
||||
<h3>Read filters</h3>
|
||||
<#if readfilters?size = 1>
|
||||
<p>This Read Filter is automatically applied to the data by the Engine before processing by ${name}.</p>
|
||||
</#if>
|
||||
<#if (readfilters?size > 1) >
|
||||
<p>These Read Filters are automatically applied to the data by the Engine before processing by ${name}.</p>
|
||||
</#if>
|
||||
<ul>
|
||||
<#list readfilters as filter>
|
||||
<li><a href="${filter.filename}">${filter.name}</a></li>
|
||||
</#list>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if parallel?size != 0>
|
||||
<h3>Parallelism options</h3>
|
||||
<#if parallel?size == 1>
|
||||
<p>This tool can be run in multi-threaded mode using this option.</p>
|
||||
</#if>
|
||||
<#if (parallel?size > 1)>
|
||||
<p>This tool can be run in multi-threaded mode using these options.</p>
|
||||
</#if>
|
||||
<ul>
|
||||
<#list parallel as option>
|
||||
<li><a href="${option.link}">${option.name} (${option.arg})</a></li>
|
||||
</#list>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if downsampling?size != 0>
|
||||
<h3>Downsampling settings</h3>
|
||||
<p>This tool overrides the engine's default downsampling settings.</p>
|
||||
<ul>
|
||||
<li>Mode: <b>${downsampling.by}</b></li>
|
||||
<li>To coverage: <b>${downsampling.to_cov}</b></li>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if refwindow?size != 0>
|
||||
<h3>Window size</h3>
|
||||
<p>This tool uses a sliding window on the reference.</p>
|
||||
<ul>
|
||||
<li>Window start: <b>${refwindow.start}</b> bp before the locus</li>
|
||||
<li>Window stop: <b>${refwindow.stop}</b> bp after the locus</li>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if activeregion?size != 0>
|
||||
<h3>ActiveRegion settings</h3>
|
||||
<p>This tool uses ActiveRegions on the reference.</p>
|
||||
<ul>
|
||||
<li>Minimum region size: <b>${activeregion.min}</b> bp</li>
|
||||
<li>Maximum region size: <b>${activeregion.max}</b> bp</li>
|
||||
<li>Extension increments: <b>${activeregion.ext}</b> bp</li>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if extradocs?size != 0 || arguments.all?size != 0>
|
||||
<hr>
|
||||
<h2>Command-line Arguments</h2>
|
||||
<p></p>
|
||||
</#if>
|
||||
<#if extradocs?size != 0>
|
||||
<h3>Inherited arguments</h3>
|
||||
<p>The arguments described in the entries below can be supplied to this tool to modify
|
||||
its behavior. For example, the -L argument directs the GATK engine restricts processing
|
||||
to specific genomic intervals (this is an Engine capability and is therefore available to all GATK walkers).</p>
|
||||
<ul>
|
||||
<#list extradocs as extradoc>
|
||||
<li><a href="${extradoc.filename}">${extradoc.name}</a></li>
|
||||
</#list>
|
||||
</ul>
|
||||
</#if>
|
||||
|
||||
<#-- This class is related to other documented classes via sub/super relationships -->
|
||||
<#if relatedDocs?? && relatedDocs?size != 0>
|
||||
<h3>Related capabilities</h3>
|
||||
<@relatedByType name="Superclasses" type="superclass"/>
|
||||
<@relatedByType name="Subclasses" type="subclass"/>
|
||||
</#if>
|
||||
|
||||
<#-- Create the argument summary -->
|
||||
<#if arguments.all?size != 0>
|
||||
<h3>${name} specific arguments</h3>
|
||||
<p>This table summarizes the command-line arguments that are specific to this tool. For details, see the list further down below the table.</p>
|
||||
<table class="table table-striped table-bordered table-condensed">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Type</th>
|
||||
<th>Default value</th>
|
||||
<th>Summary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<@argumentlist name="Required" myargs=arguments.required/>
|
||||
<@argumentlist name="Optional" myargs=arguments.optional/>
|
||||
<@argumentlist name="Advanced" myargs=arguments.advanced/>
|
||||
<@argumentlist name="Hidden" myargs=arguments.hidden/>
|
||||
<@argumentlist name="Depreciated" myargs=arguments.depreciated/>
|
||||
</tbody>
|
||||
</table>
|
||||
</#if>
|
||||
|
||||
<#-- List all of the -->
|
||||
<#if arguments.all?size != 0>
|
||||
<#-- Create the argument details -->
|
||||
<h3>Argument details</h3>
|
||||
<p>Arguments in this list are specific to this tool. Keep in mind that other arguments are available that are shared with other tools (e.g. command-line GATK arguments); see Inherited arguments above.</p>
|
||||
<#list arguments.all as arg>
|
||||
<@argumentDetails arg=arg/>
|
||||
</#list>
|
||||
</#if>
|
||||
|
||||
<#-- Create the argument summary -->
|
||||
<#if arguments.all?size != 0>
|
||||
<hr>
|
||||
<h3>${name} specific arguments</h3>
|
||||
<table class="table table-striped table-bordered table-condensed">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Type</th>
|
||||
<th>Default value</th>
|
||||
<th>Summary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<@argumentlist name="Required" myargs=arguments.required/>
|
||||
<@argumentlist name="Optional" myargs=arguments.optional/>
|
||||
<@argumentlist name="Advanced" myargs=arguments.advanced/>
|
||||
<@argumentlist name="Hidden" myargs=arguments.hidden/>
|
||||
<@argumentlist name="Depreciated" myargs=arguments.depreciated/>
|
||||
</tbody>
|
||||
</table>
|
||||
</#if>
|
||||
|
||||
<#-- Create references to additional capabilities if appropriate -->
|
||||
<#if readfilters?size != 0>
|
||||
<hr>
|
||||
<h3>Read Filters</h3>
|
||||
<#if readfilters?size = 1>
|
||||
<p>This Read Filter is automatically applied to the data by the Engine before processing by ${name}.</p>
|
||||
</#if>
|
||||
<#if (readfilters?size > 1) >
|
||||
<p>These Read Filters are automatically applied to the data by the Engine before processing by ${name}.</p>
|
||||
</#if>
|
||||
<ul>
|
||||
<#list readfilters as filter>
|
||||
<li><a href="${filter.filename}">${filter.name}</a></li>
|
||||
</#list>
|
||||
</ul>
|
||||
</#if>
|
||||
<#if extradocs?size != 0>
|
||||
<hr>
|
||||
<h2>Additional capabilities</h2>
|
||||
<p>The arguments described in the entries below can be supplied to this tool to modify
|
||||
its behavior. For example, the -L argument directs the GATK engine restricts processing
|
||||
to specific genomic intervals (this is an Engine capability and is therefore available to all GATK walkers).</p>
|
||||
<ul>
|
||||
<#list extradocs as extradoc>
|
||||
<li><a href="${extradoc.filename}">${extradoc.name}</a></li>
|
||||
</#list>
|
||||
</ul>
|
||||
</#if>
|
||||
|
||||
<#-- This class is related to other documented classes via sub/super relationships -->
|
||||
<#if relatedDocs?? && relatedDocs?size != 0>
|
||||
<hr>
|
||||
<h2>Related capabilities</h2>
|
||||
<@relatedByType name="Superclasses" type="superclass"/>
|
||||
<@relatedByType name="Subclasses" type="subclass"/>
|
||||
</#if>
|
||||
|
||||
<#-- List all of the -->
|
||||
<#if arguments.all?size != 0>
|
||||
<hr>
|
||||
<#-- Create the argument details -->
|
||||
<h2>Argument details</h2>
|
||||
<#list arguments.all as arg>
|
||||
<@argumentDetails arg=arg/>
|
||||
</#list>
|
||||
</#if>
|
||||
|
||||
<@footerInfo />
|
||||
<@pageFooter />
|
||||
<@footerInfo />
|
||||
<@pageFooter />
|
||||
Loading…
Reference in New Issue