feat: add cigar utility method get_alignment_offsets

fgpyo/sam/__init__.py

@@ -368,7 +368,7 @@ class CigarOp(enum.Enum):
         code (int): The `~pysam` cigar operator code.
         character (int): The single character cigar operator.
         consumes_query (bool): True if this operator consumes query bases, False otherwise.
-        consumes_target (bool): True if this operator consumes target bases, False otherwise.
+        consumes_reference (bool): True if this operator consumes reference bases, False otherwise.
     """
 
     M = (0, "M", True, True)  #: Match or Mismatch the reference
@@ -547,6 +547,48 @@ def length_on_target(self) -> int:
         """Returns the length of the alignment on the target sequence."""
         return sum([elem.length_on_target for elem in self.elements])
 
+    def get_alignment_offsets(self, reverse: bool = False) -> Tuple[int, int]:
+        """
+            Get the starting and ending offsets for the alignment based on the CIGAR string.
+
+            Args:
+                reverse: If True, count from the end of the read sequence.
+                    Otherwise (default behavior), count from the beginning of the read sequence.
+
+            Returns:
+                A tuple (start, end), defining the start and end offsets of the aligned part
+                of the read. These offsets are 0-based and open-ended, with respect to the
+                beginning of the read sequence. (If 'reverse' is True, the offsets are with
+                respect to the end of the read sequence.)
+                If the Cigar contains no alignment operators that consume sequence bases, or
+                only clipping operators, the start and end offsets will be the same value
+                (indicating an empty region). This shared value will be the offset to the first
+                base consumed by a non-clipping operator or the length of the read sequence if
+                there is no such base.
+
+        #
+        """  # TODO: figure out how to remove the '#' from the documentation above without
+        # breaking the build
+        start_offset: int = 0
+        end_offset: int = 0
+        element: CigarElement
+        alignment_began = False
+        elements = self.elements if not reverse else reversed(self.elements)
+        for element in elements:
+            if element.operator.is_clipping and not alignment_began:
+                # We are in the clipping operators preceding the alignment
+                start_offset += element.length_on_query
+                end_offset += element.length_on_query
+            elif not element.operator.is_clipping:
+                # We are within the alignment
+                alignment_began = True
+                end_offset += element.length_on_query
+            else:
+                # We have exited the alignment and are in the clipping operators after the alignment
+                break
+
+        return start_offset, end_offset
+
     def __getitem__(
         self, index: Union[int, slice]
     ) -> Union[CigarElement, Tuple[CigarElement, ...]]:

tests/fgpyo/sam/test_cigar.py

@@ -31,3 +31,51 @@ def test_bad_index_raises_index_error(index: int) -> None:
 def test_bad_index_raises_type_error(index: int) -> None:
     with pytest.raises(TypeError):
         cigar[index]
+
+
+@pytest.mark.parametrize(
+    ("cigar_string", "start", "end"),
+    {
+        ("10M", 0, 10),
+        ("10M10I", 0, 20),
+        ("10X10I", 0, 20),
+        ("10X10D", 0, 10),
+        ("10=10D", 0, 10),
+        ("10S10M", 10, 20),
+        ("10H10M", 0, 10),
+        ("10H10S10M", 10, 20),
+        ("10H10S10M5S", 10, 20),
+        ("10H10S10M5S10H", 10, 20),
+        ("10H", 0, 0),
+        ("10S", 10, 10),
+        ("10S10H", 10, 10),
+        ("5H10S10H", 10, 10),
+    },
+)
+def test_get_alignments(cigar_string: str, start: int, end: int) -> None:
+    cig = Cigar.from_cigarstring(cigar_string)
+    assert Cigar.get_alignment_offsets(cig, reverse=False) == (start, end)
+
+
+@pytest.mark.parametrize(
+    ("cigar_string", "start", "end"),
+    {
+        ("10M", 0, 10),
+        ("10M10I", 0, 20),
+        ("10X10I", 0, 20),
+        ("10X10D", 0, 10),
+        ("10=10D", 0, 10),
+        ("10S10M", 0, 10),
+        ("10H10M", 0, 10),
+        ("10H10S10M", 0, 10),
+        ("10H10S10M5S", 5, 15),
+        ("10H10S10M5S10H", 5, 15),
+        ("10H", 0, 0),
+        ("10S", 10, 10),
+        ("10S10H", 10, 10),
+        ("5H10S10H", 10, 10),
+    },
+)
+def test_get_alignments_reversed(cigar_string: str, start: int, end: int) -> None:
+    cig = Cigar.from_cigarstring(cigar_string)
+    assert Cigar.get_alignment_offsets(cig, reverse=True) == (start, end)