Fix #242: expose Ensembl annotation versions on Gene/Transcript/Exon/Protein (#341)

The transcript_version, gene_version, exon_version, and protein_version
columns were already loaded into the sqlite database from modern Ensembl
GTFs; they were just never surfaced on the Python objects.

Each entity now has a prefixed canonical accessor and a generic alias:

  Gene       gene_version       / versioned_gene_id
              version            / versioned_id  (aliases)

  Transcript transcript_version / versioned_transcript_id
              version            / versioned_id  (aliases)
              protein            -> new Protein view (or None for noncoding)

  Exon       exon_version       / versioned_exon_id
              version            / versioned_id  (aliases)
              exon_version is now a constructor kwarg (default None)

  Protein    protein_id, protein_version (primary)
              id, version, versioned_protein_id, versioned_id (aliases)

All version accessors return None when the GTF omits the corresponding
attribute (e.g. TAIR), and versioned_id falls back to the unversioned id
in that case.

Bump version to 2.7.0.

Author: iskandr

pyensembl/__init__.py

@@ -28,6 +28,7 @@
     genome_for_reference_name,
 )
 
+from .protein import Protein
 from .search import find_nearest_locus
 from .sequence_data import SequenceData
 from .species import find_species_by_name, check_species_object, normalize_species_name
@@ -43,6 +44,7 @@
     "MAX_ENSEMBL_RELEASE",
     "Gene",
     "Transcript",
+    "Protein",
     "Exon",
     "SequenceData",
     "find_nearest_locus",

pyensembl/exon.py

@@ -15,11 +15,22 @@
 
 
 class Exon(Locus):
-    def __init__(self, exon_id, contig, start, end, strand, gene_name, gene_id):
+    def __init__(
+        self,
+        exon_id,
+        contig,
+        start,
+        end,
+        strand,
+        gene_name,
+        gene_id,
+        exon_version=None,
+    ):
         Locus.__init__(self, contig, start, end, strand)
         self.exon_id = exon_id
         self.gene_name = gene_name
         self.gene_id = gene_id
+        self.exon_version = exon_version
 
     @property
     def id(self):
@@ -28,6 +39,23 @@ def id(self):
         """
         return self.exon_id
 
+    @property
+    def version(self):
+        """Alias for :attr:`exon_version`."""
+        return self.exon_version
+
+    @property
+    def versioned_exon_id(self):
+        """``exon_id.exon_version`` when available, else ``exon_id``."""
+        if self.exon_version is None:
+            return self.exon_id
+        return "%s.%d" % (self.exon_id, self.exon_version)
+
+    @property
+    def versioned_id(self):
+        """Alias for :attr:`versioned_exon_id`."""
+        return self.versioned_exon_id
+
     def __str__(self):
         return (
             "Exon(exon_id='%s',"
@@ -69,4 +97,5 @@ def to_dict(self):
         state_dict["exon_id"] = self.id
         state_dict["gene_name"] = self.gene_name
         state_dict["gene_id"] = self.gene_id
+        state_dict["exon_version"] = self.exon_version
         return state_dict

pyensembl/gene.py

@@ -79,6 +79,42 @@ def to_dict(self):
         state_dict["gene_name"] = self.gene_name
         return state_dict
 
+    @memoized_property
+    def gene_version(self):
+        """
+        Ensembl annotation version for this gene (int) or None if the GTF
+        did not provide a gene_version attribute.
+        """
+        if not self.db.column_exists("gene", "gene_version"):
+            return None
+        result = self.db.query_one(
+            select_column_names=["gene_version"],
+            filter_column="gene_id",
+            filter_value=self.id,
+            feature="gene",
+            required=False,
+        )
+        if not result or not result[0]:
+            return None
+        return int(result[0])
+
+    @property
+    def version(self):
+        """Alias for :attr:`gene_version`."""
+        return self.gene_version
+
+    @property
+    def versioned_gene_id(self):
+        """``gene_id.gene_version`` when a version is available, else ``gene_id``."""
+        if self.gene_version is None:
+            return self.gene_id
+        return "%s.%d" % (self.gene_id, self.gene_version)
+
+    @property
+    def versioned_id(self):
+        """Alias for :attr:`versioned_gene_id`."""
+        return self.versioned_gene_id
+
     @memoized_property
     def transcripts(self):
         """

pyensembl/genome.py

@@ -1064,14 +1064,20 @@ def exon_by_id(self, exon_id):
                 "gene_name",
                 "gene_id",
             ]
+            has_exon_version = self.db.column_exists("exon", "exon_version")
+            if has_exon_version:
+                field_names.append("exon_version")
 
