Fix #186: Locus.intersect returns the overlap region or None

Mirrors bedtools intersect for a single pair: returns a new Locus
covering the inclusive-inclusive overlap between this locus and
another, or None when they're on different contigs, opposite strands
(unless ignore_strand=True), or disjoint. The result is reported on
self's strand.

Bump version to 2.9.3.

Author: iskandr

pyensembl/locus.py

@@ -240,6 +240,25 @@ def overlap_length(self, other, ignore_strand=False):
             return 0
         return max(0, min(self.end, other.end) - max(self.start, other.start) + 1)
 
+    def intersect(self, other, ignore_strand=False):
+        """
+        Return a new :class:`Locus` covering the inclusive-inclusive
+        overlap between this locus and ``other``, or ``None`` if they do
+        not overlap. Mirrors bedtools' ``intersect`` for a single pair.
+
+        Different contigs always return ``None``. Different strands return
+        ``None`` unless ``ignore_strand=True`` is passed, in which case the
+        result is reported on this locus's strand.
+        """
+        strand = None if ignore_strand else other.strand
+        if not self.can_overlap(other.contig, strand):
+            return None
+        start = max(self.start, other.start)
+        end = min(self.end, other.end)
+        if start > end:
+            return None
+        return Locus(contig=self.contig, start=start, end=end, strand=self.strand)
+
     def contains(self, contig, start, end, strand=None):
         return (
             self.can_overlap(contig, strand) and start >= self.start and end <= self.end

pyensembl/version.py

@@ -1,4 +1,4 @@
-__version__ = "2.9.2"
+__version__ = "2.9.3"
 
 def print_version():
     print(f"v{__version__}")

tests/test_locus.py

@@ -189,3 +189,24 @@ def test_locus_overlap_length():
     other_neg = Locus("1", 10, 20, "-")
     assert locus.overlap_length(other_neg) == 0
     assert locus.overlap_length(other_neg, ignore_strand=True) == 11
+
+
+def test_locus_intersect():
+    a = Locus("1", 10, 20, "+")
+    # full overlap (other contained in a)
+    eq_result = a.intersect(Locus("1", 12, 15, "+"))
+    assert eq_result == Locus("1", 12, 15, "+")
+    # partial overlap (right tail of a)
+    assert a.intersect(Locus("1", 15, 30, "+")) == Locus("1", 15, 20, "+")
+    # partial overlap (left tail of a)
+    assert a.intersect(Locus("1", 1, 15, "+")) == Locus("1", 10, 15, "+")
+    # single-base boundary overlap
+    assert a.intersect(Locus("1", 20, 30, "+")) == Locus("1", 20, 20, "+")
+    # adjacent, non-overlapping
+    assert a.intersect(Locus("1", 21, 30, "+")) is None
+    # different contig
+    assert a.intersect(Locus("2", 10, 20, "+")) is None
+    # opposite strand: None by default, accepts when ignore_strand=True
+    other_neg = Locus("1", 12, 18, "-")
+    assert a.intersect(other_neg) is None
+    assert a.intersect(other_neg, ignore_strand=True) == Locus("1", 12, 18, "+")