From faef85841b8e309a643d28c6b81f7ab169077c29 Mon Sep 17 00:00:00 2001 From: Geraldine Van der Auwera Date: Wed, 13 Feb 2013 01:14:57 -0500 Subject: [PATCH] Added GATKDocs fct to indicate default Read Filters for each tool -- Added getClazzAnnotations() as hub to retrieve various annotations values and class properties through reflection -- Added getReadFilters() method to retrieve Read Filter annotations -- getReadFilters() uses recursion to walk up the inheritance to also capture superclass annotations -- getClazzAnnotations() stores collected info in doc handler root, which is unit.forTemplate in Doclet -- Modified FreeMarker template to use the Readfilters info (displayed after arg table, before additional capabilities) -- Tadaaa :-) #GSATDG-63 resolve --- .../sting/utils/help/GATKDoclet.java | 4 +- .../help/GenericDocumentationHandler.java | 67 ++++++++++++++++++- settings/helpTemplates/generic.template.html | 20 +++++- 3 files changed, 85 insertions(+), 6 deletions(-) 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 f63a9162b..677bbf2e5 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java @@ -224,7 +224,7 @@ public class GATKDoclet { File forumKeyFile = new File(FORUM_KEY_FILE); if (forumKeyFile.exists()) { String forumKey = null; - // Read ing a one-line file so we can do a for loop + // Read in a one-line file so we can do a for loop for (String line : new XReadLines(forumKeyFile)) forumKey = line; updateForum(myWorkUnits, forumKey); @@ -283,7 +283,7 @@ public class GATKDoclet { DocumentedGATKFeatureObject feature = getFeatureForClassDoc(doc); DocumentedGATKFeatureHandler handler = createHandler(doc, feature); if (handler != null && handler.includeInDocs(doc)) { - logger.info("Generating documentation for class " + doc); + //logger.info("Generating documentation for class " + doc); String filename = handler.getDestinationFilename(doc, clazz); GATKDocWorkUnit unit = new GATKDocWorkUnit(doc.name(), filename, feature.groupName(), feature, handler, doc, clazz, 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 bb0dc670b..fe6b1fa18 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java @@ -35,6 +35,7 @@ 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.utils.Utils; import org.broadinstitute.sting.utils.classloader.JVMUtils; import org.broadinstitute.sting.utils.collections.Pair; @@ -42,6 +43,7 @@ import org.broadinstitute.sting.utils.exceptions.ReviewedStingException; import org.broadinstitute.sting.utils.exceptions.StingException; import java.io.IOException; +import java.lang.annotation.Annotation; import java.lang.reflect.*; import java.util.*; @@ -91,6 +93,9 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { addRelatedBindings(root); root.put("group", toProcess.group); + // Adding in retrieval of peripheral info (rf annotations etc) + getClazzAnnotations(toProcess.clazz, root); + toProcess.setHandlerContent((String) root.get("summary"), root); } @@ -135,7 +140,6 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { put("filename", otherUnit.filename); put("name", otherUnit.name); }}); - } root.put("extradocs", extraDocsData); } @@ -270,6 +274,66 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { } } + /** + * Umbrella function that groups the collection of values for specific annotations applied to an + * instance of class c. Lists of collected values are added directly to the "toProcess" object. + * Requires being able to instantiate the class. + * + * @param classToProcess the object to instantiate and query for the annotation + * @param root the root of the document handler, to which we'll store collected annotations + */ + private void getClazzAnnotations(Class classToProcess, Map root) { + // + // attempt to instantiate the class + 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)); + root.put("readfilters", bucket); + // TODO: get annotators (AnnotatorCompatible) + // anything else? + } else { + root.put("readfilters", new ArrayList>()); // put empty list to avoid blowups + } + } + + + /** + * 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 + */ + private HashSet> getReadFilters(Class myClass, HashSet> bucket) { + // + // Retrieve annotation + if (myClass.isAnnotationPresent(ReadFilters.class)) { + final Annotation thisAnnotation = myClass.getAnnotation(ReadFilters.class); + if(thisAnnotation instanceof ReadFilters) { + final ReadFilters rfAnnotation = (ReadFilters) thisAnnotation; + for (Class filter : rfAnnotation.value()) { + // make hashmap of simplename and url + final HashMap nugget = new HashMap(); + nugget.put("name", filter.getSimpleName()); + nugget.put("filename", GATKDocUtils.htmlFilenameForClass(filter)); + bucket.add(nugget); + } + } + } + // Look up superclasses recursively + final Class mySuperClass = myClass.getSuperclass(); + if (mySuperClass.getSimpleName().equals("Object")) { + return bucket; + } + return getReadFilters(mySuperClass, bucket); + } + + /** * Utility function that finds the value of fieldName in any fields of ArgumentCollection fields in * instance of class c. @@ -287,6 +351,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { // @ArgumentCollection // protected DbsnpArgumentCollection dbsnp = new DbsnpArgumentCollection(); // + for (Field field : JVMUtils.getAllFields(instance.getClass())) { if (field.isAnnotationPresent(ArgumentCollection.class)) { //System.out.printf("Searching for %s in argument collection field %s%n", fieldName, field); diff --git a/settings/helpTemplates/generic.template.html b/settings/helpTemplates/generic.template.html index ce77acb5e..6e3780175 100644 --- a/settings/helpTemplates/generic.template.html +++ b/settings/helpTemplates/generic.template.html @@ -71,7 +71,6 @@

- <#macro relatedByType name type> <#list relatedDocs as relatedDoc> <#if relatedDoc.relation == type> @@ -143,12 +142,27 @@ <#-- 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 +

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 capability is available to all GATK walkers. + to specific genomic intervals (this is an Engine capability and is therefore available to all GATK walkers).