Fix #169: add three-tier protein-coding biotype ontology

Introduces a layered set of flags for "does this transcript make a
polypeptide?":

* `is_protein_coding` - unchanged, strict canonical `protein_coding`
  only. Preserves the contract downstream effect predictors (varcode)
  depend on.
* `is_protein_coding_extended` - widens to IG/TR gene segments and
  translated pseudogenes (`polymorphic_pseudogene`,
  `translated_{processed,unprocessed}_pseudogene`). Excludes NMD/NSD
  because those products are targeted for degradation rather than
  stable accumulation.
* `is_translated` - widest tier. Adds `nonsense_mediated_decay` and
  `non_stop_decay` on top of the extended set. Useful when picking the
  top variant effect or doing RNA-seq peptide analysis where ribosome
  occupancy matters more than stable expression.

Set constants `PROTEIN_CODING_BIOTYPES`,
`EXTENDED_PROTEIN_CODING_BIOTYPES`, and `TRANSLATED_BIOTYPES` are
exposed on `pyensembl.locus_with_genome` so callers can derive their
own categorization if needed.

Author: iskandr

pyensembl/locus_with_genome.py

@@ -14,6 +14,54 @@
 from .locus import Locus
 
 
+# Reference: http://www.gencodegenes.org/pages/biotypes.html
+#
+# Three-tier ontology of "does this transcript make a polypeptide?":
+#
+#   strict  ⊂  extended  ⊂  translated
+#
+# Each tier widens the previous one.
+
+# Tier 1 — strict canonical protein-coding biotype only. This is what
+# Ensembl uses for the bulk of reference proteome work; varcode and other
+# downstream effect predictors expect this set to drive `is_protein_coding`.
+PROTEIN_CODING_BIOTYPES = frozenset({"protein_coding"})
+
+# Tier 2 — anything Ensembl/GENCODE marks as producing a stable, functional
+# polypeptide:
+#  * IG_{C,D,J,V}_gene  - immunoglobulin gene segments. They produce
+#    protein after V(D)J recombination; the biotype reflects the productive
+#    pre-recombination form.
+#  * TR_{C,D,J,V}_gene  - T-cell receptor gene segments, same situation.
+#  * polymorphic_pseudogene  - codes for protein in some individuals,
+#    pseudogene in others. Genuinely protein-producing where it's coded.
+#  * translated_processed_pseudogene / translated_unprocessed_pseudogene -
+#    pseudogenes with ribosome occupancy / mass-spec evidence of being
+#    translated into a stable product.
+#
+# Excludes NMD / NSD because those are translated transiently and the
+# product is targeted for degradation, not stable accumulation.
+EXTENDED_PROTEIN_CODING_BIOTYPES = frozenset(PROTEIN_CODING_BIOTYPES) | frozenset({
+    "IG_C_gene", "IG_D_gene", "IG_J_gene", "IG_V_gene",
+    "TR_C_gene", "TR_D_gene", "TR_J_gene", "TR_V_gene",
+    "polymorphic_pseudogene",
+    "translated_processed_pseudogene",
+    "translated_unprocessed_pseudogene",
+})
+
+# Tier 3 — every biotype that gets translated on a ribosome, regardless of
+# whether the product survives. Adds nonsense_mediated_decay and
+# non_stop_decay to the extended set.
+#
+# Useful when you care about whether a variant lands in a translated frame
+# (e.g. picking a top variant effect, RNA-seq peptide analysis) rather
+# than whether it perturbs a stably-expressed protein product.
+TRANSLATED_BIOTYPES = frozenset(EXTENDED_PROTEIN_CODING_BIOTYPES) | frozenset({
+    "nonsense_mediated_decay",
+    "non_stop_decay",
+})
+
+
 class LocusWithGenome(Locus):
     """
     Common base class for Gene and Transcript to avoid copying
@@ -39,16 +87,47 @@ def to_dict(self):
     @property
     def is_protein_coding(self):
         """
