orfdata 0.1.0__py3-none-any.whl

orfdata/cli.py

@@ -0,0 +1,156 @@
+"""Query and export the offline ORF evidence reference."""
+
+import argparse
+import csv
+import json
+import re
+import sys
+
+from .catalog import EVIDENCE_METHODS, UORFCatalog, load_catalog
+
+
+def run(argv=None, prog=None, *, catalog_loader=load_catalog):
+    """Export reference records as JSON, TSV or FASTA."""
+    parser = argparse.ArgumentParser(description=__doc__, prog=prog)
+    parser.add_argument("--catalog", help="Use a compatible local JSON/JSON.gz catalogue")
+    parser.add_argument("--gene", help="Exact gene symbol or Ensembl gene ID")
+    parser.add_argument("--transcript", help="Exact source transcript ID (unversioned)")
+    parser.add_argument("--orf-id", help="Exact catalogue ORF identifier")
+    parser.add_argument("--evidence", choices=EVIDENCE_METHODS)
+    parser.add_argument(
+        "--require-unique", action="store_true", help="Require one protein mapping in the MS source"
+    )
+    parser.add_argument(
+        "--require-reviewed",
+        action="store_true",
+        help="Require convincing reviewed spectra (benchmark scores 4-5)",
+    )
+    parser.add_argument("--biotype", help="Source ORF class, e.g. uORF, lncRNA, intORF, dORF")
+    parser.add_argument("--region", help="1-based inclusive interval: chr7:66205483-66205522")
+    parser.add_argument(
+        "--position", help="Map a 1-based variant position: chr7:66205483 (JSON only)"
+    )
+    parser.add_argument(
+        "--include-initiation-context",
+        action="store_true",
+        help="Include spliced start flanks in locus lookup",
+    )
+    parser.add_argument("--ref", help="Forward-genomic SNV REF; requires --alt and --position")
+    parser.add_argument("--alt", help="Forward-genomic SNV ALT; compare initiation contexts")
+    parser.add_argument(
+        "--genome-build", help="Required for genomic queries; packaged data use GRCh38"
+    )
+    parser.add_argument("--format", choices=("json", "tsv", "fasta"), default="json")
+    args = parser.parse_args(argv)
+    if args.region and args.position:
+        parser.error("Choose --region or --position")
+    if args.position and args.format != "json":
+        parser.error("--position requires --format json")
+    if (args.ref is not None or args.alt is not None) and (
+        not args.ref or not args.alt or not args.position
+    ):
+        parser.error("SNV annotation requires --position, --ref and --alt")
+    if args.ref and (
+        args.ref not in ("A", "C", "G", "T")
+        or args.alt not in ("A", "C", "G", "T")
+        or args.ref == args.alt
+    ):
+        parser.error("Provide distinct single-base forward-genomic REF and ALT")
+    try:
+        catalog = catalog_loader(args.catalog)
+        options = {
+            "gene": args.gene,
+            "transcript_id": args.transcript,
+            "evidence": args.evidence,
+            "require_unique": args.require_unique,
+            "require_reviewed": args.require_reviewed,
+            "biotype": args.biotype,
+            "genome_build": args.genome_build,
+            "include_initiation_context": args.include_initiation_context or bool(args.ref),
+        }
+        locus = args.region or args.position
+        if locus:
+            pattern = r"([^:]+):([0-9]+)-([0-9]+)" if args.region else r"([^:]+):([0-9]+)"
+            match = re.fullmatch(pattern, locus)
+            if match is None:
+                raise ValueError(f"Invalid locus: {locus}")
+            start = int(match.group(2))
+            options.update(
+                contig=match.group(1),
+                start=start,
+                end=int(match.group(3)) if args.region else start,
+            )
+        records = catalog.query(**options)
+        if args.orf_id:
+            catalog.get(args.orf_id)  # A misspelled ID is an error, not empty evidence.
+            records = tuple(r for r in records if r.orf_id == args.orf_id)
+        initiation_annotations = None
+        if args.position:
+            initiation_annotations = []
+            for r in records:
+                annotation = r.map_initiation_position(
+                    options["start"], genome_build=args.genome_build
+                )
+                if args.ref and annotation is not None:
+                    annotation = r.annotate_initiation_snv(
+                        options["start"], args.ref, args.alt, genome_build=args.genome_build
+                    )
+                initiation_annotations.append(annotation)
+            if args.ref and not any(a is not None for a in initiation_annotations):
+                raise ValueError(
+                    "No mapped initiation context covers the SNV; coding consequences require full transcript reconstruction"
+                )
+    except (ValueError, KeyError, OSError) as exc:
+        parser.error(str(exc))
+    if args.format == "json":
+        output = {
+            "schema": "isovar.uorf_query.v1"
+            if isinstance(catalog, UORFCatalog)
+            else "orfdata.query.v1",
+            "metadata": catalog.metadata,
+            "records": [r.to_dict() for r in records],
+        }
+        if args.position:
+            output["position_annotations"] = [
+                r.map_genomic_position(options["start"], genome_build=args.genome_build)
+                for r in records
+            ]
+            output["initiation_annotations"] = initiation_annotations
+        json.dump(output, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    elif args.format == "fasta":
+        for r in records:
+            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"
+            )
+    else:
+        fields = (
+            "orf_id",
+            "gene_id",
+            "gene_name",
+            "transcript_id",
+            "genome_build",
+            "taxon_id",
+            "species",
+            "translation_table",
+            "source",
+            "contig",
+            "strand",
+            "biotype",
+            "protein_sequence",
+            "coding_blocks_json",
+            "ribosome_studies_json",
+            "peptides_json",
+            "initiation_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=(",", ":"))
+            writer.writerow(row)
+
+
+if __name__ == "__main__":
+    run()

orfdata/data/orf-evidence/AUTHOR-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leron Kok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orfdata/data/orf-evidence/NOTICE.txt

@@ -0,0 +1,32 @@
+orfdata ncORF evidence catalogue, dataset version 2026-10-11.1.
+
+The orfdata API and builder (derived from Isovar) are Apache-2.0. Source data retain their own licenses.
+
+GENCODE Phase I models and legacy MS annotations, plus HLA mapping/count data:
+Copyright (c) 2025 Leron Kok. MIT license, included as AUTHOR-LICENSE.txt.
+VanHeeschLab/deutsch_kok_et_al_2024, commit
+b65ae0c09a53e9efe083d806d617581e6139bdde.
+https://github.com/VanHeeschLab/deutsch_kok_et_al_2024
+Associated studies: Mudge et al. 2022, DOI 10.1038/s41587-022-01369-0;
+Deutsch et al. 2026, DOI 10.1038/s41586-026-10459-x.
+
+Community spectrum review input:
+Aaron Wacholder and the community assessment authors, archived dataset version 1.
+https://doi.org/10.6084/m9.figshare.30131869.v1
+License: Creative Commons Attribution 4.0 International (CC BY 4.0).
+https://creativecommons.org/licenses/by/4.0/
+Associated study: Wacholder et al. 2026, DOI 10.1038/s41467-025-68002-x.
+
+Changes: included all complete stopped source ncORF classes; normalized coordinates and source metadata;
+joined sequence-compatible peptide observations; retained individual reviews,
+source attribution and unknown mapping counts; calculated peptide intervals and
+conservative review labels. Full original article text and supplementary
+curation tables are not redistributed. Source URLs, SHA256 pins, evidence scope
+and exclusions are in catalog metadata and manifest.json.
+
+Initiation-context sequence: Ensembl release 101, human GRCh38 GTF/cDNA/ncRNA.
+Ensembl-generated data are available without restriction:
+https://www.ensembl.org/info/about/legal/disclaimer.html
+Changes: exact ORF path/protein validation; extracted transcript-oriented start
+flanks and genomic placements; added partial-context/positional Kozak priors.
+Sequence priors are not measurements of translation or protein abundance.

orfdata/data/orf-evidence/manifest.json

@@ -0,0 +1,30 @@
+{
+  "catalog_sha256": "06bc0bf3f81c25a7356f71a38581ff5704c05dcb75752454bc1ca75075ab8c09",
+  "dataset_version": "2026-10-11.1",
+  "excluded_assignments": [],
+  "schema": "orfdata.manifest.v1",
+  "source_sha256": {
+    "author-hla-counts.json": "b1e8e79e74e90d205224cc86663ebf9d64ed97cf0e0290cd86117756ee46a4b6",
+    "author-hla-mappings.tsv": "7f97f4ea675ac6abc97217c865019d73135358f448533ad8d98c9479fee9fb8f",
+    "ensembl101.cdna.fa.gz": "519cb4398f7a7904531a0eaaf16a8252f0487f101e00087f6316017bd51a1093",
+    "ensembl101.gtf.gz": "6f63da87a7f2f7b5e6940f7e2bd9dd2e7aee37494430e6ac7274f7ef8dc214ba",
+    "ensembl101.ncrna.fa.gz": "6bbf091adb1214942b6f258aa830393b27ad7cc49f8ee2fe18260a7b46a0cc88",
+    "filtered_peptides.tar.bz2": "a97d73b08b4ee7376a064f9fee3480b3d73639ebe0bd238a6dd0099df6a9e30c",
+    "media-4_with_dot_products.csv": "9e2cbb54765f8a9886cdcbf0bdfefa772f4623f54291add2bf3c47c26b17250f",
+    "ncorf_list.xlsx": "ca2e2f9389052c62f48ec6f81d53ca88c64152edb5940e556813d4a7bf1e6c62",
+    "peptide_sample_msrun_counts.tar.bz2": "290658de32de2579d17f0b75c3fcc39b4d50c5e6ce1ceea9ce9f411ccc8a98ba"
+  },
+  "statistics": {
+    "excluded_legacy_assignments": 0,
+    "hla_orfs": 1881,
+    "initiation_context_complete": 7041,
+    "initiation_context_partial": 223,
+    "initiation_context_unavailable": 0,
+    "ms_orfs": 2186,
+    "peptides": 4315,
+    "records": 7264,
+    "reviewed_ms_orfs": 44,
+    "ribosome_orfs": 7264,
+    "shotgun_orfs": 73
+  }
+}

orfdata/data/uorf-evidence/AUTHOR-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leron Kok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orfdata/data/uorf-evidence/NOTICE.txt

@@ -0,0 +1,32 @@
+Isovar uORF evidence catalogue, dataset version 2026-10-08.2.
+
+The Isovar API and builder are Apache-2.0. Source data retain their own licenses.
+
+GENCODE Phase I models and legacy MS annotations, plus HLA mapping/count data:
+Copyright (c) 2025 Leron Kok. MIT license, included as AUTHOR-LICENSE.txt.
+VanHeeschLab/deutsch_kok_et_al_2024, commit
+b65ae0c09a53e9efe083d806d617581e6139bdde.
+https://github.com/VanHeeschLab/deutsch_kok_et_al_2024
+Associated studies: Mudge et al. 2022, DOI 10.1038/s41587-022-01369-0;
+Deutsch et al. 2026, DOI 10.1038/s41586-026-10459-x.
+
+Community spectrum review input:
+Aaron Wacholder and the community assessment authors, archived dataset version 1.
+https://doi.org/10.6084/m9.figshare.30131869.v1
+License: Creative Commons Attribution 4.0 International (CC BY 4.0).
+https://creativecommons.org/licenses/by/4.0/
+Associated study: Wacholder et al. 2026, DOI 10.1038/s41467-025-68002-x.
+
+Changes: selected uORF/uoORF models; normalized coordinates and source metadata;
+joined sequence-compatible peptide observations; retained individual reviews,
+source attribution and unknown mapping counts; calculated peptide intervals and
+conservative review labels. Full original article text and supplementary
+curation tables are not redistributed. Source URLs, SHA256 pins, evidence scope
+and exclusions are in catalog metadata and manifest.json.
+
+Initiation-context sequence: Ensembl release 101, human GRCh38 GTF/cDNA.
+Ensembl-generated data are available without restriction:
+https://www.ensembl.org/info/about/legal/disclaimer.html
+Changes: exact ORF path/protein validation; extracted transcript-oriented start
+flanks and genomic placements; added partial-context/positional Kozak priors.
+Sequence priors are not measurements of translation or protein abundance.

orfdata/data/uorf-evidence/manifest.json

@@ -0,0 +1,29 @@
+{
+  "catalog_sha256": "408d79631214f3872b1fb886bf2aa117228d4ae6179d59113af8ce336244bedd",
+  "dataset_version": "2026-10-08.2",
+  "excluded_assignments": [],
+  "schema": "isovar.uorf_manifest.v1",
+  "source_sha256": {
+    "author-hla-counts.json": "b1e8e79e74e90d205224cc86663ebf9d64ed97cf0e0290cd86117756ee46a4b6",
+    "author-hla-mappings.tsv": "7f97f4ea675ac6abc97217c865019d73135358f448533ad8d98c9479fee9fb8f",
+    "ensembl101.cdna.fa.gz": "519cb4398f7a7904531a0eaaf16a8252f0487f101e00087f6316017bd51a1093",
+    "ensembl101.gtf.gz": "6f63da87a7f2f7b5e6940f7e2bd9dd2e7aee37494430e6ac7274f7ef8dc214ba",
+    "filtered_peptides.tar.bz2": "a97d73b08b4ee7376a064f9fee3480b3d73639ebe0bd238a6dd0099df6a9e30c",
+    "media-4_with_dot_products.csv": "9e2cbb54765f8a9886cdcbf0bdfefa772f4623f54291add2bf3c47c26b17250f",
+    "ncorf_list.xlsx": "ca2e2f9389052c62f48ec6f81d53ca88c64152edb5940e556813d4a7bf1e6c62",
+    "peptide_sample_msrun_counts.tar.bz2": "290658de32de2579d17f0b75c3fcc39b4d50c5e6ce1ceea9ce9f411ccc8a98ba"
+  },
+  "statistics": {
+    "excluded_legacy_assignments": 0,
+    "hla_orfs": 1059,
+    "initiation_context_complete": 3598,
+    "initiation_context_partial": 173,
+    "initiation_context_unavailable": 0,
+    "ms_orfs": 1219,
+    "peptides": 2414,
+    "records": 3771,
+    "reviewed_ms_orfs": 16,
+    "ribosome_orfs": 3771,
+    "shotgun_orfs": 31
+  }
+}

orfdata/initiation_context.py

@@ -0,0 +1,178 @@
+"""Loose, positional initiation priors, separate from translation observations."""
+
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+# A of ATG is +1; there is no position zero. The outer GCC is optional.
+KOZAK_PREFERENCES = {
+    -9: "G",
+    -8: "C",
+    -7: "C",
+    -6: "G",
+    -5: "C",
+    -4: "C",
+    -3: "AG",
+    -2: "C",
+    -1: "C",
+    4: "G",
+}
+
+
+@dataclass(frozen=True)
+class InitiationContext:
+    """Transcript-oriented bases surrounding a proposed initiation codon.
+
+    Missing flanks are empty/short strings, never inferred from protein
+    sequence or intronic genomic adjacency. Ambiguous bases remain unknown.
+    ``genomic_positions`` are optional 1-based placements in sequence order.
+    ``start_offset`` is measured from the supplied transcript sequence; it
+    is not a verified cap distance unless ``five_prime_complete`` is True.
+    """
+
+    upstream: str
+    start_codon: str
+    downstream: str
+    genomic_positions: tuple = ()
+    source: Optional[str] = None
+    source_transcript_id: Optional[str] = None
+    start_offset: Optional[int] = None
+    five_prime_complete: Optional[bool] = None
+    unavailable_reason: Optional[str] = None
+
+    def __post_init__(self):
+        sequence = self.upstream + self.start_codon + self.downstream
+        if (
+            len(self.upstream) > 9
+            or len(self.downstream) > 6
+            or any(b not in "ACGTRYSWKMBDHVN" for b in sequence)
+            or (len(self.start_codon) != 3 and not self.unavailable_reason)
+        ):
+            raise ValueError("Invalid initiation-context sequence")
+        if self.unavailable_reason and sequence:
+            raise ValueError("Unavailable context must not carry unvalidated sequence")
+        if self.genomic_positions and (
+            len(self.genomic_positions) != len(sequence)
+            or any(type(p) is not int or p < 1 for p in self.genomic_positions)
+            or len(set(self.genomic_positions)) != len(self.genomic_positions)
+        ):
+            raise ValueError("Invalid initiation-context genomic placements")
+        if self.start_offset is not None and (
+            type(self.start_offset) is not int or self.start_offset < len(self.upstream)
+        ):
+            raise ValueError("Invalid initiation-context start offset")
+        if self.five_prime_complete is not None and type(self.five_prime_complete) is not bool:
+            raise ValueError("five_prime_complete must be True, False or None")
+
+    @property
+    def relative_positions(self):
+        """Kozak numbering for every retained base, without a position zero."""
+        return tuple(range(-len(self.upstream), 0)) + tuple(
+            range(1, len(self.start_codon) + len(self.downstream) + 1)
+        )
+
+    @property
+    def assessment(self):
+        """Return observed preferences, missingness and a qualitative prior.
+
+        Match counts are descriptive, not calibrated probabilities or a
+        translation threshold. A mismatch never establishes no initiation.
+        Non-ATG starts are retained without predicting their efficiency.
+        """
+        sequence = self.upstream + self.start_codon + self.downstream
+        bases = dict(zip(self.relative_positions, sequence))
+        positions = []
+        for position, preferred in KOZAK_PREFERENCES.items():
+            base = bases.get(position)
+            positions.append(
+                {
+                    "position": position,
+                    "base": base,
+                    "preferred": preferred,
+                    "matches": base in preferred if base is not None and base in "ACGT" else None,
+                }
+            )
+        key = [p for p in positions if p["position"] in (-3, 4)]
+        observed = sum(p["matches"] is not None for p in key)
+        matches = sum(p["matches"] is True for p in key)
+        if self.unavailable_reason:
+            status, interpretation = "unavailable", "sequence_context_unavailable"
+        else:
+            status = (
+                "complete"
+                if len(self.upstream) == 9
+                and len(self.downstream) == 6
+                and all(b in "ACGT" for b in sequence)
+                else "partial"
+            )
+            interpretation = (
+                "both_key_preferences_present"
+                if matches == 2
+                else "one_key_preference_present"
+                if matches == 1
+                else "no_observed_key_preference; initiation_still_possible"
+                if observed
+                else "key_positions_unknown; initiation_unresolved"
+            )
+        codon = self.start_codon
+        atg = None if len(codon) != 3 or any(b not in "ACGT" for b in codon) else codon == "ATG"
+        boundary = (
+            (
+                "at_verified_5prime_end; conventional_scanning_uncertain"
+                if self.five_prime_complete
+                else "at_supplied_sequence_start; true_5prime_end_unverified"
+            )
+            if self.start_offset == 0
+            else None
+        )
+        return {
+            "policy": "isovar.initiation_context.v1",
+            "status": status,
+            "display": self.upstream + "[" + codon + "]" + self.downstream if sequence else None,
+            "is_atg": atg,
+            "kozak_positions": positions,
+            "key_positions_observed": observed,
+            "key_positions_matching": matches,
+            "interpretation": interpretation,
+            "sequence_boundary_note": boundary,
+            "cap_distance_nt": self.start_offset if self.five_prime_complete is True else None,
+            "translation_evidence": "sequence_prior_only; not_observed",
+        }
+
+    def to_dict(self):
+        """Serialize raw sequence/provenance and the reproducible assessment."""
+        result = asdict(self)
+        result["assessment"] = self.assessment
+        return result
+
+
+def annotate_initiation_context(sequence, start, *, five_prime_complete=None):
+    """Extract up to 9 upstream and 6 downstream bases from a supplied RNA.
+
+    Parameters
+    ----------
+    sequence : str
+        Transcript-oriented sequence, accepting RNA U or DNA T and IUPAC
+        ambiguity. It need not be a complete mature mRNA.
+    start : int
+        Zero-based offset of a complete proposed initiation codon. ATG is
+        not required; retained non-ATG codons receive no efficiency claim.
+    five_prime_complete : bool or None
+        Caller evidence that the sequence begins at the biological 5-prime
+        end. The default leaves the cap distance unknown.
+
+    Returns
+    -------
+    InitiationContext
+        Observed flanks and a loose positional assessment. Partial contexts
+        and ATG at the first three bases are retained, never filtered out.
+    """
+    sequence = sequence.upper().replace("U", "T")
+    if type(start) is not int or not 0 <= start <= len(sequence) - 3:
+        raise ValueError("start must identify a complete codon in the sequence")
+    return InitiationContext(
+        sequence[max(0, start - 9) : start],
+        sequence[start : start + 3],
+        sequence[start + 3 : start + 9],
+        start_offset=start,
+        five_prime_complete=five_prime_complete,
+    )