feat!: lift over interval, not position (#66)

jsstevenson · jsstevenson · commit 6de784e5d424 · 2025-10-29T10:54:30.000-04:00
Lift over an interval rather than a single set of coordinates. This guards against a bunch of downstream problems, like whether the space in between the start and end can also cleanly lift over, and also saves us a lookup.
diff --git a/README.md b/README.md
@@ -34,7 +34,8 @@ c = Converter(Assembly.HG19, Assembly.HG38)
 Call ``convert_coordinate()``:
 
 ```python3
-c.convert_coordinate("chr7", 140453136, Strand.POSITIVE)
+c.convert_coordinate("chr7", 140453136, 140453137, Strand.POSITIVE)
+# returns [LiftoverResult(chrom='chr7', start=140753336, end=140753337, strand=<Strand.POSITIVE: '+'>)]
 ```
 
 ## Development
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "agct"
-version = "0.1.1"
+version = "0.2.0"
 authors = [
     {name = "James Stevenson"},
     {name = "Kori Kuzma"},
diff --git a/rust/src/lib.rs b/rust/src/lib.rs
@@ -40,7 +40,13 @@ impl Converter {
     }
 
     /// Perform liftover
-    pub fn lift(&self, chrom: &str, pos: u64, strand: &str) -> PyResult<Vec<Vec<String>>> {
+    pub fn lift(
+        &self,
+        chrom: &str,
+        start: u64,
+        end: u64,
+        strand: &str,
+    ) -> PyResult<Vec<Vec<String>>> {
         let parsed_strand = if strand == "+" {
             Strand::Positive
         } else if strand == "-" {
@@ -52,15 +58,14 @@ impl Converter {
             )));
         };
         // safe to unwrap coordinates because `pos` is always an int
-        let start = Coordinate::new(chrom, parsed_strand.clone(), pos);
-        let end = Coordinate::new(chrom, parsed_strand.clone(), pos + 1);
+        let start_coordinate = Coordinate::new(chrom, parsed_strand.clone(), start);
+        let end_coordinate = Coordinate::new(chrom, parsed_strand.clone(), end);
 
-        let Ok(interval) = Interval::try_new(start, end) else {
+        let Ok(interval) = Interval::try_new(start_coordinate.clone(), end_coordinate.clone())
+        else {
             return Err(ChainfileError::new_err(format!(
                 "Chainfile yielded invalid interval from coordinates: \"{}\" (\"{}\", \"{}\")",
-                &chrom,
-                pos,
-                pos + 1
+                &chrom, start_coordinate, end_coordinate
             )));
         };
         if let Some(liftover_result) = self.machine.liftover(interval.clone()) {
@@ -70,14 +75,15 @@ impl Converter {
                     vec![
                         r.query().contig().to_string(),
                         r.query().start().position().to_string(),
+                        r.query().end().position().to_string(),
                         r.query().strand().to_string(),
                     ]
                 })
                 .collect())
         } else {
             Err(NoLiftoverError::new_err(format!(
-                "No liftover available for \"{}\" on \"{}\"",
-                chrom, pos
+                "No liftover available for \"{}\" on [\"{}\",\"{}\"]",
+                chrom, start_coordinate, end_coordinate
             )))
         }
     }
diff --git a/src/agct/converter.py b/src/agct/converter.py
@@ -27,7 +27,8 @@ class LiftoverResult(NamedTuple):
     """Declare structure of liftover response"""
 
     chrom: str
-    position: int
+    start: int
+    end: int
     strand: Strand
 
 
@@ -121,7 +122,7 @@ def _download_data(version: str, file: Path) -> None:  # noqa: ARG001
         return _download_data
 
     def convert_coordinate(
-        self, chrom: str, pos: int, strand: Strand = Strand.POSITIVE
+        self, chrom: str, start: int, end: int, strand: Strand = Strand.POSITIVE
     ) -> list[LiftoverResult]:
         """Perform liftover for given params
 
@@ -130,40 +131,50 @@ def convert_coordinate(
         .. code-block:: pycon
 
            >>> from agct import Converter, Strand, Assembly
-
            >>> c = Converter(Assembly.HG19, Assembly.HG38)
-           >>> c.convert_coordinate("chr7", 140453136, Strand.POSITIVE)
-           [LiftoverResult(chrom='chr7', position=140753336, strand=<Strand.POSITIVE: '+'>)]
-
+           >>> c.convert_coordinate("chr7", 140453136, 140453137, Strand.POSITIVE)
+           [LiftoverResult(chrom='chr7', start=140753336, end=140753337, strand=<Strand.POSITIVE: '+'>)]
 
         :param chrom: chromosome name as given in chainfile. Usually e.g. ``"chr7"``.
-        :param pos: query position
+        :param start: start position of coordinate interval (inter-residue)
+        :param end: end position of coordinate interval (inter-residue)
         :param strand: query strand (``"+"`` by default).
         :return: list of coordinate matches (possibly empty)
+        :raise ValueError: if ``start`` > ``end`` and strandedness is positive, or
+            ``start`` < ``end`` and strandedness is negative
         """