-        We're not counting immunoglobulin-like genes from the T-cell receptor or
-        or antibodies since they occur in fragments that must be recombined.
-        It might be worth consider counting non-sense mediated decay and
-        non-stop decay since variants in these could potentially make a
-        functional protein. To read more about the biotypes used in Ensembl:
-            http://vega.sanger.ac.uk/info/about/gene_and_transcript_types.html
-            http://www.gencodegenes.org/gencode_biotypes.html
-
-        For now let's stick with the simple category of 'protein_coding', which
-        means that there is an open reading frame in this gene/transcript
-        whose successful transcription has been observed.
+        True iff this entry's biotype is the canonical ``"protein_coding"``.
+        Conservative by design - this is what downstream effect predictors
+        (e.g. varcode) read to decide whether a variant lands in a
+        translatable transcript. See :attr:`is_protein_coding_extended`
+        for a wider definition that also covers IG/TR gene segments and
+        translated pseudogenes, and :attr:`is_translated` for the widest
+        definition that additionally includes NMD/NSD targets.
+        """
+        return self.biotype in PROTEIN_CODING_BIOTYPES
+
+    @property
+    def is_protein_coding_extended(self):
+        """
+        True for any biotype that makes a stable, functional protein
+        product:
+
+        * ``protein_coding`` (canonical)
+        * ``IG_{C,D,J,V}_gene`` and ``TR_{C,D,J,V}_gene`` (immunoglobulin
+          and T-cell receptor gene segments — produce protein after
+          V(D)J recombination)
+        * ``polymorphic_pseudogene`` (codes in some individuals)
+        * ``translated_{processed,unprocessed}_pseudogene`` (pseudogenes
+          with translation evidence)
+
+        Excludes ``nonsense_mediated_decay`` and ``non_stop_decay`` —
+        those biotypes are translated but the product is targeted for
+        degradation rather than stable accumulation. Use
+        :attr:`is_translated` if you want those.
+        """
+        return self.biotype in EXTENDED_PROTEIN_CODING_BIOTYPES
+
+    @property
+    def is_translated(self):
+        """
+        True for any biotype that gets translated on a ribosome, even
+        transiently. Equivalent to :attr:`is_protein_coding_extended`
+        plus ``nonsense_mediated_decay`` and ``non_stop_decay``.
+
+        Useful when you care about whether a variant lands in a
+        translated frame at all (e.g. picking a top variant effect,
+        RNA-seq peptide analysis) rather than whether the encoded
+        protein product is stably expressed.
         """
-        return self.biotype == "protein_coding"
+        return self.biotype in TRANSLATED_BIOTYPES

pyensembl/version.py

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

tests/test_extended_protein_coding.py

@@ -0,0 +1,184 @@
+"""
+Issue #169: three-tier protein-coding biotype ontology.
+
+* ``is_protein_coding`` — strict, the canonical ``"protein_coding"`` only.
+  Unchanged from previous releases for back-compat with downstream effect
+  predictors (varcode).
+* ``is_protein_coding_extended`` — widens to IG/TR gene segments and
+  translated pseudogenes.  Excludes NMD/NSD because those are degraded.
+* ``is_translated`` — widens further to include NMD/NSD; covers any
+  biotype that goes through the ribosome at all.
+"""
+
+from pyensembl.locus_with_genome import (
+    EXTENDED_PROTEIN_CODING_BIOTYPES,
+    LocusWithGenome,
+    PROTEIN_CODING_BIOTYPES,
+    TRANSLATED_BIOTYPES,
+)
+
+from .common import eq_
+from .data import (
+    custom_mouse_genome_grcm38_subset,
+    setup_init_custom_mouse_genome,
+)
+
+
+class _BiotypeFixture:
+    """Stand-in that exposes only ``.biotype`` so we can invoke the three
+    LocusWithGenome property accessors without constructing a Genome."""
+
+    is_protein_coding = LocusWithGenome.is_protein_coding
+    is_protein_coding_extended = LocusWithGenome.is_protein_coding_extended
+    is_translated = LocusWithGenome.is_translated
+
+    def __init__(self, biotype):
+        self.biotype = biotype
+
+
+# -----------------------------
+# Set constants
+# -----------------------------
+
+
+def test_biotype_set_ontology_is_monotonic():
+    """strict ⊂ extended ⊂ translated."""
+    assert PROTEIN_CODING_BIOTYPES.issubset(EXTENDED_PROTEIN_CODING_BIOTYPES)
+    assert EXTENDED_PROTEIN_CODING_BIOTYPES.issubset(TRANSLATED_BIOTYPES)
+
+
+def test_extended_set_adds_immunoglobulin_and_tcr_and_translated_pseudogenes():
+    extras = EXTENDED_PROTEIN_CODING_BIOTYPES - PROTEIN_CODING_BIOTYPES
+    eq_(
+        extras,
+        {
+            "IG_C_gene", "IG_D_gene", "IG_J_gene", "IG_V_gene",
+            "TR_C_gene", "TR_D_gene", "TR_J_gene", "TR_V_gene",
+            "polymorphic_pseudogene",
+            "translated_processed_pseudogene",
+            "translated_unprocessed_pseudogene",
+        },
+    )
+
+
+def test_translated_set_only_adds_nmd_and_nsd_over_extended():
+    extras = TRANSLATED_BIOTYPES - EXTENDED_PROTEIN_CODING_BIOTYPES
+    eq_(extras, {"nonsense_mediated_decay", "non_stop_decay"})
+
+
+def test_strict_excludes_everything_but_canonical():
+    eq_(PROTEIN_CODING_BIOTYPES, {"protein_coding"})
+
+
+# -----------------------------
+# Property dispatch
+# -----------------------------
+
+
+def test_canonical_protein_coding_is_true_in_every_tier():
+    f = _BiotypeFixture("protein_coding")
+    assert f.is_protein_coding
+    assert f.is_protein_coding_extended
+    assert f.is_translated
+
+
+def test_ig_gene_segments_are_extended_and_translated_but_not_strict():
+    for biotype in ("IG_C_gene", "IG_D_gene", "IG_J_gene", "IG_V_gene"):
+        f = _BiotypeFixture(biotype)
+        assert not f.is_protein_coding, biotype
+        assert f.is_protein_coding_extended, biotype
+        assert f.is_translated, biotype
+
+
+def test_tcr_gene_segments_are_extended_and_translated_but_not_strict():
+    for biotype in ("TR_C_gene", "TR_D_gene", "TR_J_gene", "TR_V_gene"):
+        f = _BiotypeFixture(biotype)
+        assert not f.is_protein_coding, biotype
+        assert f.is_protein_coding_extended, biotype
+        assert f.is_translated, biotype
+
+
+def test_translated_pseudogenes_are_extended_and_translated_but_not_strict():
+    for biotype in (
+        "polymorphic_pseudogene",
+        "translated_processed_pseudogene",
+        "translated_unprocessed_pseudogene",
+    ):
+        f = _BiotypeFixture(biotype)
+        assert not f.is_protein_coding, biotype
+        assert f.is_protein_coding_extended, biotype
+        assert f.is_translated, biotype
+
+
+def test_nmd_and_nsd_are_translated_only():
+    """NMD/NSD biotypes are translated by the ribosome but don't yield a
+    stable protein product, so they're True for `is_translated` and
+    False for the other two tiers."""
+    for biotype in ("nonsense_mediated_decay", "non_stop_decay"):
+        f = _BiotypeFixture(biotype)
+        assert not f.is_protein_coding, biotype
+        assert not f.is_protein_coding_extended, biotype
+        assert f.is_translated, biotype
+
+
+def test_noncoding_biotypes_are_false_at_every_tier():
+    """Sanity: typical non-coding biotypes (lncRNA, miRNA, snRNA, plain
+    pseudogenes, regulatory) are False across all three tiers."""
+    for biotype in (
+        "lncRNA",
+        "miRNA",
+        "snRNA",
+        "snoRNA",
+        "rRNA",
+        "processed_pseudogene",
+        "unprocessed_pseudogene",
+        "transcribed_processed_pseudogene",
+        "transcribed_unprocessed_pseudogene",
+        "transcribed_unitary_pseudogene",
+        "TEC",
+        "retained_intron",
+        "processed_transcript",
+        "antisense",
+    ):
+        f = _BiotypeFixture(biotype)
+        assert not f.is_protein_coding, biotype
+        assert not f.is_protein_coding_extended, biotype
+        assert not f.is_translated, biotype
+
+
+def test_none_biotype_is_false_at_every_tier():
+    """Some GTFs (older Ensembl releases, TAIR) don't carry biotype
+    attributes at all. `biotype=None` must not crash and must be False
+    across the board."""
+    f = _BiotypeFixture(None)
+    assert not f.is_protein_coding
+    assert not f.is_protein_coding_extended
+    assert not f.is_translated
+
+
+# -----------------------------
+# Backward compat with existing callers
+# -----------------------------
+
+
+def setup_module(module):
+    setup_init_custom_mouse_genome()
+
+
+def test_existing_mouse_protein_coding_transcript_is_strict_protein_coding():
+    """The mouse partial fixture has exactly one transcript with
+    biotype=='protein_coding' and one with biotype=='processed_transcript'.
+    is_protein_coding must continue to return True for the first and
+    False for the second; downstream effect prediction depends on this."""
+    coding = custom_mouse_genome_grcm38_subset.transcripts(biotype="protein_coding")
+    eq_(len(coding), 1)
+    assert coding[0].is_protein_coding
+    assert coding[0].is_protein_coding_extended
+    assert coding[0].is_translated
+
+    all_transcripts = custom_mouse_genome_grcm38_subset.transcripts()
+    noncoding = [t for t in all_transcripts if t.biotype != "protein_coding"]
+    eq_(len(noncoding), 1)
+    assert not noncoding[0].is_protein_coding
+    assert not noncoding[0].is_protein_coding_extended
+    assert not noncoding[0].is_translated