Fix #190: Genome.merged_gene_intervals returns union of gene loci (#347)

Promotes the existing private _merge_ranges helper in transcript.py to
a public common.merge_intervals (the old name is kept as an alias).

Adds Genome.merged_gene_intervals(contig, strand=None) which queries
all (start, end) pairs from the gene table on the given contig and
returns a sorted list of non-overlapping inclusive intervals. Adjacent
intervals (end+1 == next start) are merged. Useful for "is this
position inside any gene?" / gene-density without double-counting
overlapping genes.

Bump version to 2.9.4.

Author: iskandr

pyensembl/common.py

@@ -50,6 +50,25 @@ def _memoize_cache_key(args, kwargs):
     return tuple(cache_key_list)
 
 
+def merge_intervals(ranges):
+    """
+    Sort ``[(start, end)]`` inclusive-inclusive ranges and merge any pair
+    that overlaps or is exactly adjacent (``end + 1 == next start``).
+    Returns a new list of merged ``(start, end)`` tuples in ascending order.
+    """
+    if not ranges:
+        return []
+    ordered = sorted(ranges)
+    merged = [ordered[0]]
+    for start, end in ordered[1:]:
+        prev_start, prev_end = merged[-1]
+        if start <= prev_end + 1:
+            merged[-1] = (prev_start, max(prev_end, end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
 def memoize(fn):
     """Simple reset-able memoization decorator for functions and methods,
     assumes that all arguments to the function can be hashed and

pyensembl/genome.py

@@ -22,9 +22,11 @@
 from serializable import Serializable
 
 from .download_cache import DownloadCache
+from .common import merge_intervals
 from .database import Database
 from .exon import Exon
 from .gene import Gene
+from .normalization import normalize_chromosome, normalize_strand
 from .search import find_nearest_locus
 from .sequence_data import SequenceData
 from .transcript import Transcript
@@ -588,6 +590,24 @@ def nearest_gene(self, contig, position, end=None, strand=None):
             loci=self.genes(contig=contig, strand=strand),
         )
 
+    def merged_gene_intervals(self, contig, strand=None):
+        """
+        Return the union of all gene loci on ``contig`` as a sorted list of
+        non-overlapping ``(start, end)`` tuples. Adjacent intervals
+        (``end + 1 == next start``) are merged into one. Pass ``strand`` to
+        restrict to one strand of the contig.
+
+        Useful for asking "is this position inside any gene?" or computing
+        gene-density coverage without double-counting overlapping genes.
+        """
+        sql = "SELECT start, end FROM gene WHERE seqname = ?"
+        params = [normalize_chromosome(contig)]
+        if strand is not None:
+            sql += " AND strand = ?"
+            params.append(normalize_strand(strand))
+        rows = self.db.run_sql_query(sql, query_params=params)
+        return merge_intervals(rows)
+
     def nearest_transcript(self, contig, position, end=None, strand=None):
         """
         Find the transcript on ``contig`` whose locus is nearest to the

pyensembl/transcript.py

@@ -12,27 +12,13 @@
 
 from memoized_property import memoized_property
 
-from .common import memoize
+from .common import memoize, merge_intervals
 from .exon import Exon
 from .locus_with_genome import LocusWithGenome
 
 
-def _merge_ranges(ranges):
-    """
-    Sort [(start, end)] inclusive-inclusive ranges and merge any that are
-    adjacent or overlapping (end+1 == next start).
-    """
-    if not ranges:
-        return []
-    ordered = sorted(ranges)
-    merged = [ordered[0]]
-    for start, end in ordered[1:]:
-        prev_start, prev_end = merged[-1]
-        if start <= prev_end + 1:
-            merged[-1] = (prev_start, max(prev_end, end))
-        else:
-            merged.append((start, end))
-    return merged
+# Back-compat alias for callers that imported the private helper.
+_merge_ranges = merge_intervals
 
 
 class Transcript(LocusWithGenome):
@@ -435,7 +421,7 @@ def coding_sequence_position_ranges(self):
             ranges.extend(
                 self._transcript_feature_position_ranges("stop_codon", required=False)
             )
-        return _merge_ranges(ranges)
+        return merge_intervals(ranges)
 
     @memoized_property
     def complete(self):

pyensembl/version.py

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

tests/test_merged_gene_intervals.py

@@ -0,0 +1,91 @@
+"""
+Issue #190: Genome.merged_gene_intervals(contig) returns sorted
+non-overlapping (start, end) tuples after merging adjacent/overlapping
+gene loci on the contig.
+"""
+
+from pyensembl.common import merge_intervals
+
+from .common import TemporaryDirectory, eq_
+from pyensembl import Genome
+
+
+def test_merge_intervals_handles_overlap_adjacency_and_disjoint():
+    # Overlapping
+    eq_(merge_intervals([(1, 10), (5, 15)]), [(1, 15)])
+    # Adjacent (end+1 == next start) merges
+    eq_(merge_intervals([(1, 10), (11, 20)]), [(1, 20)])
+    # One-base gap stays separate
+    eq_(merge_intervals([(1, 10), (12, 20)]), [(1, 10), (12, 20)])
+    # Unsorted input is reordered
+    eq_(merge_intervals([(50, 60), (1, 10), (5, 15)]), [(1, 15), (50, 60)])
+    # Containment
+    eq_(merge_intervals([(1, 100), (10, 20)]), [(1, 100)])
+    # Empty
+    eq_(merge_intervals([]), [])
+
+
+def test_merged_gene_intervals_against_synthetic_gtf():
+    """Build a tiny GTF with three overlapping and one disjoint gene on
+    chr1 plus a single gene on chr2, then assert the merged intervals."""
+    with TemporaryDirectory() as tmpdir:
+        import os
+        gtf_path = os.path.join(tmpdir, "merge.gtf")
+        with open(gtf_path, "w") as f:
+            # chr1: gene1 [100,200], gene2 [150,250] overlap → [100,250]
+            #       gene3 [251,300] adjacent → merges into [100,300]
+            #       gene4 [500,600] disjoint
+            # chr1 -: gene5 on minus strand for strand-filter test
+            # chr2: gene6 standalone
+            for gene_id, contig, start, end, strand in [
+                ("G1", "1", 100, 200, "+"),
+                ("G2", "1", 150, 250, "+"),
+                ("G3", "1", 251, 300, "+"),
+                ("G4", "1", 500, 600, "+"),
+                ("G5", "1", 700, 800, "-"),
+                ("G6", "2", 1000, 1100, "+"),
+            ]:
+                f.write(
+                    "%s\ttest\tgene\t%d\t%d\t.\t%s\t.\t"
+                    'gene_id "%s"; gene_name "%s";\n'
+                    % (contig, start, end, strand, gene_id, gene_id)
+                )
+                f.write(
+                    "%s\ttest\ttranscript\t%d\t%d\t.\t%s\t.\t"
+                    'gene_id "%s"; transcript_id "%s_t"; gene_name "%s";\n'
+                    % (contig, start, end, strand, gene_id, gene_id, gene_id)
+                )
+                f.write(
+                    "%s\ttest\texon\t%d\t%d\t.\t%s\t.\t"
+                    'gene_id "%s"; transcript_id "%s_t"; exon_number "1"; gene_name "%s";\n'
+                    % (contig, start, end, strand, gene_id, gene_id, gene_id)
+                )
+
+        genome = Genome(
+            reference_name="GRCh38",
+            annotation_name="merge_intervals_test",
+            gtf_path_or_url=gtf_path,
+            cache_directory_path=tmpdir,
+        )
+        genome.index()
+
+        # chr1 (any strand): overlapping triplet collapses, gene4 stays,
+        # minus-strand gene5 is included when strand is not filtered.
+        eq_(
+            genome.merged_gene_intervals("1"),
+            [(100, 300), (500, 600), (700, 800)],
+        )
+        # Strand-restricted: gene5 is excluded
+        eq_(
+            genome.merged_gene_intervals("1", strand="+"),
+            [(100, 300), (500, 600)],
+        )
+        # Only the minus-strand gene
+        eq_(
+            genome.merged_gene_intervals("1", strand="-"),
+            [(700, 800)],
+        )
+        # chr2: single gene
+        eq_(genome.merged_gene_intervals("2"), [(1000, 1100)])
+        # Empty contig returns []
+        eq_(genome.merged_gene_intervals("3"), [])