orfdata 0.32.0__tar.gz → 0.34.0__tar.gz

{orfdata-0.32.0/orfdata.egg-info → orfdata-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.32.0
+Version: 0.34.0
 Summary: Reference proteomes with evidence-backed noncanonical ORFs on PyEnsembl genomes
 Author: OpenVax
 License-Expression: Apache-2.0
@@ -113,11 +113,16 @@ Human evidence is never transferred to another species. Viral proteomes can be a
 orfdata also provides [RNA, ribosome and protein measurements](https://openvax.github.io/orfdata/measurements/)
 for human, mouse, dog and yeast.
 
-`viral_orfs(reference_dna, contig="HPV16")` loads source-defined viral CDSs as
-existing RNA/ORF models, offline and qualified by exact reference sequence.
+`viral_references(host="human", group="HPV", virus_type="HPV16")` finds
+source-qualified `ViralReference` objects. Choose a stable ID with
+`viral_reference("NC_001526.4")`, then use `.dna` and `.orfs` to load its
+packaged bases and coding paths. The functional loaders remain available.
+When annotating an existing alignment, `viral_orfs(reference_dna,
+contig="HPV16")` checks its actual reference sequence before applying the same
+models.
 The first [coding reference](https://openvax.github.io/orfdata/viral/) contains
 the nine RefSeq NC_001526.4 HPV16 CDSs, with native and GDC placements;
-`viral_references()` lists the available identities and coverage. Broader
+the host association is distinct from the virus's own taxon. Broader
 imports remain in [the viral roadmap](https://github.com/openvax/orfdata/issues/91).
 
 ## Measurement datasets

{orfdata-0.32.0 → orfdata-0.34.0}/README.md

@@ -81,11 +81,16 @@ Human evidence is never transferred to another species. Viral proteomes can be a
 orfdata also provides [RNA, ribosome and protein measurements](https://openvax.github.io/orfdata/measurements/)
 for human, mouse, dog and yeast.
 
-`viral_orfs(reference_dna, contig="HPV16")` loads source-defined viral CDSs as
-existing RNA/ORF models, offline and qualified by exact reference sequence.
+`viral_references(host="human", group="HPV", virus_type="HPV16")` finds
+source-qualified `ViralReference` objects. Choose a stable ID with
+`viral_reference("NC_001526.4")`, then use `.dna` and `.orfs` to load its
+packaged bases and coding paths. The functional loaders remain available.
+When annotating an existing alignment, `viral_orfs(reference_dna,
+contig="HPV16")` checks its actual reference sequence before applying the same
+models.
 The first [coding reference](https://openvax.github.io/orfdata/viral/) contains
 the nine RefSeq NC_001526.4 HPV16 CDSs, with native and GDC placements;
-`viral_references()` lists the available identities and coverage. Broader
+the host association is distinct from the virus's own taxon. Broader
 imports remain in [the viral roadmap](https://github.com/openvax/orfdata/issues/91).
 
 ## Measurement datasets

orfdata-0.34.0/docs/viral.md

@@ -0,0 +1,77 @@
+# Viral coding references
+
+Browse the packaged viral references by host, convenience group and virus type,
+then load their source-annotated coding paths without fetching the genome:
+
+```python
+from orfdata import viral_orfs, viral_reference, viral_references
+
+references = viral_references(host="human", group="HPV", virus_type="HPV16")
+print([(r.id, r.coding_models) for r in references])
+# [('NC_001526.4', 9), ('GRCh38.d1.vd1:HPV16', 9)]
+
+ref = viral_reference("NC_001526.4")  # choose the native RefSeq placement
+reference_dna = ref.dna
+for orf in ref.orfs:
+    print(orf.orf_id, orf.gene_name, orf.coding_blocks, orf.protein_sequence)
+```
+
+The small bundled catalogue loads offline without PyEnsembl, Biopython or a
+human genome. It supplies the complete DNA for the native RefSeq NC_001526.4
+and GDC HPV16 placements; both map to the same nine source CDSs. The two DNA
+strings differ by a verified circular rotation. `viral_reference_sequence(id)`
+returns the exact forward FASTA bases, with T rather than U. A missing ID raises
+`ValueError`. `viral_references()` returns immutable `ViralReference` data
+classes; `.dna` and `.orfs` load only on access, so browsing does not copy
+genome bases or construct ORF models for every result. Choose by reference ID,
+not by result position: the native and GDC sequences have different coordinates.
+Use `ref.to_dict()` when serializing reference metadata to JSON; it does not
+load DNA or ORF models.
+
+`host` accepts a known species name such as `"human"` or an NCBI taxon ID such
+as `9606`. The released HPV16 reference objects have viral `taxon_id=333760`
+and `host_taxon_ids=(9606,)`; these are different identities. Their documented
+human host association is sourced to PaVE. `ref.group == "HPV"`
+is a convenient selection label, not a formal taxonomic rank. The
+`ref.virus_type == "HPV16"` label is the virus
+type; ICTV places it in the species *Alphapapillomavirus 9*. Each reference also
+retains the association and taxonomy source URLs. Host associations can cover
+several host taxa as new references are curated; an unlisted host is unknown,
+not proof that infection is impossible. NCBI Virus's isolation-host metadata is
+not an exhaustive host-range list. `ref.host_taxon_ids` and `ref.host_source` have the
+same meaning as in [ViralProteome](proteome.md#viral-proteomes).
+
+When annotating an existing BAM, continue to bind against its **actual** full
+alignment-reference DNA:
+
+```python
+orfs = viral_orfs(alignment_reference_dna, contig="HPV16")
+```
+
+This checks the sequence hash and its qualified coordinates. A contig name or
+related strain cannot transfer CDS annotations to mismatching DNA. It raises
+`ValueError` for an unavailable reference rather than returning an empty ORF
+set. `viral_references()` reports coverage and source checksums, and
+`viral_orfs()` returns the existing `SourceRNA`/`TranscriptORF` models.
+
+Each model uses a `SourceRNA` containing only the available CDS, including
+ordered splice blocks. Full transcript ends are not asserted. The existing
+`TranscriptORF.at()` validates its source protein and coding boundaries.
+These models have `orf_type="reference_CDS"`. Their internal kind `extra_orf`
+describes a source-defined ORF outside a loaded PyEnsembl annotation, not a
+claim that a RefSeq CDS is biologically noncanonical. No Ribo-seq or MS
+support is inferred from the reference annotation.
+
+The nine annotations are not an exhaustive HPV16 ORF catalogue. Other HPV
+types/lineages, EBV/KSHV, CMV, hepatitis viruses including HDV, HTLV-1/HIV,
+and polyomaviruses remain explicit coverage work in
+[issues #91–98](https://github.com/openvax/orfdata/issues/91).
+
+Isovar owns reconstructed sample RNA and read evidence. It can use these
+coding paths to anchor a frame on observed sequence, preserving variants
+and incomplete starts/stops. ORFdata does not assemble sample RNA, replace
+missing bases, infer protein abundance or establish viral tumor causality.
+RNA and coding-reference matches are not direct protein evidence.
+
+Source attribution and rebuilding instructions are in
+[`orfdata/data/viral/NOTICE.md`](https://github.com/openvax/orfdata/blob/main/orfdata/data/viral/NOTICE.md).

{orfdata-0.32.0 → orfdata-0.34.0}/orfdata/__init__.py

@@ -70,10 +70,21 @@ from .rna import IRES, ProteinProduct, RNAFeature, SourceRNA, products_from_unip
 from .search_reference import SearchMembership, SearchReference, SearchReferenceSpec, SearchSequence
 from .sequence import GeneticCode, genetic_code
 from .version import __version__
-from .viral import viral_orfs, viral_references
+from .viral import (
+    ViralProduct,
+    ViralReference,
+    viral_orfs,
+    viral_reference,
+    viral_reference_sequence,
+    viral_references,
+)
 
 __all__ = [
+    "ViralProduct",
+    "ViralReference",
     "viral_orfs",
+    "viral_reference",
+    "viral_reference_sequence",
     "viral_references",
     "__version__",
     "Proteome",

{orfdata-0.32.0 → orfdata-0.34.0}/orfdata/data/viral/NOTICE.md

@@ -13,6 +13,17 @@ The catalogue contains nine source-annotated CDSs, including two joined paths.
 It does not claim all reported HPV16 ORFs or complete transcript models.
 RNA support does not establish translation or protein expression.
 
+The released catalogue also contains the full forward reference bases for both
+qualified placements. HPV16's documented human host is sourced from PaVE's
+HPV16REF record (`/host="Human (Homo sapiens)"`):
+https://pave.niaid.nih.gov/locus_viewer?feature_id=HPV16_E7&seq_id=HPV16REF .
+This host association applies to HPV16 as a type, not to all papillomaviruses,
+and does not claim an exhaustive host range. ICTV lists HPV16 in the species
+*Alphapapillomavirus 9*:
+https://ictv.global/report/chapter/papillomaviridae/taxonomy/papillomaviridae .
+These are distinct from the RefSeq DNA/CDS source and the GDC coordinate
+placement. Consulted 2026-10-16.
+
 Native DNA MD5: `08d2b3849496d12cc45fd4df713d5c2f`.
 GDC GRCh38.d1.vd1 HPV16 DNA MD5: `f2463721818c29998ef5ab917e6df74a`.
 GDC DNA is the source circle rotated by 864 bases. Both placements retain

orfdata-0.34.0/orfdata/version.py

@@ -0,0 +1 @@
+__version__ = "0.34.0"

orfdata-0.34.0/orfdata/viral.py

@@ -0,0 +1,242 @@
+"""Offline, sequence-qualified viral CDSs bound to the existing RNA/ORF models."""
+
+import gzip
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from functools import cached_property, lru_cache
+from importlib.resources import files
+
+from .model import TranscriptORF
+from .reference import ReferenceContext, species_taxon
+from .rna import SourceRNA
+
+_CATALOG_SHA256 = "aca0c72948d4cda896d14b32203981bce4759e0c70212c05dca6f3d0e16ed4b4"
+_COMPLEMENT = str.maketrans("ACGT", "TGCA")
+
+
+@dataclass(frozen=True)
+class ViralProduct:
+    """One source-labelled protein product in a viral coding reference."""
+
+    protein_id: str
+    gene: str
+    product: str
+
+
+@dataclass(frozen=True)
+class ViralReference:
+    """One exact, bundled viral reference and its source-defined coding paths.
+
+    ``dna`` and ``orfs`` load only when accessed. Host associations describe
+    documented hosts, not an exhaustive host range.
+    """
+
+    id: str
+    species: str
+    taxon_id: int
+    host_taxon_ids: tuple[int, ...]
+    host_source: str
+    group: str
+    virus_type: str
+    ictv_species: str
+    taxonomy_source: str
+    length: int
+    sequence_md5: str
+    sequence_sha256: str
+    native_to_reference_rotation: int
+    source_accession: str
+    source_sha256: str
+    source_url: str
+    coding_models: int
+    products: tuple[ViralProduct, ...]
+    scope: str
+    catalogue_sha256: str
+
+    @cached_property
+    def dna(self):
+        """Complete, checksum-verified forward FASTA bases for this reference."""
+        return viral_reference_sequence(self.id)
+
+    @cached_property
+    def orfs(self):
+        """Source-defined CDS paths placed on this exact reference."""
+        return viral_orfs(reference_id=self.id)
+
+    def to_dict(self):
+        """Return serializable metadata without loading DNA or ORF models."""
+        row = asdict(self)
+        row["host_taxon_ids"] = list(self.host_taxon_ids)
+        row["products"] = list(row["products"])
+        row["virus"] = dict(group=row.pop("group"), type=row.pop("virus_type"),
+                            ictv_species=row.pop("ictv_species"),
+                            taxonomy_source=row.pop("taxonomy_source"))
+        row["source"] = dict(accession=row.pop("source_accession"),
+                             sha256=row.pop("source_sha256"), url=row.pop("source_url"))
+        return row
+
+
+@lru_cache(maxsize=1)
+def _catalog():
+    raw = files("orfdata").joinpath("data/viral/hpv16-refseq-CDS.json.gz").read_bytes()
+    if hashlib.sha256(raw).hexdigest() != _CATALOG_SHA256:
+        raise ValueError("Bundled viral CDS catalogue checksum mismatch")
+    data = json.loads(gzip.decompress(raw))
+    if data["schema"] != "orfdata.viral_cds.v2":
+        raise ValueError("Unsupported viral CDS catalogue schema")
+    return data
+
+
+def _reference(row, data):
+    virus = row["virus"]
+    source = row["source"]
+    return ViralReference(
+        id=row["id"], species=row["species"], taxon_id=row["taxon_id"],
+        host_taxon_ids=tuple(row["host_taxon_ids"]), host_source=row["host_source"],
+        group=virus["group"], virus_type=virus["type"],
+        ictv_species=virus["ictv_species"], taxonomy_source=virus["taxonomy_source"],
+        length=row["length"], sequence_md5=row["sequence_md5"],
+        sequence_sha256=row["sequence_sha256"],
+        native_to_reference_rotation=row["native_to_reference_rotation"],
+        source_accession=source["accession"], source_sha256=source["sha256"],
+        source_url=source["url"], coding_models=len(row["coding_blocks"]),
+        products=tuple(ViralProduct(cds["protein_id"], cds["gene"], cds["product"])
+                       for cds in data["cds"]),
+        scope=data["scope"], catalogue_sha256=_CATALOG_SHA256)
+
+
+def viral_references(*, host=None, group=None, virus_type=None):
+    """Find released viral references by documented host, group and type.
+
+    Parameters
+    ----------
+    host : str or int, optional
+        Known host name such as ``"human"``, or an NCBI host taxon ID. A host
+        association is source-attributed and is not a complete host range.
+    group : str, optional
+        Convenience group label, such as ``"HPV"``; not a taxonomy rank.
+    virus_type : str, optional
+        Named virus type, such as ``"HPV16"``; distinct from ICTV species.
+
+    Returns
+    -------
+    tuple of ViralReference
+        Exact sequence hashes, source/host pins, virus identity and coverage.
+        A listed reference is not a complete transcript or exhaustive ORF
+        catalogue. DNA and ORFs load only when their properties are accessed.
+    """
+    if host is None:
+        host_taxon_id = None
+    elif type(host) is int and host > 0:
+        host_taxon_id = host
+    elif isinstance(host, str) and species_taxon(host) is not None:
+        host_taxon_id = species_taxon(host)
+    else:
+        raise ValueError("host must be a known species name or positive NCBI taxon ID")
+    if any(value is not None and (not isinstance(value, str) or not value)
+           for value in (group, virus_type)):
+        raise ValueError("group and virus_type must be nonempty names")
+    data = _catalog()
+    return tuple(_reference(row, data)
+                 for row in data["references"]
+                 if (host_taxon_id is None or host_taxon_id in row["host_taxon_ids"])
+                 and (group is None or row["virus"]["group"].casefold() == group.casefold())
+                 and (virus_type is None or row["virus"]["type"].casefold() == virus_type.casefold()))
+
+
+def viral_reference(reference_id):
+    """Return one exact viral reference by stable ID, without positional selection."""
+    data = _catalog()
+    matches = [row for row in data["references"] if row["id"] == reference_id]
+    if len(matches) != 1:
+        raise ValueError("No unique released viral reference ID matches this name")
+    return _reference(matches[0], data)
+
+
+def viral_reference_sequence(reference_id):
+    """Return bundled, checksum-verified reference bases for one exact ID.
+
+    The sequence uses the forward FASTA alphabet (T rather than U) and may
+    represent a virus whose biological genome is RNA. No network is accessed.
+    """
+    matches = [row for row in _catalog()["references"] if row["id"] == reference_id]
+    if len(matches) != 1:
+        raise ValueError("No unique released viral reference ID matches this name")
+    row = matches[0]
+    sequence = row["reference_sequence"]
+    if (len(sequence) != row["length"] or
+            hashlib.sha256(sequence.encode("ascii")).hexdigest() != row["sequence_sha256"]):
+        raise ValueError("Bundled viral reference sequence checksum mismatch")
+    return sequence
+
+
+def viral_orfs(reference_sequence=None, *, reference_id=None, contig=None):
+    """Load source-defined CDSs for one exactly matching viral DNA reference.
+
+    Parameters
+    ----------
+    reference_sequence : str, optional
+        Complete forward reference DNA from an alignment. This checks actual
+        sequence identity rather than transferring annotation by contig name.
+    reference_id : str, optional
+        Bundled reference ID from ``viral_references()``. Use this to load the
+        reference ORFs without obtaining DNA separately. Supply exactly one
+        of ``reference_sequence`` or ``reference_id``.
+    contig : str, optional
+        The caller's name for this exact DNA in an alignment reference. The
+        original versioned source identity remains on every ORF's context.
+
+    Returns
+    -------
+    tuple of TranscriptORF
+        Source CDS fragments represented with SourceRNA and TranscriptORF.at.
+        Their genomic blocks are 1-based inclusive and their RNA sequence is
+        only the available CDS. Full transcript boundaries are not asserted.
+        No ribosome, peptide or sample protein-expression evidence is inferred.
+
+    Raises
+    ------
+    ValueError
+        No released coding reference matches, or a source model fails to bind
+        and translate exactly. Discovery is available through viral_references.
+    """
+    if (reference_sequence is None) == (reference_id is None):
+        raise ValueError("Provide exactly one of reference_sequence or reference_id")
+    sequence = (viral_reference_sequence(reference_id) if reference_id is not None
+                else str(reference_sequence).upper())
+    fingerprint = hashlib.sha256(sequence.encode("ascii")).hexdigest()
+    data = _catalog()
+    matches = [row for row in data["references"] if row["sequence_sha256"] == fingerprint
+               and row["length"] == len(sequence)]
+    if len(matches) != 1:
+        raise ValueError("No unique released viral coding reference matches this DNA; "
+                         "inspect viral_references() for available sequence identities")
+    reference = matches[0]
+    source = reference["source"]
+    label = contig if contig is not None else reference["id"]
+    if not isinstance(label, str) or not label:
+        raise ValueError("contig must be a nonempty name")
+    context = ReferenceContext(
+        taxon_id=reference["taxon_id"], species=reference["species"],
+        genome_build=reference["id"], annotation_name="NCBI RefSeq",
+        annotation_version=source["accession"], sequence_sha256=fingerprint,
+        source_sha256=source["sha256"])
+    result = []
+    for cds in data["cds"]:
+        protein_id = cds["protein_id"]
+        blocks = reference["coding_blocks"][protein_id]
+        coding = "".join(sequence[a - 1:b] if cds["strand"] == "+" else
+                         sequence[a - 1:b].translate(_COMPLEMENT)[::-1] for a, b in blocks)
+        if cds["phase"] != 0:
+            raise ValueError(f"Unsupported partial source codon: {protein_id}")
+        rna = SourceRNA(
+            id=f"{source['accession']}:CDS:{protein_id}", sequence=coding, reference=context,
+            source=f"NCBI RefSeq {source['accession']}", contig=label, strand=cds["strand"],
+            exons=blocks, gene_name=cds["gene"], biotype="source_CDS_fragment")
+        orf = TranscriptORF.at(rna, 0, orf_id=protein_id, source=rna.source,
+                               protein=cds["protein_sequence"], translation_table=cds["translation_table"],
+                               orf_type="reference_CDS", start_complete=cds["start_complete"])
+        if orf.coding_sequence != coding or orf.stop_complete != cds["stop_complete"]:
+            raise ValueError(f"Source coding boundaries do not translate exactly: {protein_id}")
+        result.append(orf)
+    return tuple(result)

{orfdata-0.32.0 → orfdata-0.34.0/orfdata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.32.0
+Version: 0.34.0
 Summary: Reference proteomes with evidence-backed noncanonical ORFs on PyEnsembl genomes
 Author: OpenVax
 License-Expression: Apache-2.0
@@ -113,11 +113,16 @@ Human evidence is never transferred to another species. Viral proteomes can be a
 orfdata also provides [RNA, ribosome and protein measurements](https://openvax.github.io/orfdata/measurements/)
 for human, mouse, dog and yeast.
 
-`viral_orfs(reference_dna, contig="HPV16")` loads source-defined viral CDSs as
-existing RNA/ORF models, offline and qualified by exact reference sequence.
+`viral_references(host="human", group="HPV", virus_type="HPV16")` finds
+source-qualified `ViralReference` objects. Choose a stable ID with
+`viral_reference("NC_001526.4")`, then use `.dna` and `.orfs` to load its
+packaged bases and coding paths. The functional loaders remain available.
+When annotating an existing alignment, `viral_orfs(reference_dna,
+contig="HPV16")` checks its actual reference sequence before applying the same
+models.
 The first [coding reference](https://openvax.github.io/orfdata/viral/) contains
 the nine RefSeq NC_001526.4 HPV16 CDSs, with native and GDC placements;
-`viral_references()` lists the available identities and coverage. Broader
+the host association is distinct from the virus's own taxon. Broader
 imports remain in [the viral roadmap](https://github.com/openvax/orfdata/issues/91).
 
 ## Measurement datasets

orfdata-0.34.0/tests/test_viral.py

@@ -0,0 +1,199 @@
+"""Qualify real, versioned viral CDS paths independently of sample assembly."""
+
+import gzip
+import hashlib
+import io
+import json
+from copy import deepcopy
+from dataclasses import FrozenInstanceError
+from importlib.resources import files
+from pathlib import Path
+
+import pytest
+from Bio import SeqIO
+
+import orfdata.viral as viral_module
+from orfdata import (
+    SourceRNA,
+    ViralReference,
+    viral_orfs,
+    viral_reference,
+    viral_reference_sequence,
+    viral_references,
+)
+from tools.build_hpv16_cds import build
+
+FIXTURE = Path(__file__).parent / "data/viral/NC_001526.4.gb.gz"
+EXPECTED = {
+    "YP_009268708.1": 92, "NP_041327.2": 649, "NP_041328.1": 365,
+    "NP_041330.2": 83, "NP_041331.2": 473, "NP_041332.2": 505,
+    "NP_041325.1": 158, "YP_009268707.1": 50, "NP_041326.1": 98,
+}
+
+
+@pytest.fixture
+def source():
+    raw = gzip.decompress(FIXTURE.read_bytes())
+    assert hashlib.sha256(raw).hexdigest() == "282be442f226cc809fefbda616ac136b8d20dfde23fad09558f3f653a3de96a4"
+    return raw, SeqIO.read(io.StringIO(raw.decode()), "genbank")
+
+
+def test_catalogue_rebuilds_from_the_pinned_public_annotation(source):
+    raw, _ = source
+    packaged = json.loads(gzip.decompress(files("orfdata").joinpath(
+        "data/viral/hpv16-refseq-CDS.json.gz").read_bytes()))
+    assert build(raw) == packaged
+    assert len(packaged["cds"]) == 9
+
+
+def test_native_source_paths_match_all_nine_source_proteins(source):
+    _, record = source
+    orfs = viral_orfs(str(record.seq))
+    definitions = {f.qualifiers["protein_id"][0]: f for f in record.features if f.type == "CDS"}
+    assert {orf.orf_id: len(orf.protein_sequence) for orf in orfs} == EXPECTED
+    for orf in orfs:
+        feature = definitions[orf.orf_id]
+        assert isinstance(orf.transcript, SourceRNA)
+        assert orf.transcript.biotype == "source_CDS_fragment"
+        assert orf.transcript.genome is None
+        assert orf.protein_sequence == feature.qualifiers["translation"][0]
+        assert orf.coding_sequence == str(feature.extract(record.seq))
+        assert orf.start_complete and orf.stop_complete
+        assert orf.context.annotation_version == "NC_001526.4"
+        assert orf.context.taxon_id == 333760
+        assert not orf.evidence.has_evidence("ms")
+        assert not orf.evidence.has_evidence("ribosome")
+
+
+def test_gdc_rotation_is_exact_and_retains_spliced_coding_positions(source):
+    _, record = source
+    native = str(record.seq)
+    gdc = native[-864:] + native[:-864]
+    assert hashlib.md5(gdc.encode()).hexdigest() == "f2463721818c29998ef5ab917e6df74a"
+    orfs = {orf.orf_id: orf for orf in viral_orfs(gdc, contig="HPV16")}
+    assert orfs["YP_009268708.1"].coding_blocks == ((865, 880), (3358, 3620))
+    assert orfs["YP_009268707.1"].coding_blocks == ((83, 226), (409, 417))
+    assert orfs["NP_041326.1"].coding_blocks == ((562, 858),)
+    for orf in orfs.values():
+        assert orf.transcript.contig == "HPV16"
+        assert orf.context.genome_build == "GRCh38.d1.vd1:HPV16"
+        assert orf.protein_sequence == next(o.protein_sequence for o in viral_orfs(native)
+                                            if o.orf_id == orf.orf_id)
+
+
+def test_mutated_same_name_reference_and_partial_dna_are_not_qualified(source):
+    _, record = source
+    native = str(record.seq)
+    changed = ("A" if native[0] != "A" else "C") + native[1:]
+    for sequence in (changed, native[1:], native[::-1]):
+        with pytest.raises(ValueError, match="No unique released"):
+            viral_orfs(sequence, contig="HPV16")
+
+
+def test_discovery_is_offline_and_reference_objects_are_immutable(source, monkeypatch):
+    _, record = source
+    references = viral_references()
+    assert all(isinstance(ref, ViralReference) for ref in references)
+    assert {ref.id for ref in references} == {"NC_001526.4", "GRCh38.d1.vd1:HPV16"}
+    assert all(ref.coding_models == 9 for ref in references)
+    assert all(ref.catalogue_sha256 and ref.source_sha256 for ref in references)
+    native = viral_reference("NC_001526.4")
+    assert native == next(ref for ref in references if ref.id == native.id)
+    with pytest.raises(FrozenInstanceError):
+        native.source_accession = "changed"
+    with pytest.raises(AttributeError):
+        native.host_taxon_ids.clear()
+    assert viral_reference("NC_001526.4").source_accession == "NC_001526.4"
+    assert native.host_taxon_ids == (9606,)
+    payload = native.to_dict()
+    assert payload["virus"]["type"] == "HPV16"
+    assert payload["source"]["accession"] == "NC_001526.4"
+    assert payload["host_taxon_ids"] == [9606]
+    assert len(payload["products"]) == 9
+    assert "dna" not in payload and "orfs" not in payload
+    json.dumps(payload)
+    payload["host_taxon_ids"].clear()
+    assert native.host_taxon_ids == (9606,)
+    with monkeypatch.context() as patch:
+        patch.setattr(viral_module, "viral_orfs", lambda **kwargs: 1 / 0)
+        patch.setattr(viral_module, "viral_reference_sequence", lambda reference_id: 1 / 0)
+        assert viral_references(host="human") == references
+    assert viral_orfs(str(record.seq))[0].context.annotation_version == "NC_001526.4"
+
+
+def test_host_group_and_type_select_exact_references_with_distinct_taxa():
+    references = viral_references(host="human", group="HPV", virus_type="HPV16")
+    assert {ref.id for ref in references} == {"NC_001526.4", "GRCh38.d1.vd1:HPV16"}
+    assert viral_references(host=9606, group="hpv", virus_type="hpv16") == references
+    assert viral_references(host="mouse") == viral_references(host=10090) == ()
+    assert viral_references(host="human", virus_type="HPV18") == ()
+    for ref in references:
+        assert ref.taxon_id == 333760 and ref.host_taxon_ids == (9606,)
+        assert "PaVE HPV16REF" in ref.host_source
+        assert ref.ictv_species == "Alphapapillomavirus 9"
+        assert ref.group == "HPV" and ref.virus_type == "HPV16"
+        assert ref.taxonomy_source.startswith("https://ictv.global/")
+    for invalid in ("not_a_host", 0, True):
+        with pytest.raises(ValueError, match="host"):
+            viral_references(host=invalid)
+
+
+def test_explicit_multiple_host_associations_can_select_one_reference_from_each_host(monkeypatch):
+    # Synthetic metadata checks selection only; it makes no HPV16 mouse-host claim.
+    catalog = deepcopy(viral_module._catalog())
+    catalog["references"][0]["host_taxon_ids"].append(10090)
+    catalog["references"][0]["host_source"] = "synthetic multiple-host fixture"
+    monkeypatch.setattr(viral_module, "_catalog", lambda: catalog)
+    assert {ref.id for ref in viral_references(host="human")} == {
+        "NC_001526.4", "GRCh38.d1.vd1:HPV16"}
+    mouse, = viral_references(host="mouse", virus_type="HPV16")
+    assert mouse.id == "NC_001526.4" and mouse.taxon_id == 333760
+
+
+def test_bundled_reference_sequences_and_named_orfs_match_both_source_placements(source):
+    _, record = source
+    native = str(record.seq)
+    gdc = native[-864:] + native[:-864]
+    for reference_id, expected in (("NC_001526.4", native),
+                                   ("GRCh38.d1.vd1:HPV16", gdc)):
+        ref = viral_reference(reference_id)
+        sequence = ref.dna
+        assert sequence == expected
+        assert ref.dna is sequence
+        assert sequence == viral_reference_sequence(reference_id)
+        assert hashlib.sha256(sequence.encode()).hexdigest() == ref.sequence_sha256
+        assert {orf.orf_id for orf in ref.orfs} == {product.protein_id for product in ref.products}
+        assert ref.orfs is ref.orfs
+        assert {orf.transcript.contig for orf in ref.orfs} == {reference_id}
+        by_name = viral_orfs(reference_id=reference_id, contig="selected")
+        by_dna = viral_orfs(sequence, contig="selected")
+        assert [(o.orf_id, o.coding_blocks, o.protein_sequence) for o in by_name] == [
+            (o.orf_id, o.coding_blocks, o.protein_sequence) for o in by_dna]
+        assert {o.transcript.contig for o in by_name} == {"selected"}
+    with pytest.raises(ValueError, match="reference ID"):
+        viral_reference_sequence("unknown")
+    with pytest.raises(ValueError, match="reference ID"):
+        viral_reference("unknown")
+    with pytest.raises(ValueError, match="exactly one"):
+        viral_orfs()
+    with pytest.raises(ValueError, match="exactly one"):
+        viral_orfs(native, reference_id="NC_001526.4")
+
+
+def test_corrupt_packaged_catalogue_fails_before_returning_models(monkeypatch):
+    import orfdata.viral as module
+
+    class CorruptResource:
+        def joinpath(self, path):
+            return self
+
+        def read_bytes(self):
+            return b"corrupt catalogue"
+
+    module._catalog.cache_clear()
+    try:
+        monkeypatch.setattr(module, "files", lambda name: CorruptResource())
+        with pytest.raises(ValueError, match="checksum mismatch"):
+            viral_references()
+    finally:
+        module._catalog.cache_clear()