orfdata 0.42.0__tar.gz → 0.42.2__tar.gz

{orfdata-0.42.0/orfdata.egg-info → orfdata-0.42.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.42.0
+Version: 0.42.2
 Summary: Reference proteomes with evidence-backed noncanonical ORFs on PyEnsembl genomes
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.42.0 → orfdata-0.42.2}/docs/catalogs.md

@@ -17,7 +17,8 @@ original PyEnsembl transcript through `ReferenceORF`. To use several catalogues
 for one species together, see
 [merging catalogues](proteome.md#merging-catalogues).
 
-The packaged registry builds each catalogue from its sources' own files:
+The packaged registry supplies catalogues as pinned downloads or builds from
+their sources' own files:
 
 | Species | Catalogues | ORFs |
 | --- | --- | ---: |
@@ -78,11 +79,11 @@ existing standalone local-file workflow.
 
 ```sh
 pip install "orfdata"
-orfdata setup --species mouse --accept-terms   # Three catalogues and the chains; about 130 MB of sources
+orfdata setup --species mouse --accept-terms   # Three catalogues and the chains
 ```
 
-`orfdata setup` builds each registered mouse catalogue from its pinned sources
-and downloads the chain files (`--accept-terms` for UCSC's non-commercial
+`orfdata setup` downloads the published Chang et al. catalogue, builds the other
+registered mouse catalogues from their pinned sources, and downloads the chain files (`--accept-terms` for UCSC's non-commercial
 GRCm38/GRCm39 chains). It prints what it did with each: built, downloaded,
 already installed, repaired or skipped. If one fails, the rest are still
 installed and it exits with status 1, naming each failure; in Python,
@@ -115,6 +116,14 @@ least two callers find it in a library, in at least two libraries, starting at
 ATG, CTG, GTG or TTG. Its types are uORF (8,294), lncORF (3,576), uoORF
 (1,950), iORF (1,749), dORF (741) and doORF (174).
 
+- **Download.** `orfdata data fetch ncorf-mammals-mouse` installs the
+  checksum-pinned 2.22 MB catalogue. `orfdata data path ncorf-mammals-mouse`
+  returns its local path for offline use. Python callers use
+  `fetch_data("ncorf-mammals-mouse")` and `CatalogRegistry().open("ncorf-mammals-mouse")`.
+  The [data release](https://github.com/openvax/orfdata/releases/tag/data-ncorf-mammals-mouse-1)
+  includes the manifest, source access terms and acceptance receipt.
+  `orfdata catalogs build ncorf-mammals-mouse` still explicitly rebuilds from
+  the original inputs; `catalogs query ncorf-mammals-mouse --built` selects that result.
 - **Sources.** The authors' BED and protein FASTA (MIT, pinned commit), the
   paper's Table S3 (CC BY 4.0) and Ensembl 107's GTF; about 40 MB.
 - **Coding paths.** The BED garbles multi-exon block sizes, so each ORF's

{orfdata-0.42.0 → orfdata-0.42.2}/docs/reference.md

@@ -84,6 +84,18 @@ explicitly supplied RNA, checking its identity, reference, coding path and
 sequence fingerprints. It preserves source evidence and optional catalogue
 provenance.
 
+Every `to_dict()` export includes `resolved_transcript.contig` and
+`resolved_transcript.strand`, including annotated CDSs and `TranscriptORF.at`
+placements whose `model` and `record` are `null`. These fields describe the RNA
+actually carrying the ORF, preserving its contig spelling and `+`/`-` strand;
+they do not substitute the original source model's locus. Unknown `SourceRNA`
+locus values remain `null`, so unknown orientation is explicit. Saved results can be
+interpreted without reloading a reference sequence.
+
+These are additive fields in `orfdata.transcript_orf.v1` as of 0.42.1. The reader
+accepts older v1 exports where they are absent. If a field is present, including
+an explicit `null`, it must match the supplied carrier RNA during replay.
+
 ```python
 from orfdata import extra_orfs
 

{orfdata-0.42.0 → orfdata-0.42.2}/orfdata/data/catalogs.json

@@ -190,10 +190,16 @@
           "schema": "orfdata.catalog-manifest.v1"
         },
         "distribution": {
-          "access_terms": "Built locally from the pinned source files: the authors' ncORF files (MIT), the paper's Table S3 (CC BY 4.0) and Ensembl 107's GTF. Cite Chang et al., eLife 2025 (doi:10.7554/eLife.109128).",
+          "access_terms": "Redistributed from the pinned authors' ncORF files (MIT), Table S3 (CC BY 4.0) and Ensembl 107 GTF (unrestricted). Includes source provenance and one unresolved row. Cite Chang et al., eLife 2025 (doi:10.7554/eLife.109128).",
           "redistributable": true
         },
-        "assets": {}
+        "assets": {
+          "catalog.json.gz": {
+            "url": "https://github.com/openvax/orfdata/releases/download/data-ncorf-mammals-mouse-1/catalog.json.gz",
+            "sha256": "255f1d089b1eaa88a0bed53006c05ec78350626659461086fa11164947f151f1",
+            "size": 2219659
+          }
+        }
       }
     },
     "priority": 20

{orfdata-0.42.0 → orfdata-0.42.2}/orfdata/model.py

@@ -800,6 +800,11 @@ class TranscriptORF:
         return self._source_gene[1] if self.record is None else self.model.gene_name
 
     def to_dict(self):
+        """Export this placement, including the carrier RNA's contig and strand.
+
+        ``resolved_transcript`` always contains both locus fields; an unmapped
+        source RNA keeps its unknown values as ``None``.
+        """
         transcript = self.transcript
         genome = transcript.genome
         species = getattr(genome, "species", None)
@@ -825,6 +830,8 @@ class TranscriptORF:
             },
             resolved_transcript=dict(
                 id=transcript.id,
+                contig=transcript.contig,
+                strand=transcript.strand,
                 version=getattr(transcript, "version", None),
                 release=getattr(genome, "release", None),
                 genome_build=self.context.genome_build,
@@ -862,6 +869,8 @@ class TranscriptORF:
         The complete RNA sequence, reference context, coordinates and protein
         fingerprints must agree. Annotation and source-defined placements keep
         ``record=None``; no catalogue observation is fabricated during replay.
+        Legacy v1 exports without carrier locus fields remain readable; when
+        present, those fields must match the explicitly supplied RNA.
         """
         from .catalog import ORFEvidence, _record
 
@@ -880,6 +889,9 @@ class TranscriptORF:
         if (transcript.id != resolved["id"]
                 or getattr(transcript, "version", None) != resolved["version"]):
             raise ValueError("Transcript ORF snapshot transcript identity mismatch")
+        for field in ("contig", "strand"):
+            if field in resolved and resolved[field] != getattr(transcript, field):
+                raise ValueError(f"Transcript ORF snapshot carrier {field} mismatch")
         if value.get("record") is not None:
             restored = cls(_record(value["record"]), transcript, context=context, any_transcript=True)
         else:
@@ -934,7 +946,13 @@ class TranscriptORF:
             elif ((restored.start_complete and origin != 0)
                   or (restored.stop_complete and origin != len(coding) - 3 * (len(restored.protein_sequence) + 1))):
                 raise ValueError("Transcript ORF snapshot coding phase contradicts its annotated boundaries")
-        if json.dumps(restored.to_dict(), sort_keys=True) != json.dumps(value, sort_keys=True):
+        exported = restored.to_dict()
+        # Before 0.42.1, v1 snapshots did not include the carrier's locus.
+        # Only absent fields are optional: an explicit null still must agree.
+        for field in ("contig", "strand"):
+            if field not in resolved:
+                exported["resolved_transcript"].pop(field)
+        if json.dumps(exported, sort_keys=True) != json.dumps(value, sort_keys=True):
             raise ValueError("Transcript ORF snapshot does not round-trip to its source definition")
         return restored
 

orfdata-0.42.2/orfdata/version.py

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

{orfdata-0.42.0 → orfdata-0.42.2/orfdata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.42.0
+Version: 0.42.2
 Summary: Reference proteomes with evidence-backed noncanonical ORFs on PyEnsembl genomes
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.42.0 → orfdata-0.42.2}/orfdata.egg-info/SOURCES.txt

@@ -188,6 +188,7 @@ tests/test_riborf.py
 tests/test_search_reference.py
 tests/test_selectors.py
 tests/test_storage.py
+tests/test_transcript_orf_serialization.py
 tests/test_uorf_catalog.py
 tests/test_verify_dog_dataset.py
 tests/test_viral.py
@@ -311,6 +312,7 @@ tests/data/references/homo_sapiens.json
 tests/data/references/mitochondrial.json
 tests/data/references/mus_musculus.json
 tests/data/references/saccharomyces_cerevisiae.json
+tests/data/references/transcript_orf_v1_0.42.0.json
 tests/data/references/uniprot_literature.json
 tests/data/regions/NOTICE.md
 tests/data/regions/ingolia.json

orfdata-0.42.2/tests/data/references/transcript_orf_v1_0.42.0.json

@@ -0,0 +1,71 @@
+{
+  "schema": "orfdata.transcript_orf.v1",
+  "kind": "extra_orf",
+  "orf_id": "legacy",
+  "equivalent_ids": [],
+  "source_transcript_id": "snapshot-fixture",
+  "on_source_transcript": true,
+  "model": null,
+  "record": null,
+  "evidence": {
+    "ribosome_studies": [],
+    "peptides": []
+  },
+  "reference_context": {
+    "taxon_id": 9606,
+    "species": "human",
+    "genome_build": "GRCh38",
+    "annotation_name": "synthetic",
+    "annotation_version": "1",
+    "assembly_accession": null,
+    "strain": null,
+    "strain_taxon_id": null,
+    "sequence_sha256": null,
+    "taxonomy_version": "ncbi-2026-10-12",
+    "source_sha256": null
+  },
+  "reference_key": "ref:2cd293bb014bdfd762ba5d24f5a4f7c9eb6ee91b1ba0cbd2585b60b667491fec",
+  "sequence_fingerprints": {
+    "transcript_sha256": "c5fc760ddfbe43faada474e3d39342b30a0542dd9e4583b655cec28b53867498",
+    "coding_sha256": "c5fc760ddfbe43faada474e3d39342b30a0542dd9e4583b655cec28b53867498",
+    "protein_sha256": "b2690faaaa9351ecb43b60145db79e38151129eaa426b9529f1705b2dd5168bc"
+  },
+  "resolved_transcript": {
+    "id": "snapshot-fixture",
+    "version": null,
+    "release": null,
+    "genome_build": "GRCh38",
+    "species": null,
+    "biotype": null,
+    "topology": "linear"
+  },
+  "source": "synthetic",
+  "source_gene_id": null,
+  "source_gene_name": null,
+  "orf_type": null,
+  "coding_sequence": "ATGAAATAA",
+  "protein_sequence": "MK",
+  "translation_table": 1,
+  "coding_phase": 0,
+  "coding_origin": 0,
+  "start": 0,
+  "end": 9,
+  "segments": [
+    [
+      0,
+      9
+    ]
+  ],
+  "cdna_interval": [
+    0,
+    9
+  ],
+  "coding_blocks": [],
+  "start_complete": true,
+  "stop_complete": true,
+  "start_codon": "ATG",
+  "stop_codon": "TAA",
+  "decoded_stop_codons": [],
+  "subcodon_introns": [],
+  "coordinates": "0-based-half-open-cdna;1-based-inclusive-genome"
+}

orfdata-0.42.2/tests/test_transcript_orf_serialization.py

@@ -0,0 +1,128 @@
+"""Carrier loci survive export; synthetic mappings are not biological observations."""
+
+import json
+from pathlib import Path
+
+import pytest
+from test_orf_cases import genome as genome
+
+from orfdata import ORFModel, ORFRecord, ReferenceContext, SourceRNA, TranscriptORF
+
+
+class Carrier:
+    """A second RNA with the same pinned sequence/path and a contig alias."""
+
+    def __init__(self, transcript):
+        self.original = transcript
+        self.id = "carrier-" + transcript.id
+        self.versioned_id = self.id + "." + str(transcript.version)
+        self.contig = "chr" + transcript.contig
+        self.gene_id = "carrier-gene"
+        self.gene_name = "CARRIER"
+
+    def __getattr__(self, name):
+        return getattr(self.original, name)
+
+
+@pytest.fixture(params=("ENST00000644866", "ENST00000395826"), ids=("plus", "minus"))
+def placement(request, genome):
+    transcript = genome.transcript_by_id(request.param)
+    annotated = TranscriptORF.from_annotation(transcript)
+    record = ORFRecord.from_model(ORFModel(
+        "synthetic-record", transcript.id, transcript.gene_id, transcript.gene_name,
+        transcript.contig, transcript.strand, annotated.coding_blocks,
+        annotated.protein_sequence, "synthetic", "GRCh38", 9606, "homo_sapiens",
+        source="synthetic"))
+    return transcript, annotated, record
+
+
+@pytest.mark.parametrize("route", ("at", "annotated", "mapped_annotation", "record", "mapped_record"))
+def test_every_constructor_exports_the_actual_carrier_locus(placement, route):
+    transcript, annotated, record = placement
+    carrier = Carrier(transcript) if route.startswith("mapped_") else transcript
+    if route == "at":
+        orf = TranscriptORF.at(carrier, annotated.start, orf_id="synthetic-at",
+                               source="synthetic", protein=annotated.protein_sequence)
+    elif route in ("annotated", "mapped_annotation"):
+        orf = TranscriptORF.from_annotation(transcript, on=carrier)
+    else:
+        orf = TranscriptORF(record, carrier, any_transcript=route == "mapped_record")
+    snapshot = json.loads(json.dumps(orf.to_dict()))
+    resolved = snapshot["resolved_transcript"]
+    assert resolved["id"] == carrier.id
+    assert resolved["contig"] == carrier.contig
+    assert resolved["strand"] == carrier.strand
+    if route.startswith("mapped_"):
+        assert not snapshot["on_source_transcript"]
+        assert snapshot["source_transcript_id"] != resolved["id"]
+    if route == "mapped_record":
+        assert snapshot["model"]["contig"] != resolved["contig"]
+    if route in ("at", "annotated", "mapped_annotation"):
+        assert snapshot["model"] is None and snapshot["record"] is None
+    restored = TranscriptORF.from_dict(snapshot, carrier)
+    assert json.loads(json.dumps(restored.to_dict())) == snapshot
+    # Earlier v1 exports omitted both fields for every construction path.
+    legacy = json.loads(json.dumps(snapshot))
+    del legacy["resolved_transcript"]["strand"]
+    del legacy["resolved_transcript"]["contig"]
+    assert TranscriptORF.from_dict(legacy, carrier).to_dict() == orf.to_dict()
+    assert "strand" not in legacy["resolved_transcript"]  # Replay does not rewrite its input.
+
+
+def source_rna(**locus):
+    return SourceRNA("snapshot-fixture", "ATGAAATAA",
+                     ReferenceContext(9606, "human", "GRCh38", "synthetic", "1"),
+                     "synthetic", **locus)
+
+
+@pytest.mark.parametrize("strand", (None, "+", "-"))
+def test_source_rna_locus_is_explicit_even_when_unknown(strand):
+    locus = {} if strand is None else dict(contig="2", strand=strand, exons=((100, 108),))
+    rna = source_rna(**locus)
+    orf = TranscriptORF.at(rna, 0, orf_id="source-rna", source="synthetic")
+    snapshot = json.loads(json.dumps(orf.to_dict()))
+    assert snapshot["resolved_transcript"]["strand"] == strand
+    assert snapshot["resolved_transcript"]["contig"] == (None if strand is None else "2")
+    assert TranscriptORF.from_dict(snapshot, rna).to_dict() == orf.to_dict()
+
+
+@pytest.mark.parametrize("field,wrong", (("strand", "-"), ("strand", None),
+                                         ("contig", "other"), ("contig", None)))
+@pytest.mark.parametrize("legacy_other_field", (False, True))
+def test_conflicting_carrier_locus_is_rejected_before_reading_sequence(field, wrong, legacy_other_field):
+    rna = source_rna(contig="2", strand="+", exons=((100, 108),))
+    snapshot = TranscriptORF.at(rna, 0, orf_id="source-rna", source="synthetic").to_dict()
+    snapshot["resolved_transcript"][field] = wrong
+    if legacy_other_field:
+        del snapshot["resolved_transcript"]["contig" if field == "strand" else "strand"]
+
+    class UnavailableSequence:
+        def __getattr__(self, name):
+            if name == "sequence":
+                pytest.fail("A contradictory carrier locus must fail before reading RNA bases")
+            return getattr(rna, name)
+
+    with pytest.raises(ValueError, match=f"carrier {field} mismatch"):
+        TranscriptORF.from_dict(snapshot, UnavailableSequence())
+
+
+@pytest.mark.parametrize("field,wrong", (("strand", "+"), ("contig", "2")))
+def test_snapshot_cannot_assign_a_locus_to_an_unmapped_source_rna(field, wrong):
+    rna = source_rna()
+    snapshot = TranscriptORF.at(rna, 0, orf_id="unmapped", source="synthetic").to_dict()
+    snapshot["resolved_transcript"][field] = wrong
+    with pytest.raises(ValueError, match=f"carrier {field} mismatch"):
+        TranscriptORF.from_dict(snapshot, rna)
+
+
+def test_published_042_snapshot_remains_readable():
+    # Frozen using the published 0.42.0 wheel, before carrier locus fields existed.
+    path = Path(__file__).parent / "data/references/transcript_orf_v1_0.42.0.json"
+    snapshot = json.loads(path.read_text())
+    restored = TranscriptORF.from_dict(snapshot, source_rna())
+    assert restored.protein_sequence == "MK" and restored.record is None
+    assert restored.to_dict()["resolved_transcript"]["strand"] is None
+    assert restored.to_dict()["resolved_transcript"]["contig"] is None
+    snapshot["sequence_fingerprints"]["protein_sha256"] = "0" * 64
+    with pytest.raises(ValueError, match="does not round-trip"):
+        TranscriptORF.from_dict(snapshot, source_rna())

orfdata-0.42.0/orfdata/version.py

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