feat: add left/right template counts when aggregating pileups. (#23)

* feat: add left/right template counts when aggregating pileups.

This is the denominator used when calculating frequency.

docs/04_Metrics.md

@@ -42,6 +42,8 @@ Aggregated cluster of breakpoint pileups
 |right_pileups|PositionList|List of constituent right breakends|
 |left_frequency|Option[Double]|Proportion of templates mapping at one of the left breakends that support a breakpoint.                              If a template maps across multiple breakends, it is only counted once. If a template                              maps entirely between two breakends but does not overlap one, it is not counted. If two                              paired reads straddle a breakend, the template is counted as reading across the                              breakend. If two paired reads both overlap the same breakend, the template is counted                              once.|
 |right_frequency|Option[Double]|Proportion of reads mapping at one of the right breakends that support a breakpoint|
+|left_templates|Option[Int]|The total number of templates used for the denominator when calculating `left_frequency`.|
+|right_templates|Option[Int]|The total number of templates used for the denominator when calculating `right_frequency`.|
 |left_overlaps_target|Boolean|True if the left aggregated region overlaps a target region|
 |right_overlaps_target|Boolean|True if the right aggregated region overlaps a target region|
 |left_targets|Option[String]|The comma-delimited list of target names overlapping the left breakpoint|

docs/tools/index.md

@@ -4,7 +4,7 @@ title: fgsv tools
 
 # fgsv tools
 
-The following tools are available in fgsv version 0.0.2-07c651c.
+The following tools are available in fgsv version 0.0.2-ce6db29.
 ## All tools
 
 All tools.

src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala

@@ -245,6 +245,8 @@ object BreakpointCategory extends Enumeration {
  *                              breakend. If two paired reads both overlap the same breakend, the template is counted
  *                              once.
  * @param right_frequency       Proportion of reads mapping at one of the right breakends that support a breakpoint
+ * @param left_templates        The total number of templates used for the denominator when calculating `left_frequency`.
+ * @param right_templates       The total number of templates used for the denominator when calculating `right_frequency`.
  * @param left_overlaps_target  True if the left aggregated region overlaps a target region
  * @param right_overlaps_target True if the right aggregated region overlaps a target region
  * @param left_targets  the comma-delimited list of target names overlapping the left breakpoint
@@ -267,6 +269,8 @@ case class AggregatedBreakpointPileup(id: String,
                                       right_pileups: PositionList,
                                       left_frequency: Option[Double] = None,
                                       right_frequency: Option[Double] = None,
+                                      left_templates: Option[Int] = None,
+                                      right_templates: Option[Int] = None,
                                       left_overlaps_target: Boolean = false,
                                       right_overlaps_target: Boolean = false,
                                       left_targets: Option[String] = None,
@@ -335,7 +339,7 @@ case class AggregatedBreakpointPileup(id: String,
                          minFrequency: Double):
   AggregatedBreakpointPileup = {
 
-    def frequency(contig: String, pileups: PositionList, minPos: Int, maxPos: Int): Option[Double] = source match {
+    def frequency_and_count(contig: String, pileups: PositionList, minPos: Int, maxPos: Int): Option[(Double, Int)] = source match {
       case None => None
       case Some(src) =>
         val numOverlap = numOverlappingTemplates(
@@ -349,13 +353,16 @@ case class AggregatedBreakpointPileup(id: String,
         )
         numOverlap match {
           case None => None
-          case Some(n) => Some(total.toDouble / n)
+          case Some(n) => Some(total.toDouble / n, n)
         }
     }
-
+    val leftResult  = frequency_and_count(left_contig, left_pileups, left_min_pos, left_max_pos)
+    val rightResult = frequency_and_count(right_contig, right_pileups, right_min_pos, right_max_pos)
     this.copy(
-      left_frequency = frequency(left_contig, left_pileups, left_min_pos, left_max_pos),
-      right_frequency = frequency(right_contig, right_pileups, right_min_pos, right_max_pos),
+      left_frequency  = leftResult.map(_._1),
+      right_frequency = rightResult.map(_._1),
+      left_templates  = leftResult.map(_._2),
+      right_templates = rightResult.map(_._2),
     )
   }
 

src/test/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileupTest.scala

@@ -380,6 +380,8 @@ class AggregateSvPileupTest extends UnitSpec {
       right_pileups  = PositionList(300, 400, 425, 500),
       left_frequency = Some(8d/16),
       right_frequency = Some(8d/8),
+      left_templates = Some(16),
+      right_templates = Some(8),
       left_overlaps_target = true,
       right_overlaps_target = true,
       left_targets = Some("target-1"),
@@ -404,6 +406,8 @@ class AggregateSvPileupTest extends UnitSpec {
       right_pileups  = PositionList(401),
       left_frequency = Some(2d/2),
       right_frequency = Some(2d/8),
+      left_templates = Some(2),
+      right_templates = Some(8),
       left_overlaps_target = false,
       right_overlaps_target = false,  // There is a BED feature 401-402; BED is 0-based half open
     )
@@ -439,6 +443,8 @@ class AggregateSvPileupTest extends UnitSpec {
       right_pileups  = PositionList(300, 400, 425, 500),
       left_frequency = Some(8d/16),
       right_frequency = Some(8d/8),
+      left_templates = Some(16),
+      right_templates = Some(8),
       left_targets   = Some("1,2,5")
     )