orfdata 0.1.0__tar.gz → 0.2.0__tar.gz

orfdata-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include lint.sh test.sh deploy.sh
+recursive-include docs *.md
+recursive-include tests *.py *.json *.md

{orfdata-0.1.0 → orfdata-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.1.0
+Version: 0.2.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0
@@ -90,8 +90,9 @@ RNA products. Reference evidence stays separate from evidence for a variant or
 fusion. See the [API and integration guide](docs/reference.md).
 
 The catalogue API supports other species, with explicit species and assembly
-checks. **Bundled evidence is currently human-only**; mouse bindings use synthetic
-test data. [Adding another species](docs/reference.md#other-species).
+checks. **Bundled experimental evidence is currently human-only**. Offline tests
+bind real human, mouse, dog and yeast reference slices; those fixtures are not
+new experimental ORF catalogues. [Species and reference identity](docs/species.md).
 
 Install with `pip install orfdata[pyensembl]`. See the
 [quantitative, multispecies data roadmap](https://github.com/openvax/orfdata/issues/3)

{orfdata-0.1.0 → orfdata-0.2.0}/README.md

@@ -68,8 +68,9 @@ RNA products. Reference evidence stays separate from evidence for a variant or
 fusion. See the [API and integration guide](docs/reference.md).
 
 The catalogue API supports other species, with explicit species and assembly
-checks. **Bundled evidence is currently human-only**; mouse bindings use synthetic
-test data. [Adding another species](docs/reference.md#other-species).
+checks. **Bundled experimental evidence is currently human-only**. Offline tests
+bind real human, mouse, dog and yeast reference slices; those fixtures are not
+new experimental ORF catalogues. [Species and reference identity](docs/species.md).
 
 Install with `pip install orfdata[pyensembl]`. See the
 [quantitative, multispecies data roadmap](https://github.com/openvax/orfdata/issues/3)

orfdata-0.2.0/deploy.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Publish only a reviewed version from clean, synchronized main.
+set -euo pipefail
+PYTHON="${PYTHON:-python}"
+[[ "$(git branch --show-current)" == main ]] || { echo 'Release from main only' >&2; exit 1; }
+[[ -z "$(git status --porcelain)" ]] || { echo 'Release requires a clean tree' >&2; exit 1; }
+git fetch origin main
+[[ "$(git rev-parse HEAD)" == "$(git rev-parse origin/main)" ]] || { echo 'Synchronize main first' >&2; exit 1; }
+version="$($PYTHON -c 'from orfdata.version import __version__; print(__version__)')"
+if git rev-parse "v$version" >/dev/null 2>&1; then echo 'Version tag already exists' >&2; exit 1; fi
+./lint.sh
+./test.sh
+"$PYTHON" -m build
+"$PYTHON" -m twine check "dist/orfdata-$version.tar.gz" "dist/orfdata-$version-py3-none-any.whl"
+if [[ "${1:-}" == --dry-run ]]; then exit 0; fi
+"$PYTHON" -m twine upload "dist/orfdata-$version.tar.gz" "dist/orfdata-$version-py3-none-any.whl"
+git tag "v$version"
+git push origin "v$version"

orfdata-0.2.0/docs/design.md

@@ -0,0 +1,84 @@
+# General ORF reference and evidence layer
+
+Status: architectural correction to the unmerged oncoref/Varcode/Isovar PRs.
+Working distribution name: orfdata. No release is authorized by this document.
+
+## Ownership
+
+PyEnsembl remains responsible for reference genomes, annotations, transcripts,
+exons and canonical proteins. A small separate library adds source-defined ORFs
+on those transcripts and their experimental evidence. oncoref remains a consumer
+for cancer-specific analysis. Neither Varcode nor Isovar owns reference datasets.
+PepData's immune-epitope/property scope is not a fit.
+
+The new library has a dependency-light data layer and a PyEnsembl-compatible
+binding API. It must not import Varcode, Isovar or oncoref. No new PyEnsembl core
+API is needed to bind a Transcript; avoid reverse dependencies or monkey-patching.
+
+## Public objects
+
+- ORFModel: immutable source ORF identity, assembly, species (NCBI taxon ID and
+  scientific name), translation table, parent transcript, spliced coding blocks,
+  protein sequence, ORF class. ORF class is distinct from transcript biotype.
+- ORFEvidence: ribosome observations and peptide-level MS observations with their
+  source, accession, mapping ambiguity, assay and quality. Native evidence does
+  not become evidence for a modified product; orthology is not direct evidence.
+- ORFRecord: model plus evidence, retaining legacy flat accessors for Isovar.
+- ReferenceORF: validated binding of a record to a PyEnsembl Transcript, retaining
+  the original transcript (including noncoding biotype), cDNA coding interval,
+  coding sequence and actual resolved annotation/version. Multiple ORFs per RNA
+  are normal. Annotation lookup never relabels the transcript protein-coding.
+- ORFCatalog: explicitly one species/assembly per catalogue. Query by transcript,
+  gene, locus, class or evidence. for_transcript(transcript) validates and returns
+  ReferenceORFs. Load custom versioned catalogues offline. The initial bundled
+  human data is identified as human-only; no implied mouse evidence.
+- Varcode ORFAnnotation: reference ORF plus effect and realized products. Exports
+  separately identify reference model/evidence and modifications, preserving
+  phase/splice alternatives. A private transcript-engine adapter permits reuse
+  of existing variant logic without exposing a fake transcript as the base ORF.
+- Isovar: attach those same annotations to RNA products with candidate-specific
+  RNA support, maintaining conditional translation and unresolved RNA polarity.
+
+## Generality and compatibility
+
+Support uORF, overlapping uORF, internal/out-of-frame, downstream and noncoding-
+transcript ORFs with the same model and evidence schema. Preserve source classes
+verbatim rather than equating them with Ensembl transcript biotypes. Complete
+stopped ORFs are the initial binding contract; partial models are rejected
+explicitly rather than given invented boundaries.
+
+A generic v1 schema requires species, assembly, translation table and source
+provenance. Legacy Isovar human data may be read only through its explicit known
+human/GRCh38 provenance. Keep legacy Isovar uorf_* imports/call shapes working.
+New generic APIs use orf terminology; defaults remain explicit about dataset scope.
+
+Multi-species path: one versioned catalogue per organism/assembly, importer input
+using the same model/evidence schema, optional organism-specific source adapters
+(e.g. OpenProt). Test a mouse noncoding transcript with real PyEnsembl objects,
+plus human coding transcripts, different frames, minus strand, splice junctions,
+assembly/species mismatches and unknown translation tables. Synthetic examples
+are identified as test fixtures, never scientific observations. OpenProt already
+publishes multiple species with Ensembl/RefSeq mappings and evidence filters.
+
+## Review corrections
+
+Remove the oncoref runtime dependency from both consumers and withdraw its ORF
+PR when the replacement is reviewable. Keep unrelated lint fixes independently.
+Review evidence retention for duplicate reference codons (retain all copies),
+explicit translation tables and noncoding parents; preserve all Sid alternatives.
+Document unsupported de novo initiation discovery and partial ORFs honestly.
+
+## Verification
+
+New library: existing evidence/context/builder tests, generic data round-trip,
+PyEnsembl binding and multi-species isolation, independently installed wheel.
+Varcode/Isovar: focused tests then required full lint/test scripts. Regenerate
+Sid outputs from the original packaged reads. Existing human evidence counts and
+native peptide attribution must remain unchanged. Do not claim release until CI,
+merge and PyPI publication actually complete; publication remains unapproved.
+
+Primary sources:
+- https://www.nature.com/articles/s41587-022-01369-0
+- https://www.nature.com/articles/s41586-026-10459-x
+- https://archive.openprot.org/p/help
+- https://github.com/openvax/pyensembl

orfdata-0.2.0/docs/reference.md

@@ -0,0 +1,145 @@
+# Using orfdata
+
+See the [README](../README.md) for the purpose, ORF types and basic example.
+
+## Objects and queries
+
+`load_catalog()` loads the bundled reference data offline. Catalogue access uses
+only the Python standard library; the optional `pyensembl` extra supplies
+PyEnsembl. Binding uses a transcript you have already loaded.
+
+`catalog.for_transcript(transcript)` returns a `ReferenceORF` for each matching
+ORF. Each has:
+
+- `model`: source identity, ORF type, coordinates, species and protein sequence.
+- `evidence`: ribosome observations and peptide-level MS observations.
+- `transcript`: the original PyEnsembl transcript, including its original biotype.
+- `coding_sequence` and `protein_sequence`: checked against that transcript.
+
+Binding checks the assembly, available species information, transcript identity,
+full spliced coding path, protein sequence and terminal stop. A matching gene
+name alone is insufficient. Incompatible annotations raise an error.
+
+To inspect source records without loading a transcript:
+
+```python
+from orfdata import load_catalog
+
+catalog = load_catalog()
+records = catalog.query(gene="TPST1", evidence="ms")
+```
+
+## Evidence
+
+Use `orf.evidence.has_evidence("ribosome")`, `"shotgun"` (protease-digest MS),
+`"mhc"` (including human HLA), or `"ms"` (any supporting MS observation).
+`"hla"` selects human HLA observations specifically. Source observations whose
+MS assay type is unspecified remain labelled `"ms_unclassified"`.
+
+```python
+orf.evidence.has_evidence("ms", require_unique=True, require_reviewed=True)
+```
+
+This requires a supporting spectrum review and a single protein mapping
+**within that source's search scope**. It does not imply uniqueness across every
+possible protein. Inspect `orf.evidence.peptides` for peptide sequences, source
+accessions, matching intervals, mapping counts and review quality. Missing counts
+remain unknown; low or mixed spectrum reviews do not count as supporting MS.
+
+The distinction between translation, peptide detection and functional protein
+evidence follows the [TransCODE study](https://www.nature.com/articles/s41586-026-10459-x).
+Source evidence belongs to the exact reference ORF. It is not automatically
+evidence for a different isoform, a mutant protein, a fusion or another species.
+
+## Variants and RNA products
+
+Varcode keeps the reference object alongside its modification:
+
+```python
+from pyensembl import EnsemblRelease
+from orfdata import load_catalog
+from varcode import Variant, annotate_orf_variants
+
+genome = EnsemblRelease(95, species="human")  # already downloaded and indexed
+transcript = genome.transcript_by_id("ENST00000304842")
+orf, = load_catalog().for_transcript(transcript)
+variant = Variant("7", 66205486, "C", "G", genome=genome)
+annotation = annotate_orf_variants([variant], orf)
+assert annotation.reference is orf
+print(annotation.effect)  # P2A in the TPST1 upstream ORF
+result = annotation.to_dict()  # reference, evidence and altered products
+```
+
+Isovar's `annotate_sv_orf_evidence` attaches the same reference annotations to
+reconstructed RNA products and preserves each candidate's RNA support. For
+example, the native TPST1 peptide KIILSKISV is absent from the Sid TPST1–CRCP
+alternatives, so its MS evidence does not support those altered products.
+
+The reference integration is available in Varcode 10.12.0; the Isovar 1.50.0
+integration is in review. The stricter reference-context contract is coordinated
+with Varcode 10.13.0 and Isovar 1.51.0.
+
+## Data and limits
+
+The bundled human GRCh38 catalogue, dataset `2026-10-11.1`, draws on the
+[GENCODE Phase I reference](https://www.nature.com/articles/s41587-022-01369-0),
+[TransCODE author exports](https://www.nature.com/articles/s41586-026-10459-x),
+and the [community microprotein spectrum benchmark](https://www.nature.com/articles/s41467-025-68002-x).
+All 7,264 ORF paths and proteins were checked against Ensembl 101 GTF, coding RNA
+and noncoding RNA FASTAs. The 2,186 models with supporting MS observations use
+the packaged source-specific filters; this is not a count of proven functional
+proteins. Packaged manifests retain source accessions, checksums, licenses,
+processing rules and dataset version.
+
+The current binder accepts complete ORFs with a terminal stop, NCBI translation
+table 1, and ATG/CTG/TTG initiation codons. All bundled models start at ATG.
+Other genetic codes, initiation conventions and incomplete ORFs need additional
+support. Transcript-boundary contexts can be partial; initiation efficiency and
+effects on the main coding region are not established by these data.
+
+Circular-RNA translation, stop-codon readthrough and translation from new
+transcripts or fusions are not covered by this reference catalogue. Those need
+additional source data and, where necessary, model support. ORF discovery is
+outside the current API.
+
+`load_uorf_catalog()` preserves Isovar's upstream-only snapshot: 3,771 models,
+dataset `2026-10-08.2`. New code should use the broader `load_catalog()` API.
+
+## Other species
+
+[ReferenceContext and ScopedTarget](species.md) keep taxa, strains, assemblies
+and annotation versions separate. Custom genomes without species/taxonomy need
+an explicit context when binding; source-pinned contexts require an exact match.
+
+`load_catalog(path)` reads a custom versioned JSON catalogue. Each catalogue is
+scoped to one species and assembly; each model records its NCBI taxon, scientific
+name, assembly, translation table and source. Human evidence is never transferred
+to a mouse ortholog. Mouse bindings are tested with synthetic ORFs on PyEnsembl
+transcripts; there is no bundled mouse evidence.
+
+To build a catalogue, create `ORFModel` objects from source coordinates and
+sequences, attach source observations with `ORFRecord.from_model(model, evidence)`,
+and construct `ORFCatalog(records, metadata)`. Its `to_dict()` produces the
+`orfdata.catalog.v1` JSON representation. Genomic coding blocks are 1-based,
+inclusive, sorted by genomic position, and include the terminal stop codon.
+
+[OpenProt](https://archive.openprot.org/p/help) is a possible source for further species,
+with organism/assembly-specific models, transcript mappings and experimental
+evidence. A future importer must pin releases, preserve ambiguity and licensing,
+and validate coordinate conventions. No OpenProt importer is included yet.
+
+## Rebuild and verify
+
+From a development checkout with the PyEnsembl dependency installed:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m orfdata.build --source-dir /path/to/sources --prepare-sources \
+    --all-orfs --output orfdata/data/orf-evidence
+./lint.sh
+./test.sh
+```
+
+Source preparation downloads pinned public inputs and needs Rscript to extract
+the author export. Ordinary queries need neither R nor spreadsheet libraries.
+See the [design notes](design.md) for the model and library boundaries.

orfdata-0.2.0/docs/species.md

@@ -0,0 +1,58 @@
+# Species and references
+
+ORFdata uses the same objects for human, mouse, dog, yeast and custom species.
+Every ORF states its NCBI species taxon, assembly and genetic code. A
+`ReferenceContext` also pins the annotation provider/version and can retain a
+versioned assembly accession, strain taxon/label and sequence-set SHA-256.
+
+```python
+from orfdata import ReferenceContext, ScopedTarget
+
+yeast = ReferenceContext(
+    taxon_id=4932, species="saccharomyces_cerevisiae",
+    genome_build="R64-1-1", assembly_accession="GCA_000146045.2",
+    annotation_name="ensembl", annotation_version="115",
+    strain="S288C", strain_taxon_id=559292,
+)
+target = ScopedTarget(yeast, "protein", "YFL039C", "ensembl:115")
+print(target.key)
+```
+
+Target keys include the reference, source namespace, kind and source identifier.
+Identical local IDs in different species, reference versions or datasets remain
+separate. Known aliases such as `canis_familiaris` and
+`canis_lupus_familiaris` resolve to dog taxon 9615 through a versioned mapping;
+the original name stays in exports. Assembly names are never automatically
+equated, and strain identity is never discarded. Unknown species require their
+own explicit taxonomy context; they do not require a schema change.
+
+`ReferenceContext.from_genome(genome)` resolves available PyEnsembl metadata
+offline. A custom Genome without species/taxonomy needs an explicit context:
+
+```python
+bound = record.bind(transcript, context=yeast)
+# Or: catalog.for_transcript(transcript, context=yeast)
+```
+
+The caller declares metadata absent from a custom genome; any metadata already
+present must agree. The binder still checks transcript version, strand, complete
+spliced path, coding sequence and protein. An ORF model with a
+`reference_context` requires that exact context. Older catalogues without a
+pinned annotation context can bind an identical transcript in another release;
+the actual resolved context and transcript/coding/protein hashes are exported.
+No binding downloads a reference or performs liftover.
+
+`context.validate_genome(genome)` checks available metadata against an explicit
+context. Genomic alleles can use `include_annotation=False`: their coordinates
+are independent of a gene annotation release, while taxonomy, strain and
+assembly checks still apply. This does not relax ORF or RNA-product binding.
+
+`ScopedTarget` supports genes, transcripts, ORFs, proteins, ambiguous protein
+groups and peptides. A parent's gene or RNA measurement remains at its original
+resolution; this identity layer does not copy it onto every ORF. Orthology and
+equal peptide sequences do not transfer observations between species.
+
+The binder currently supports complete stopped ORFs under NCBI table 1, with
+ATG/CTG/TTG initiation. Unsupported codes and initiation codons fail explicitly.
+In particular, yeast nuclear and mitochondrial codes differ; a contig named
+`MT` never selects a code implicitly. See [NCBI's code definitions](https://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi).

orfdata-0.2.0/lint.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+set -eu
+"${PYTHON:-python}" -m ruff check orfdata tests

{orfdata-0.1.0 → orfdata-0.2.0}/orfdata/__init__.py

@@ -14,6 +14,7 @@ from .catalog import (
 )
 from .initiation_context import KOZAK_PREFERENCES, InitiationContext, annotate_initiation_context
 from .model import ORFModel, ReferenceORF
+from .reference import ReferenceContext, ScopedTarget
 from .version import __version__
 
 __all__ = [
@@ -25,6 +26,8 @@ __all__ = [
     "PeptideEvidence",
     "ORFModel",
     "ReferenceORF",
+    "ReferenceContext",
+    "ScopedTarget",
     "load_catalog",
     "UORFCatalog",
     "UORFRecord",

{orfdata-0.1.0 → orfdata-0.2.0}/orfdata/catalog.py

@@ -15,6 +15,7 @@ from typing import Optional
 
 from .initiation_context import KOZAK_PREFERENCES, InitiationContext
 from .model import ORFModel, ReferenceORF, _species
+from .reference import ReferenceContext
 from .sequence import CODONS, reverse_complement_dna
 
 EVIDENCE_METHODS = ("ribosome", "shotgun", "mhc", "hla", "ms_unclassified", "ms")
@@ -114,6 +115,7 @@ class ORFRecord:
     species: Optional[str] = None
     translation_table: int = 1
     source: str = ""
+    reference_context: Optional[ReferenceContext] = None
 
     @property
     def model(self):
@@ -133,6 +135,7 @@ class ORFRecord:
             species=self.species,
             translation_table=self.translation_table,
             source=self.source,
+            reference_context=self.reference_context,
         )
 
     @property
@@ -144,6 +147,8 @@ class ORFRecord:
         """Construct a record from the generic model and independent evidence."""
         evidence = ORFEvidence() if evidence is None else evidence
         fields = model.to_dict()
+        if model.reference_context is not None:
+            fields["reference_context"] = model.reference_context
         fields["biotype"] = fields.pop("orf_type")
         return cls(
             **fields,
@@ -152,13 +157,15 @@ class ORFRecord:
             initiation_context=initiation_context,
         )
 
-    def bind(self, transcript):
+    def bind(self, transcript, *, context=None):
         """Validate and bind this ORF to a PyEnsembl transcript without relabelling it."""
-        return ReferenceORF(self, transcript)
+        return ReferenceORF(self, transcript, context=context)
 
     def to_dict(self):
         """Return a serializable copy of this record."""
         result = asdict(self)
+        if self.reference_context is None:
+            result.pop("reference_context")
         if self.initiation_context is not None:
             result["initiation_context"] = self.initiation_context.to_dict()
         return result
@@ -348,7 +355,7 @@ class ORFCatalog:
             if r.genome_build != self.genome_build or r.strand not in ("+", "-"):
                 raise ValueError(f"Invalid assembly or strand for {r.orf_id}")
             r.model  # Validate identity and geometry, including non-upstream ORFs.
-            if (r.taxon_id, r.species) != (self.taxon_id, self.species):
+            if (r.taxon_id, _species(r.species)) != (self.taxon_id, _species(self.species)):
                 raise ValueError("Catalogue and ORF species disagree")
             if (
                 not r.coding_blocks
@@ -425,7 +432,7 @@ class ORFCatalog:
         """Return an exact source ORF ID; unknown IDs raise KeyError."""
         return self._by_id[orf_id]
 
-    def for_transcript(self, transcript, **filters):
+    def for_transcript(self, transcript, *, context=None, **filters):
         """Return validated ORFs on this transcript, with optional evidence filters.
 
         A source model that disagrees with the selected annotation raises rather
@@ -436,8 +443,11 @@ class ORFCatalog:
         species = getattr(transcript.genome, "species", None)
         if species is not None and _species(species) != _species(self.species):
             raise ValueError("Catalogue transcript species mismatch")
+        resolved = ReferenceContext.from_genome(transcript.genome, context=context)
+        if resolved.taxon_id != self.taxon_id:
+            raise ValueError("Catalogue transcript taxon mismatch")
         return tuple(
-            record.bind(transcript)
+            record.bind(transcript, context=resolved)
             for record in self.query(**filters)
             if record.transcript_id.split(".")[0] == str(transcript.id).split(".")[0]
         )
@@ -576,6 +586,8 @@ def _load_catalog(path=None, *, expected_sha256=None, resource="orf-evidence"):
             )
         row["coding_blocks"] = tuple(tuple(x) for x in row["coding_blocks"])
         row["ribosome_studies"] = tuple(row["ribosome_studies"])
+        if row.get("reference_context") is not None:
+            row["reference_context"] = ReferenceContext(**row["reference_context"])
         if row.get("initiation_context") is not None:
             context = dict(row["initiation_context"])
             assessment = context.pop("assessment", None)

{orfdata-0.1.0 → orfdata-0.2.0}/orfdata/cli.py

@@ -120,8 +120,10 @@ def run(argv=None, prog=None, *, catalog_loader=load_catalog):
         sys.stdout.write("\n")
     elif args.format == "fasta":
         for r in records:
+            reference = "" if r.reference_context is None else " reference=" + r.reference_context.key
+            scope = "" if isinstance(catalog, UORFCatalog) else f" taxon={r.taxon_id}{reference}"
             sys.stdout.write(
-                f">{r.orf_id} gene={r.gene_name} transcript={r.transcript_id} assembly={r.genome_build} biotype={r.biotype}\n{r.protein_sequence}\n"
+                f">{r.orf_id} gene={r.gene_name} transcript={r.transcript_id} assembly={r.genome_build} biotype={r.biotype}{scope}\n{r.protein_sequence}\n"
             )
     else:
         fields = (
@@ -143,12 +145,17 @@ def run(argv=None, prog=None, *, catalog_loader=load_catalog):
             "peptides_json",
             "initiation_context_json",
         )
+        scoped = not isinstance(catalog, UORFCatalog)
+        if scoped:
+            fields += ("reference_context_json",)
         writer = csv.DictWriter(sys.stdout, fieldnames=fields, delimiter="\t", lineterminator="\n")
         writer.writeheader()
         for r in records:
             row = r.to_dict()
             for field in ("coding_blocks", "ribosome_studies", "peptides", "initiation_context"):
                 row[field + "_json"] = json.dumps(row.pop(field), separators=(",", ":"))
+            if scoped:
+                row["reference_context_json"] = json.dumps(row.pop("reference_context", None), separators=(",", ":"))
             writer.writerow(row)
 
 

{orfdata-0.1.0 → orfdata-0.2.0}/orfdata/model.py

@@ -1,7 +1,10 @@
 """Reference ORF identity and its binding to an annotated transcript."""
 
+import hashlib
 from dataclasses import asdict, dataclass
+from typing import Optional
 
+from .reference import ReferenceContext, canonical_species, species_taxon
 from .sequence import CODONS
 
 
@@ -29,10 +32,21 @@ class ORFModel:
     species: str
     translation_table: int = 1
     source: str = ""
+    reference_context: Optional[ReferenceContext] = None
 
     def __post_init__(self):
         if type(self.taxon_id) is not int or self.taxon_id < 1 or not self.species:
             raise ValueError("An explicit species and positive NCBI taxon_id are required")
+        known = species_taxon(self.species)
+        if known is not None and known != self.taxon_id:
+            raise ValueError("ORF species name and taxon_id disagree")
+        if self.reference_context is not None:
+            if not isinstance(self.reference_context, ReferenceContext):
+                raise TypeError("reference_context must be a ReferenceContext")
+            if (self.reference_context.taxon_id != self.taxon_id
+                    or self.reference_context.genome_build != self.genome_build
+                    or canonical_species(self.reference_context.species) != canonical_species(self.species)):
+                raise ValueError("ORF and reference context disagree")
         if type(self.translation_table) is not int or self.translation_table < 1:
             raise ValueError("An explicit NCBI translation_table is required")
         if not all((self.orf_id, self.transcript_id, self.genome_build, self.orf_type)):
@@ -58,7 +72,10 @@ class ORFModel:
         return positions[::-1] if self.strand == "-" else positions
 
     def to_dict(self):
-        return asdict(self)
+        result = asdict(self)
+        if self.reference_context is None:
+            result.pop("reference_context")
+        return result
 
 
 def transcript_positions(transcript):
@@ -78,7 +95,7 @@ def _contig(value):
 
 
 def _species(value):
-    return str(getattr(value, "latin_name", value)).lower().replace(" ", "_")
+    return canonical_species(value)
 
 
 @dataclass(frozen=True, init=False)
@@ -96,8 +113,9 @@ class ReferenceORF:
     coding_sequence: str
     transcript_sequence: str
     genomic_positions: tuple
+    context: ReferenceContext
 
-    def __init__(self, record, transcript):
+    def __init__(self, record, transcript, *, context=None):
         model = record.model
         genome = transcript.genome
         if genome.reference_name != model.genome_build:
@@ -108,6 +126,11 @@ class ReferenceORF:
         taxon = getattr(genome, "taxon_id", None)
         if taxon is not None and taxon != model.taxon_id:
             raise ValueError("ORF transcript taxon mismatch")
+        resolved_context = ReferenceContext.from_genome(genome, context=context)
+        if resolved_context.taxon_id != model.taxon_id:
+            raise ValueError("ORF transcript taxon mismatch")
+        if model.reference_context is not None and model.reference_context.key != resolved_context.key:
+            raise ValueError("ORF transcript reference context mismatch (annotation, strain or assembly)")
         if str(transcript.id).split(".")[0] != model.transcript_id.split(".")[0]:
             raise ValueError("ORF transcript identity mismatch")
         # If the source explicitly pins a transcript version, respect it.
@@ -154,6 +177,7 @@ class ReferenceORF:
             coding_sequence=coding,
             transcript_sequence=sequence,
             genomic_positions=positions,
+            context=resolved_context,
         ).items():
             object.__setattr__(self, name, value)
 
@@ -175,6 +199,16 @@ class ReferenceORF:
         return dict(
             model=self.model.to_dict(),
             evidence=self.evidence.to_dict(),
+            reference_context=self.context.to_dict(),
+            reference_key=self.context.key,
+            sequence_fingerprints={
+                name: hashlib.sha256(sequence.encode("ascii")).hexdigest()
+                for name, sequence in (
+                    ("transcript_sha256", self.transcript_sequence),
+                    ("coding_sha256", self.coding_sequence),
+                    ("protein_sha256", self.protein_sequence),
+                )
+            },
             resolved_transcript=dict(
                 id=transcript.id,
                 version=getattr(transcript, "version", None),