Explain missing be tags in SvPileup (#29)

* Explain missing be tags in SvPileup * Generate docs files --------- Co-authored-by: Nobody <[email protected]>
fulcrumgenomics · Oct 4, 2023 · 6587c13 · 6587c13
1 parent f55b599
commit 6587c13
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 3 deletions.
diff --git a/docs/tools/SvPileup.md b/docs/tools/SvPileup.md
@@ -19,7 +19,7 @@ Two output files will be created:
 2. `<output-prefix>.bam`: a SAM/BAM file containing reads that contain SV breakpoint evidence annotated with SAM
   tag.
 
-The `be` SAM tag contains a comma-delimited list of breakpoints to which a given read belongs.  Each element is
+The `be` SAM tag contains a comma-delimited list of breakpoints to which a given alignment belongs.  Each element is
 a semi-colon delimited, with four fields:
 
 1. The unique breakpoint identifier (same identifier found in the tab-delimited output).
@@ -32,6 +32,11 @@ a semi-colon delimited, with four fields:
 4. The type of breakpoint evidence: either "split_read" for observations of an aligned segment of a single read
    with split alignments, or "read_pair" for observations _between_ reads in a read pair.
 
+As described in the Algorithm Overview below, split-read evidence is favored over across-read-pair evidence.
+Therefore, if the template (alignments for a read pair) contain both types of evidence, then the `be` tag
+will only be added to the split-read alignments (i.e. the primary and supplementary alignments of the read
+in the pair that has split-read evidence), and will not be found in the mate's alignment.
+
 ## Example output
 
 The following shows two breakpoints:

diff --git a/docs/tools/index.md b/docs/tools/index.md
@@ -4,7 +4,7 @@ title: fgsv tools
 
 # fgsv tools
 
-The following tools are available in fgsv version 0.0.3-d6090a5.
+The following tools are available in fgsv version 0.0.3-994cece.
 ## All tools
 
 All tools.

diff --git a/src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala b/src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala
@@ -51,7 +51,7 @@ object TargetBedRequirement extends FgBioEnum[TargetBedRequirement] {
     |2. `<output-prefix>.bam`: a SAM/BAM file containing reads that contain SV breakpoint evidence annotated with SAM
     |  tag.
     |
-    |The `be` SAM tag contains a comma-delimited list of breakpoints to which a given read belongs.  Each element is
+    |The `be` SAM tag contains a comma-delimited list of breakpoints to which a given alignment belongs.  Each element is
     |a semi-colon delimited, with four fields:
     |
     |1. The unique breakpoint identifier (same identifier found in the tab-delimited output).
@@ -64,6 +64,11 @@ object TargetBedRequirement extends FgBioEnum[TargetBedRequirement] {
     |4. The type of breakpoint evidence: either "split_read" for observations of an aligned segment of a single read
     |   with split alignments, or "read_pair" for observations _between_ reads in a read pair.
     |
+    |As described in the Algorithm Overview below, split-read evidence is favored over across-read-pair evidence.
+    |Therefore, if the template (alignments for a read pair) contain both types of evidence, then the `be` tag
+    |will only be added to the split-read alignments (i.e. the primary and supplementary alignments of the read
+    |in the pair that has split-read evidence), and will not be found in the mate's alignment.
+    | 
     |## Example output
     |
     |The following shows two breakpoints: