Metrics documentation generation. (#7749)

broadinstitute · Mar 21, 2023 · b370c06 · b370c06
1 parent 9afa998
commit b370c06
Show file tree

Hide file tree

Showing 8 changed files with 131 additions and 3 deletions.
diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java b/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java
@@ -1,7 +1,8 @@
 package org.broadinstitute.hellbender.metrics;
 
 import htsjdk.samtools.SamPairUtil.PairOrientation;
-import org.broadinstitute.hellbender.metrics.MultiLevelMetrics;
+import org.broadinstitute.barclay.help.DocumentedFeature;
+import picard.util.help.HelpConstants;
 
 import java.io.Serializable;
 
@@ -11,6 +12,7 @@
  * ".insertSizeMetrics".  In addition the insert size distribution is plotted to
  * a file with the extension ".insertSizeMetrics.pdf".
  */
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public final class InsertSizeMetrics extends MultiLevelMetrics implements Serializable {
 
     private static final long serialVersionUID = 1L;

diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java b/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java
@@ -1,13 +1,16 @@
 package org.broadinstitute.hellbender.metrics;
 
 import htsjdk.samtools.metrics.MetricBase;
+import org.broadinstitute.barclay.help.DocumentedFeature;
 import org.broadinstitute.hellbender.utils.Utils;
 import org.broadinstitute.hellbender.utils.read.GATKRead;
 import org.broadinstitute.hellbender.utils.read.ReadUtils;
+import picard.util.help.HelpConstants;
 
 import java.io.Serializable;
 
 /** A set of metrics used to describe the general quality of a BAM file */
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public final class QualityYieldMetrics extends MetricBase implements Serializable {
     private static final long serialVersionUID = 1;
 

diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java b/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java
@@ -1,7 +1,10 @@
 package org.broadinstitute.hellbender.metrics.analysis;
 
 import htsjdk.samtools.metrics.MetricBase;
+import org.broadinstitute.barclay.help.DocumentedFeature;
+import picard.util.help.HelpConstants;
 
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public class AlleleFrequencyQCMetric extends MetricBase {
 
     public String SAMPLE;

diff --git a/...n/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java b/...n/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java
@@ -1,7 +1,10 @@
 package org.broadinstitute.hellbender.metrics.analysis;
 
 import htsjdk.samtools.metrics.MetricBase;
+import org.broadinstitute.barclay.help.DocumentedFeature;
+import picard.util.help.HelpConstants;
 
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public final class BaseDistributionByCycleMetrics extends MetricBase {
     public int READ_END;
     public int CYCLE;

diff --git a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java
@@ -1,10 +1,13 @@
 package org.broadinstitute.hellbender.tools.spark.pathseq.loggers;
 
 import htsjdk.samtools.metrics.MetricBase;
+import org.broadinstitute.barclay.help.DocumentedFeature;
+import picard.util.help.HelpConstants;
 
 /**
  * Metrics that are calculated during the PathSeq filter
  */
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public final class PSFilterMetrics extends MetricBase {
 
     /**

diff --git a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java
@@ -1,11 +1,14 @@
 package org.broadinstitute.hellbender.tools.spark.pathseq.loggers;
 
 import htsjdk.samtools.metrics.MetricBase;
+import org.broadinstitute.barclay.help.DocumentedFeature;
+import picard.util.help.HelpConstants;
 
 /**
  * Metrics that are calculated during the PathSeq scoring
  */
 @SuppressWarnings("serial")
+@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY)
 public final class PSScoreMetrics extends MetricBase {
 
     /**

diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java
@@ -1,9 +1,20 @@
 package org.broadinstitute.hellbender.utils.help;
 
+import htsjdk.samtools.metrics.MetricBase;
 import org.broadinstitute.barclay.argparser.CommandLineProgramProperties;
 import org.broadinstitute.barclay.help.DefaultDocWorkUnitHandler;
 import org.broadinstitute.barclay.help.DocWorkUnit;
 import org.broadinstitute.barclay.help.HelpDoclet;
+import org.broadinstitute.barclay.help.scanners.JavaLanguageModelScanners;
+
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ElementKind;
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 
 /**
  * The GATK Documentation work unit handler class that is the companion to GATKHelpDoclet.
@@ -17,6 +28,12 @@ public class GATKHelpDocWorkUnitHandler extends DefaultDocWorkUnitHandler {
     private final static String GATK_JAVADOC_TAG_PREFIX = "GATK"; // prefix for custom javadoc tags used by GATK
 
     private final static String GATK_FREEMARKER_TEMPLATE_NAME = "generic.template.html";
+    private final static String PICARD_METRICS_TEMPLATE_NAME = "metrics.template.html";
+
+    private final static String WORK_UNIT_SUMMARY_KEY = "summary";
+    private final static String METRICS_MAP_ENTRY_KEY = "metrics";
+    private final static String METRICS_MAP_NAME_KEY = "name";
+    private final static String METRICS_MAP_SUMMARY_KEY = "summary";
 
     public GATKHelpDocWorkUnitHandler(final HelpDoclet doclet) {
         super(doclet);
@@ -30,12 +47,19 @@ public GATKHelpDocWorkUnitHandler(final HelpDoclet doclet) {
 
     /**
      * @param workUnit the classdoc object being processed
-     * @return the name of a the freemarker template to be used for the class being documented.
+     * @return the name of the freemarker template to be used for the class being documented.
      * Must reside in the folder passed to the Barclay Doclet via the "-settings-dir" parameter to
      * Javadoc.
      */
     @Override
-    public String getTemplateName(final DocWorkUnit workUnit) { return GATK_FREEMARKER_TEMPLATE_NAME; }
+    public String getTemplateName(final DocWorkUnit workUnit) {
+        Class<?> clazz = workUnit.getClazz();
+        if (MetricBase.class.isAssignableFrom(clazz)) {
+            return PICARD_METRICS_TEMPLATE_NAME;
+        } else {
+            return GATK_FREEMARKER_TEMPLATE_NAME;
+        }
+    }
 
 
     /**
@@ -54,6 +78,28 @@ protected void addCustomBindings(final DocWorkUnit currentWorkUnit) {
         if (picard.cmdline.CommandLineProgram.class.isAssignableFrom(toolClass)) {
             final CommandLineProgramProperties clpProperties = currentWorkUnit.getCommandLineProperties();
             currentWorkUnit.setProperty("picardsummary", clpProperties.summary());
+        } else if (MetricBase.class.isAssignableFrom(toolClass)) {
+            currentWorkUnit.setProperty(WORK_UNIT_SUMMARY_KEY, currentWorkUnit.getSummary());
+            final List<Map<String, String>> workUnitMetricsList = new ArrayList<>();
+            currentWorkUnit.setProperty(METRICS_MAP_ENTRY_KEY, workUnitMetricsList);
+            final Field[] fields = currentWorkUnit.getClazz().getFields();
+            for (final Field field : fields) {
+                if (Modifier.isPublic(field.getModifiers())) {
+                    final Element fieldElement = JavaLanguageModelScanners.getElementForField(
+                            getDoclet().getDocletEnv(),
+                            currentWorkUnit.getDocElement(),
+                            field,
+                            ElementKind.FIELD
+                    );
+                    if (fieldElement != null) {
+                        final String docComment = JavaLanguageModelScanners.getDocComment(getDoclet().getDocletEnv(), fieldElement);
+                        final Map<String, String> metricsFields = new HashMap<>();
+                        metricsFields.put(METRICS_MAP_NAME_KEY, field.getName());
+                        metricsFields.put(METRICS_MAP_SUMMARY_KEY, docComment);
+                        workUnitMetricsList.add(metricsFields);
+                    }
+                }
+            }
         }
     }
 

diff --git a/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html b/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html
@@ -0,0 +1,65 @@
+<?php
+
+    include '../../../common/include/common.php';
+    include_once '../../config.php';
+    $module = modules::GATK;
+    printHeader($module, $name, topSN::guide);
+?>
+
+<link type='text/css' rel='stylesheet' href='gatkDoc.css'>
+
+<div class='row-fluid' id="top">
+
+	<#include "common.html"/>
+
+	<?php $group = '${group}'; ?>
+
+	<section class="span4">
+		<aside class="well">
+			<a href="index.html"><h4><i class='fa fa-chevron-left'></i> Back to Tool Docs Index</h4></a>
+		</aside>
+		<?php getForumPosts( '${name}' ) ?>
+
+	</section>
+
+	<div class="span8">
+
+		<h1>${name}</h1>
+
+		<p class="lead">${summary}</p>
+
+		<#if group?? >
+			<h3>Category
+				<small> ${group}</small>
+			</h3>
+		</#if>
+		<hr>
+		<h2>Overview</h2>
+		${description}
+
+			<#-- Create the metrics summary -->
+			<#if metrics?size != 0>
+				<p>This table summarizes the values that are specific to this metric.</p>
+				<table class="table table-striped table-bordered table-condensed">
+					<thead>
+					<tr>
+						<th>Metric</th>
+						<th>Summary</th>
+					</tr>
+					</thead>
+					<#list metrics as metric>
+					<tr>
+						<td>${metric.name}<br />
+						<td>${metric.summary}</td>
+					</tr>
+					</#list>
+					</tbody>
+				</table>
+			</#if>
+
+			<@footerInfo />
+			<@footerClose />
+
+	</div>
+
+	<?php printFooter($module); ?>