-            contig, start, end, strand, gene_name, gene_id = self.db.query_one(
+            row = self.db.query_one(
                 select_column_names=field_names,
                 filter_column="exon_id",
                 filter_value=exon_id,
                 feature="exon",
                 distinct=True,
             )
+            contig, start, end, strand, gene_name, gene_id = row[:6]
+            version_value = row[6] if has_exon_version else None
+            exon_version = int(version_value) if version_value else None
 
             self._exons[exon_id] = Exon(
                 exon_id=exon_id,
@@ -1081,6 +1087,7 @@ def exon_by_id(self, exon_id):
                 strand=strand,
                 gene_name=gene_name,
                 gene_id=gene_id,
+                exon_version=exon_version,
             )
 
         return self._exons[exon_id]

pyensembl/protein.py

@@ -0,0 +1,71 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from serializable import Serializable
+
+
+class Protein(Serializable):
+    """
+    Lightweight view object exposing the protein identity for a transcript.
+    Accessed via :attr:`Transcript.protein`.
+    """
+
+    def __init__(self, protein_id, protein_version=None):
+        self.protein_id = protein_id
+        self.protein_version = protein_version
+
+    @property
+    def id(self):
+        """Alias for :attr:`protein_id`."""
+        return self.protein_id
+
+    @property
+    def version(self):
+        """Alias for :attr:`protein_version`."""
+        return self.protein_version
+
+    @property
+    def versioned_protein_id(self):
+        """``protein_id.protein_version`` when available, else ``protein_id``."""
+        if self.protein_version is None:
+            return self.protein_id
+        return "%s.%d" % (self.protein_id, self.protein_version)
+
+    @property
+    def versioned_id(self):
+        """Alias for :attr:`versioned_protein_id`."""
+        return self.versioned_protein_id
+
+    def __eq__(self, other):
+        return (
+            other.__class__ is Protein
+            and self.protein_id == other.protein_id
+            and self.protein_version == other.protein_version
+        )
+
+    def __hash__(self):
+        return hash((self.protein_id, self.protein_version))
+
+    def __str__(self):
+        return "Protein(protein_id='%s', protein_version=%s)" % (
+            self.protein_id,
+            self.protein_version,
+        )
+
+    def __repr__(self):
+        return str(self)
+
+    def to_dict(self):
+        return {
+            "protein_id": self.protein_id,
+            "protein_version": self.protein_version,
+        }

pyensembl/transcript.py

@@ -531,6 +531,42 @@ def three_prime_utr_sequence(self):
             return None
         return self.sequence[self.last_stop_codon_spliced_offset + 1 :]
 
+    @memoized_property
+    def transcript_version(self):
+        """
+        Ensembl annotation version for this transcript (int) or None if the
+        GTF did not provide a transcript_version attribute.
+        """
+        if not self.db.column_exists("transcript", "transcript_version"):
+            return None
+        result = self.db.query_one(
+            select_column_names=["transcript_version"],
+            filter_column="transcript_id",
+            filter_value=self.id,
+            feature="transcript",
+            required=False,
+        )
+        if not result or not result[0]:
+            return None
+        return int(result[0])
+
+    @property
+    def version(self):
+        """Alias for :attr:`transcript_version`."""
+        return self.transcript_version
+
+    @property
+    def versioned_transcript_id(self):
+        """``transcript_id.transcript_version`` when available, else ``transcript_id``."""
+        if self.transcript_version is None:
+            return self.transcript_id
+        return "%s.%d" % (self.transcript_id, self.transcript_version)
+
+    @property
+    def versioned_id(self):
+        """Alias for :attr:`versioned_transcript_id`."""
+        return self.versioned_transcript_id
+
     @memoized_property
     def protein_id(self):
         result_tuple = self.db.query_one(
@@ -546,6 +582,32 @@ def protein_id(self):
         else:
             return None
 
+    @memoized_property
+    def protein(self):
+        """
+        :class:`Protein` view object for this transcript's encoded protein,
+        or ``None`` if this transcript is non-coding.
+        """
+        from .protein import Protein
+
+        if not self.protein_id:
+            return None
+        protein_version = None
+        if self.db.column_exists("CDS", "protein_version"):
+            result = self.db.query_one(
+                select_column_names=["protein_version"],
+                filter_column="transcript_id",
+                filter_value=self.id,
+                feature="CDS",
+                distinct=True,
+                required=False,
+            )
+            if result and result[0]:
+                protein_version = int(result[0])
+        return Protein(
+            protein_id=self.protein_id, protein_version=protein_version
+        )
+
     @memoized_property
     def protein_sequence(self):
         if self.protein_id:

pyensembl/version.py

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