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 fe6b1fa18..1711a3923 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java @@ -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> bucket= new HashSet>(); - bucket.addAll(getReadFilters(myClass, bucket)); + // Get parallelism options + final HashSet> parallelOptions = getParallelism(myClass, new HashSet>()); + root.put("parallel", parallelOptions); + // Get annotation info (what type of annotation, standard etc.) + final HashSet annotInfo = getAnnotInfo(myClass, new HashSet()); + 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> bucket= getReadFilters(myClass, new HashSet>()); root.put("readfilters", bucket); - // TODO: get annotators (AnnotatorCompatible) + // Get default downsampling settings + final HashMap dsSettings = getDownSamplingSettings(myClass, new HashMap()); + root.put("downsampling", dsSettings); + // Get reference window size settings + final HashMap refwindow = getRefWindow(myClass, new HashMap()); + root.put("refwindow", refwindow); + // Get ActiveRegion size settings + final HashMap activeRegion = getActiveRegion(myClass, new HashMap()); + root.put("activeregion", activeRegion); // anything else? } else { - root.put("readfilters", new ArrayList>()); // put empty list to avoid blowups + // put empty items to avoid blowups + root.put("parallel", new HashSet()); + root.put("annotinfo", ""); + root.put("walkertype", ""); + root.put("partitiontype", ""); + root.put("readfilters", new HashSet>()); + root.put("downsampling", new HashMap()); + root.put("refwindow", new HashMap()); + root.put("activeregion", new HashMap()); } } + /** + * 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> getParallelism(Class myClass, HashSet> parallelOptions) { + // + // Retrieve interfaces + Class[] implementedInterfaces = myClass.getInterfaces(); + for (Class intfClass : implementedInterfaces) { + final HashMap nugget = new HashMap(); + 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 getAnnotInfo(Class myClass, HashSet 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 getDownSamplingSettings(Class myClass, HashMap 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 getRefWindow(Class myClass, HashMap 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 getActiveRegion(Class myClass, HashMap 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> getReadFilters(Class myClass, HashSet> bucket) { // 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 8edf83252..f99ff7538 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/HelpConstants.java @@ -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, diff --git a/settings/helpTemplates/generic.template.html b/settings/helpTemplates/generic.template.html index 6e3780175..587828d1e 100644 --- a/settings/helpTemplates/generic.template.html +++ b/settings/helpTemplates/generic.template.html @@ -113,80 +113,141 @@ ${group} -
+ <#if walkertype != ""> +

Traversal + ${walkertype} +

+ + <#if walkertype != ""> +

PartitionBy + ${partitiontype} +

+ + <#if annotinfo != "" > +

Annotation type + ${annotinfo} +

+ +

Introduction

${description} + + <#-- Create references to additional capabilities if appropriate --> + <#if readfilters?size != 0 || parallel?size != 0> +
+

Additional Information

+

+ + <#if readfilters?size != 0> +

Read filters

+ <#if readfilters?size = 1> +

This Read Filter is automatically applied to the data by the Engine before processing by ${name}.

+ + <#if (readfilters?size > 1) > +

These Read Filters are automatically applied to the data by the Engine before processing by ${name}.

+ + + + <#if parallel?size != 0> +

Parallelism options

+ <#if parallel?size == 1> +

This tool can be run in multi-threaded mode using this option.

+ + <#if (parallel?size > 1)> +

This tool can be run in multi-threaded mode using these options.

+ + + + <#if downsampling?size != 0> +

Downsampling settings

+

This tool overrides the engine's default downsampling settings.

+
    +
  • Mode: ${downsampling.by}
    • +
  • To coverage: ${downsampling.to_cov}
    • +
+ + <#if refwindow?size != 0> +

Window size

+

This tool uses a sliding window on the reference.

+
    +
  • Window start: ${refwindow.start} bp before the locus
    • +
  • Window stop: ${refwindow.stop} bp after the locus
    • +
+ + <#if activeregion?size != 0> +

ActiveRegion settings

+

This tool uses ActiveRegions on the reference.

+
    +
  • Minimum region size: ${activeregion.min} bp
    • +
  • Maximum region size: ${activeregion.max} bp
    • +
  • Extension increments: ${activeregion.ext} bp
    • +
+ + <#if extradocs?size != 0 || arguments.all?size != 0> +
+

Command-line Arguments

+

+ + <#if extradocs?size != 0> +

Inherited arguments

+

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).

+ + + + <#-- This class is related to other documented classes via sub/super relationships --> + <#if relatedDocs?? && relatedDocs?size != 0> +

Related capabilities

+ <@relatedByType name="Superclasses" type="superclass"/> + <@relatedByType name="Subclasses" type="subclass"/> + + + <#-- 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.

+ + + + + + + + + + + <@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/> + +
NameTypeDefault valueSummary
+ + + <#-- List all of the --> + <#if arguments.all?size != 0> + <#-- Create the argument details --> +

Argument details

+

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.

+ <#list arguments.all as arg> + <@argumentDetails arg=arg/> + + - <#-- Create the argument summary --> - <#if arguments.all?size != 0> -
-

${name} specific arguments

- - - - - - - - - - - <@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/> - -
NameTypeDefault valueSummary
- - - <#-- Create references to additional capabilities if appropriate --> - <#if readfilters?size != 0> -
-

Read Filters

- <#if readfilters?size = 1> -

This Read Filter is automatically applied to the data by the Engine before processing by ${name}.

- - <#if (readfilters?size > 1) > -

These Read Filters are automatically applied to the data by the Engine before processing by ${name}.

- - - - <#if extradocs?size != 0> -
-

Additional capabilities

-

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).

- - - - <#-- This class is related to other documented classes via sub/super relationships --> - <#if relatedDocs?? && relatedDocs?size != 0> -
-

Related capabilities

- <@relatedByType name="Superclasses" type="superclass"/> - <@relatedByType name="Subclasses" type="subclass"/> - - - <#-- List all of the --> - <#if arguments.all?size != 0> -
- <#-- Create the argument details --> -

Argument details

- <#list arguments.all as arg> - <@argumentDetails arg=arg/> - - - - <@footerInfo /> - <@pageFooter /> \ No newline at end of file + <@footerInfo /> + <@pageFooter /> \ No newline at end of file