+        if start < end and strand == Strand.NEGATIVE:
+            msg = f"`start` must be less than `end` on the negative strand: {start=}, {end=}"
+            raise ValueError(msg)
+        if start > end and strand == Strand.POSITIVE:
+            msg = f"`end` must be less than `start` on the positive strand: {start=}, {end=}"
+            raise ValueError(msg)
         try:
-            results = self._converter.lift(chrom, pos, strand)
+            results = self._converter.lift(chrom, start, end, strand)
         except _core.NoLiftoverError:
             results = []
         except _core.ChainfileError:
             _logger.exception(
-                "Encountered internal error while converting coordinates - is the chainfile invalid? (%s, %s, %s)",
+                "Encountered internal error while converting coordinates - is the chainfile invalid? (%s, [%s, %s], %s)",
                 chrom,
-                pos,
+                start,
+                end,
                 strand,
             )
             results = []
         formatted_results: list[LiftoverResult] = []
         for result in results:
             try:
-                pos = int(result[1])
+                lifted_over_start, lifted_over_end = int(result[1]), int(result[2])
             except ValueError:
                 _logger.exception("Got invalid position value in %s", result)
                 continue
             try:
-                strand = Strand(result[2])
+                strand = Strand(result[3])
             except ValueError:
                 _logger.exception("Got invalid Strand value in %s", result)
                 continue
-            formatted_results.append(LiftoverResult(result[0], pos, strand))
+            formatted_results.append(
+                LiftoverResult(result[0], lifted_over_start, lifted_over_end, strand)
+            )
         return formatted_results
diff --git a/tests/test_liftover.py b/tests/test_liftover.py
@@ -1,49 +1,84 @@
 """Run liftover tests."""
 
+import re
+
+import pytest
+
 from agct import Assembly, Converter, LiftoverResult, Strand
 
 
 def test_hg19_to_hg38():
     """Test hg19 to hg38 lifter."""
     converter = Converter(Assembly.HG19, Assembly.HG38)
 
-    result = converter.convert_coordinate("chr7", 140439611)
+    result = converter.convert_coordinate("chr7", 140439611, 140439611)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140739811, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 140739811, 140739811, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr7", 140439746)
+    result = converter.convert_coordinate("chr7", 140439746, 140439746)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140739946, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 140739946, 140739946, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr7", 140439703)
+    result = converter.convert_coordinate("chr7", 140439703, 140439703)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140739903, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 140739903, 140739903, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr7", 140453136)
+    result = converter.convert_coordinate("chr7", 140453136, 140453136)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140753336, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 140753336, 140753336, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr1", 206072707)
+    result = converter.convert_coordinate("chr1", 206072707, 206072708)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr1", 206268644, Strand.NEGATIVE)
+    assert result[0] == LiftoverResult("chr1", 206268644, 206268643, Strand.NEGATIVE)
 
     # coordinate exceeds bounds
-    result = converter.convert_coordinate("chr7", 14040053136)
+    result = converter.convert_coordinate("chr7", 14040053136, 14040053136)
     assert result == []
 
 
 def test_hg38_to_hg19():
     """Test hg38 to hg19 lifter."""
     converter = Converter(Assembly.HG38, Assembly.HG19)
 
-    result = converter.convert_coordinate("chr7", 140739811)
+    result = converter.convert_coordinate("chr7", 140739811, 140739811)
+    assert len(result) == 1
+    assert result[0] == LiftoverResult("chr7", 140439611, 140439611, Strand.POSITIVE)
+
+    result = converter.convert_coordinate("chr7", 140759820, 140759820)
+    assert len(result) == 1
+    assert result[0] == LiftoverResult("chr7", 140459620, 140459620, Strand.POSITIVE)
+
+    result = converter.convert_coordinate("chr7", 60878240, 60878240)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140439611, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 61646115, 61646115, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr7", 140759820)
+    result = converter.convert_coordinate("chr7", 60878240, 60878240)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 140459620, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 61646115, 61646115, Strand.POSITIVE)
 
-    result = converter.convert_coordinate("chr7", 60878240)
+    result = converter.convert_coordinate("chr7", 60878240, 60878245)
     assert len(result) == 1
-    assert result[0] == LiftoverResult("chr7", 61646115, Strand.POSITIVE)
+    assert result[0] == LiftoverResult("chr7", 61646115, 61646120, Strand.POSITIVE)
+
+
+def test_interval_input():
+    """Test that invalid intervals raise errors"""
+    converter = Converter(Assembly.HG38, Assembly.HG19)
+
+    with pytest.raises(
+        ValueError,
+        match=re.escape(
+            "`end` must be less than `start` on the positive strand: start=140739811, end=140739809"
+        ),
+    ):
+        converter.convert_coordinate("chr7", 140739811, 140739809)
+
+    with pytest.raises(
+        ValueError,
+        match=re.escape(
+            "`start` must be less than `end` on the negative strand: start=206268644, end=206268645"
+        ),
+    ):
+        converter.convert_coordinate(
+            "chr1", 206268644, 206268645, strand=Strand.NEGATIVE
+        )
