Doc fix for SOR (#5703)

 Update StrandOddsRatio (SOR) and AS_StrandOddsRatio (AS_SOR) tool documents
- Render LaTex equations with plugin (pre-tested)
- Render Markdown table correctly and add spacing between columns
- In 'Statistical notes' section, introduce the contingency table and place appropriately with text
- Provide both R and 1/R equations instead of just one (both are mentioned in the text)
- Close out the equation elements appropriately with `]` and `)`s
- Mention the final annotation is given in log space and provide a link to an example calculation
- Update links, e.g. to related annotations, to point to GATK4 current docs instead of v3.8
- Add example step-by-step SOR calculation using variant record provided by Laura
- Clarify SOR is calculated with `ln(ratio) + ln(refRatio) - ln(altRatio)`
- Mention one is added to each count

Author: ldgauthier

src/main/java/org/broadinstitute/hellbender/tools/walkers/annotator/StrandOddsRatio.java

@@ -20,37 +20,100 @@
 /**
  * Strand bias estimated by the Symmetric Odds Ratio test
  *
- * <p>Strand bias is a type of sequencing bias in which one DNA strand is favored over the other, which can result in incorrect evaluation of the amount of evidence observed for one allele vs. the other. The StrandOddsRatio annotation is one of several methods that aims to evaluate whether there is strand bias in the data. It is an updated form of the Fisher Strand Test that is better at taking into account large amounts of data in high coverage situations. It is used to determine if there is strand bias between forward and reverse strands for the reference or alternate allele.</p>
+ * <p>Strand bias is a type of sequencing bias in which one DNA strand is favored over the other, which can result in
+ * incorrect evaluation of the amount of evidence observed for one allele vs. the other. The StrandOddsRatio annotation
+ * is one of several methods that aims to evaluate whether there is strand bias in the data. It is an updated form of
+ * the <a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_FisherStrand.php">Fisher Strand Test</a>
+ * that is better at taking into account large amounts of data in high coverage situations. It is used to determine if
+ * there is strand bias between forward and reverse strands for the reference or alternate allele(s).</p>
  *
  * <h3>Statistical notes</h3>
- * <p> Odds Ratios in the 2x2 contingency table below are</p>
  *
- * $$ R = \frac{X[0][0] * X[1][1]}{X[0][1] * X[1][0]} $$
- *
- * <p>and its inverse:</p>
+ * <p>The following 2x2 contingency table gives the notation for allele support and strand orientation.</p>
  *
  * <table>
- *      <tr><td>&nbsp;</td><td>+ strand </td><td>- strand</td></tr>
- *      <tr><td>REF;</td><td>X[0][0]</td><td>X[0][1]</td></tr>
- *      <tr><td>ALT;</td><td>X[1][0]</td><td>X[1][1]</td></tr>
+ * <tr><th>&nbsp;</th><th>+ strand&nbsp;&nbsp;&nbsp;</th><th>- strand&nbsp;&nbsp;&nbsp;</th></tr>
+ * <tr><th>REF&nbsp;&nbsp;&nbsp;</th><td>X[0][0]</td><td>X[0][1]</td></tr>
+ * <tr><th>ALT&nbsp;&nbsp;&nbsp;</th><td>X[1][0]</td><td>X[1][1]</td></tr>
  * </table>
  *
- * <p>The sum R + 1/R is used to detect a difference in strand bias for REF and for ALT (the sum makes it symmetric). A high value is indicative of large difference where one entry is very small compared to the others. A scale factor of refRatio/altRatio where</p>
+ * <p>We can then represent the Odds Ratios with the equation:</p>
+ *
+ * <img src="http://latex.codecogs.com/svg.latex?$$ R = \frac{X[0][0] * X[1][1]}{X[0][1] * X[1][0]} $$" border="0"/>
+ *
+ * <p>and its inverse:</p>
+ *
+ * <img src="http://latex.codecogs.com/svg.latex?$$ \frac{1}{R} = \frac{X[0][1] * X[1][0]}{X[0][0] * X[1][1]} $$" border="0"/>
  *
- * $$ refRatio = \frac{max(X[0][0], X[0][1])}{min(X[0][0], X[0][1} $$
+ * <p>The sum R + 1/R is used to detect a difference in strand bias for REF and for ALT. The sum makes it symmetric.
+ * A high value is indicative of large difference where one entry is very small compared to the others. A scale factor
+ * of refRatio/altRatio where</p>
+ *
+ * <img src="http://latex.codecogs.com/svg.latex?$$ refRatio = \frac{min(X[0][0], X[0][1])}{max(X[0][0], X[0][1])} $$" border="0"/>
  *
  * <p>and </p>
  *
- * $$ altRatio = \frac{max(X[1][0], X[1][1])}{min(X[1][0], X[1][1]} $$
+ * <img src="http://latex.codecogs.com/svg.latex?$$ altRatio = \frac{min(X[1][0], X[1][1])}{max(X[1][0], X[1][1])} $$" border="0"/>
+ *
+ * <p>ensures that the annotation value is large only. The final SOR annotation is given in natural log space.</p>
+ *
+ * <p>See the <a href="http://www.broadinstitute.org/gatk/guide/article?id=4732">method document on statistical tests</a>
+ * for a more detailed explanation of this statistical test.</p>
+ *
+ * <h3>Example calculation</h3>
+ *
+ * <p>Here is a variant record where SOR is 0.592.</p>
+ *
+ * <pre>
+ *     AC=78;AF=2.92135e-02;AN=2670;DP=31492;FS=48.628;MQ=58.02;MQRankSum=-2.02400e+00;MQ_DP=3209;QD=3.03; \
+ *     ReadPosRankSum=-1.66500e-01;SB_TABLE=1450,345,160,212;SOR=0.592;VarDP=2167
+ * </pre>
+ *
+ * <p>Read support shows some strand bias for the reference allele but not
+ * the alternate allele. The SB_TABLE annotation (a non-GATK annotation) indicates 1450 reference alleles on the forward strand, 345
+ * reference alleles on the reverse strand, 160 alternate alleles on the forward strand and 212 alternate alleles on
+ * the reverse strand. The tool uses these counts towards calculating SOR. To avoid multiplying or dividing by zero
+ * values, the tool adds one to each count.</p>
+ *
+ * <pre>
+ * refFw = 1450 + 1 = 1451
+ * refRv = 345 + 1 = 346
+ * altFw = 160 + 1 = 161
+ * altRv = 212 + 1 = 213
+ * </pre>
+ *
+ * <p>Calculate SOR with the following.</p>
+ *
+ * <p><img src="http://latex.codecogs.com/svg.latex?$$ SOR = ln(symmetricalRatio) + ln(refRatio) - ln(altRatio) $$" border="0"/></p>
+ *
+ * <p>where</p>
+ *
+ * <p><img src="http://latex.codecogs.com/svg.latex?$$ symmetricalRatio = R + \frac{1}{R} $$" border="0"/></p>
+ * <p><img src="http://latex.codecogs.com/svg.latex?$$ R = \frac{(\frac{refFw}{refRv})}{(\frac{altFw}{altRv})} = \frac{(refFw*altRv)}{(altFw*refRv)} $$" border="0"/></p>
+ *
+ * <p><img src="http://latex.codecogs.com/svg.latex?$$ refRatio = \frac{(smaller\;of\;refFw\;and\;refRv)}{(larger\;of\;refFw\;and\;refRv)} $$" border="0"/></p>
+ *
+ * <p>and</p>
+ *
+ * <p><img src="http://latex.codecogs.com/svg.latex?$$ altRatio = \frac{(smaller\;of\;altFw\;and\;altRv)}{(larger\;of\;altFw\;and\;altRv)} $$" border="0"/></p>
  *
- * <p>ensures that the annotation value is large only. </p>
+ * <p>Fill out the component equations with the example counts to calculate SOR.</p>
  *
- * <p>See the <a href="http://www.broadinstitute.org/gatk/guide/article?id=4732">method document on statistical tests</a> for a more detailed explanation of this statistical test.</p>
+ * <pre>
+ * symmetricalRatio  = (1451*213)/(161*346) + (161*346)/(1451*213) = 5.7284
+ * refRatio = 346/1451 = 0.2385
+ * altRatio = 161/213 = 0.7559
+ * SOR = ln(5.7284) + ln(0.2385) – ln(0.7559) = 1.7454427755 + (-1.433) – (-0.2798) = 0.592
+ * </pre>
  *
  * <h3>Related annotations</h3>
  * <ul>
- *     <li><b><a href="https://www.broadinstitute.org/gatk/guide/tooldocs/org_broadinstitute_gatk_tools_walkers_annotator_StrandBiasBySample.php">StrandBiasBySample</a></b> outputs counts of read depth per allele for each strand orientation.</li>
- *     <li><b><a href="https://www.broadinstitute.org/gatk/guide/tooldocs/org_broadinstitute_gatk_tools_walkers_annotator_FisherStrand.php">FisherStrand</a></b> uses Fisher's Exact Test to evaluate strand bias.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_allelespecific_AS_StrandOddsRatio.php">AS_StrandOddsRatio</a></b>
+ *     allele-specific strand bias estimated by the symmetric odds ratio test.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_StrandBiasBySample.php">StrandBiasBySample</a></b>
+ *     outputs counts of read depth per allele for each strand orientation.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_FisherStrand.php">FisherStrand</a></b>
+ *     uses Fisher's Exact Test to evaluate strand bias.</li>
  * </ul>
  *
  */

src/main/java/org/broadinstitute/hellbender/tools/walkers/annotator/allelespecific/AS_StrandOddsRatio.java

@@ -16,44 +16,60 @@
 /**
  * Allele-specific strand bias estimated by the Symmetric Odds Ratio test
  *
- * <p>Strand bias is a type of sequencing bias in which one DNA strand is favored over the other, which can result in incorrect evaluation of the amount of evidence observed for one allele vs. the other. </p>
- *
- * <p>The AS_StrandOddsRatio annotation is one of several methods that aims to evaluate whether there is strand bias in the data. It is an updated form of the Fisher Strand Test that is better at taking into account large amounts of data in high coverage situations. It is used to determine if there is strand bias between forward and reverse strands for the reference or alternate allele. It does so separately for each allele. The reported value is ln-scaled.</p>
+ * <p>Strand bias is a type of sequencing bias in which one DNA strand is favored over the other, which can result in
+ * incorrect evaluation of the amount of evidence observed for one allele vs. the other. The AS_StrandOddsRatio
+ * annotation is one of several methods that aims to evaluate whether there is strand bias in the data. It is an
+ * updated form of the Fisher Strand Test that is better at taking into account large amounts of data in high coverage
+ * situations. It is used to determine if there is strand bias between forward and reverse strands for the reference or
+ * alternate allele. It does so separately for each allele. The reported value is ln-scaled.</p>
  *
  * <h3>Statistical notes</h3>
- * <p> Odds Ratios in the 2x2 contingency table below are</p>
+ * <p>The following 2x2 contingency table gives the notation for allele support and strand orientation.</p>
+ *
+ * <table>
+ * <tr><th>&nbsp;</th><th>+ strand&nbsp;&nbsp;&nbsp;</th><th>- strand&nbsp;&nbsp;&nbsp;</th></tr>
+ * <tr><th>REF&nbsp;&nbsp;&nbsp;</th><td>X[0][0]</td><td>X[0][1]</td></tr>
+ * <tr><th>ALT&nbsp;&nbsp;&nbsp;</th><td>X[1][0]</td><td>X[1][1]</td></tr>
+ * </table>
  *
- * $$ R = \frac{X[0][0] * X[1][1]}{X[0][1] * X[1][0]} $$
+ * <p>We can then represent the Odds Ratios with the equation:</p>
+ *
+ * <img src="http://latex.codecogs.com/svg.latex?$$ R = \frac{X[0][0] * X[1][1]}{X[0][1] * X[1][0]} $$" border="0"/>
  *
  * <p>and its inverse:</p>
  *
- * <table>
- *      <tr><td>&nbsp;</td><td>+ strand </td><td>- strand</td></tr>
- *      <tr><td>REF;</td><td>X[0][0]</td><td>X[0][1]</td></tr>
- *      <tr><td>ALT;</td><td>X[1][0]</td><td>X[1][1]</td></tr>
- * </table>
+ * <img src="http://latex.codecogs.com/svg.latex?$$ \frac{1}{R} = \frac{X[0][1] * X[1][0]}{X[0][0] * X[1][1]} $$" border="0"/>
  *
- * <p>The sum R + 1/R is used to detect a difference in strand bias for REF and for ALT (the sum makes it symmetric). A high value is indicative of large difference where one entry is very small compared to the others. A scale factor of refRatio/altRatio where</p>
+ * <p>The sum R + 1/R is used to detect a difference in strand bias for REF and for ALT. The sum makes it symmetric.
+ * A high value is indicative of large difference where one entry is very small compared to the others. A scale factor
+ * of refRatio/altRatio where</p>
  *
- * $$ refRatio = \frac{max(X[0][0], X[0][1])}{min(X[0][0], X[0][1} $$
+ * <img src="http://latex.codecogs.com/svg.latex?$$ refRatio = \frac{min(X[0][0], X[0][1])}{max(X[0][0], X[0][1])} $$" border="0"/>
  *
  * <p>and </p>
  *
- * $$ altRatio = \frac{max(X[1][0], X[1][1])}{min(X[1][0], X[1][1]} $$
+ * <img src="http://latex.codecogs.com/svg.latex?$$ altRatio = \frac{min(X[1][0], X[1][1])}{max(X[1][0], X[1][1])} $$" border="0"/>
  *
- * <p>ensures that the annotation value is large only. </p>
+ * <p>ensures that the annotation value is large only. The final SOR annotation is given in natural log space.</p>
  *
- * <p>See the <a href="http://www.broadinstitute.org/gatk/guide/article?id=4732">method document on statistical tests</a> for a more detailed explanation of this statistical test.</p>
+ * <p>See the <a href="http://www.broadinstitute.org/gatk/guide/article?id=4732">method document on statistical tests</a>
+ * for a more detailed explanation of this statistical test, and see
+ * <a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_StrandOddsRatio.php">StrandOddsRatio</a>
+ * documentation for an example calculation.</p>
  *
  * <h3>Caveat</h3>
  * <p>
  * The name AS_StrandOddsRatio is not entirely appropriate because the implementation was changed somewhere between the start of development and release of this annotation. Now SOR isn't really an odds ratio anymore. The goal was to separate certain cases of data without penalizing variants that occur at the ends of exons because they tend to only be covered by reads in one direction (depending on which end of the exon they're on), so if a variant has 10 ref reads in the + direction, 1 ref read in the - direction, 9 alt reads in the + direction and 2 alt reads in the - direction, it's actually not strand biased, but the FS score is pretty bad. The implementation that resulted derived in part from empirically testing some read count tables of various sizes with various ratios and deciding from there.</p>
  *
  * <h3>Related annotations</h3>
  * <ul>
- *     <li><b><a href="https://www.broadinstitute.org/gatk/guide/tooldocs/org_broadinstitute_gatk_tools_walkers_annotator_StrandOddsRatio.php">StrandOddsRatio</a></b> outputs a version of this annotation that includes all alternate alleles in a single calculation.</li>
- *     <li><b><a href="https://www.broadinstitute.org/gatk/guide/tooldocs/org_broadinstitute_gatk_tools_walkers_annotator_StrandBiasBySample.php">StrandBiasBySample</a></b> outputs counts of read depth per allele for each strand orientation.</li>
- *     <li><b><a href="https://www.broadinstitute.org/gatk/guide/tooldocs/org_broadinstitute_gatk_tools_walkers_annotator_FisherStrand.php">FisherStrand</a></b> uses Fisher's Exact Test to evaluate strand bias.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_allelespecific_AS_FisherStrand.php">AS_FisherStrand</a></b>
+ *     uses Fisher's Exact Test to evaluate strand bias.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_StrandOddsRatio.php">StrandOddsRatio</a></b>
+ *     outputs a version of this annotation that includes all alternate alleles in a single calculation.</li>
+ *     <li><b><a href="https://software.broadinstitute.org/gatk/documentation/tooldocs/current/org_broadinstitute_hellbender_tools_walkers_annotator_StrandBiasBySample.php">StrandBiasBySample</a></b>
+ *     outputs counts of read depth per allele for each strand orientation.</li>
+ *
  * </ul>
  *
  */