orfdata 0.16.0__tar.gz → 0.17.0__tar.gz

{orfdata-0.16.0/orfdata.egg-info → orfdata-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.16.0
+Version: 0.17.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.16.0 → orfdata-0.17.0}/docs/reference.md

@@ -12,7 +12,7 @@ PyEnsembl. Binding uses a transcript you have already loaded.
 ORF. Each has:
 
 - `model`: source identity, ORF type, coordinates, species and protein sequence.
-- `evidence`: ribosome observations and peptide-level MS observations.
+- `evidence`: ribosome observations, peptide-level MS and native aggregate support.
 - `transcript`: the original PyEnsembl transcript, including its original biotype.
 - `coding_sequence` and `protein_sequence`: checked against that transcript.
 
@@ -46,10 +46,44 @@ 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.
 
+Some sources provide only aggregate support counts. `EvidenceSummary` keeps the
+native metric, definition, value, source/release, source checksum and explicitly
+scoped entity. For example, [OpenProt's native metrics](https://api.openprot.org/api/2.0/SC/downloads/yeast_s288c-openprot-2_2-altprots+isoforms-min_2_pep-R64-1-1.106.tsv.readme.html)
+include an MS score that sums study-specific unique-peptide
+counts; it is neither global peptide uniqueness nor protein abundance. Its
+translation score counts studies with significant translation detection.
+`None` means unknown and remains distinct from a reported zero.
+
+Positive summaries in `orf.evidence.summaries` can satisfy general evidence
+queries. To require actual peptide records or named ribosome studies, use:
+
+```python
+orf.evidence.has_evidence("ms", require_resolved=True)
+catalog.query(evidence="ribosome", require_resolved=True)
+```
+
+The CLI uses `--evidence ms --require-resolved`. Uniqueness and review filters
+always require resolved peptide observations. Summaries never create peptide
+sequences, residue coverage, retained variant peptides or mutant-translation
+evidence. Their protein checksum and species/reference checks prevent attaching
+them to a different protein or incompatible source context.
+
+A sequence-level summary may have several transcript assignments. Those records
+share the summary's `key`; `catalog.evidence_summaries` returns each native metric
+once and rejects conflicting facts for the same identity. Native accession
+aliases must be resolved explicitly by the source adapter. Counts from different
+metrics and sources are not summed, and a later peptide-resolved snapshot is not
+an additional independent experiment merely because it has more detail.
+
+This API includes source-backed OpenProt human, mouse and yeast test slices.
+It does not yet publish those species' OpenProt ORF catalogues; coordinate and
+sequence qualification remains tracked in [#18](https://github.com/openvax/orfdata/issues/18).
+
 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.
+Source evidence stays at its declared ORF or protein-sequence scope. It is not
+automatically evidence for another isoform, a mutant protein, a fusion or
+another species.
 
 ## Variants and RNA products
 

{orfdata-0.16.0 → orfdata-0.17.0}/orfdata/__init__.py

@@ -14,6 +14,7 @@ from .catalog import (
 )
 from .dataset import QuantitativeDataset
 from .datasets import DatasetRegistry, build_dataset
+from .evidence_summary import EvidenceSummary
 from .initiation_context import KOZAK_PREFERENCES, InitiationContext, annotate_initiation_context
 from .measurements import (
     Assay,
@@ -44,6 +45,7 @@ __all__ = [
     "ORFCatalog",
     "ORFRecord",
     "ORFEvidence",
+    "EvidenceSummary",
     "PeptideEvidence",
     "ORFModel",
     "ReferenceORF",

{orfdata-0.16.0 → orfdata-0.17.0}/orfdata/catalog.py

@@ -13,6 +13,7 @@ from importlib.resources import files
 from pathlib import Path
 from typing import Optional
 
+from .evidence_summary import EvidenceSummary, unique_summaries
 from .initiation_context import KOZAK_PREFERENCES, InitiationContext
 from .model import ORFModel, ReferenceORF, _species
 from .reference import ReferenceContext
@@ -73,25 +74,41 @@ class ORFEvidence:
 
     ribosome_studies: tuple = ()
     peptides: tuple = ()
+    summaries: tuple = ()
+
+    def __post_init__(self):
+        object.__setattr__(self, "summaries", unique_summaries(self.summaries))
 
     def to_dict(self):
-        return asdict(self)
+        result = asdict(self)
+        if not self.summaries:
+            result.pop("summaries")
+        return result
 
-    def has_evidence(self, method, *, require_unique=False, require_reviewed=False):
-        """Select reference observations by assay, without clinical promotion."""
+    def has_evidence(self, method, *, require_unique=False, require_reviewed=False, require_resolved=False):
+        """Select reported support, or require named studies/resolved peptides.
+
+        Aggregate counts never satisfy uniqueness or spectrum-review filters.
+        No selection establishes evidence for a modified protein product.
+        """
         if method not in EVIDENCE_METHODS:
             raise ValueError(f"Unknown evidence method: {method}")
         if method == "ribosome":
             if require_unique or require_reviewed:
                 raise ValueError("MS filters do not apply to ribosome evidence")
-            return bool(self.ribosome_studies)
-        return any(
+            return bool(self.ribosome_studies) or (not require_resolved and any(
+                s.method == "ribosome" and s.is_supporting for s in self.summaries))
+        resolved = any(
             (method == "ms" or p.method == method or (method == "mhc" and p.method == "hla"))
             and p.is_supporting
             and (not require_unique or p.unique_in_source)
             and (not require_reviewed or p.quality == "reviewed_support")
             for p in self.peptides
         )
+        return resolved or (not (require_resolved or require_unique or require_reviewed) and any(
+            (method == "ms" and s.method != "ribosome"
+             or s.method == method or method == "mhc" and s.method == "hla")
+            and s.is_supporting for s in self.summaries))
 
 
 @dataclass(frozen=True)
@@ -116,6 +133,14 @@ class ORFRecord:
     translation_table: int = 1
     source: str = ""
     reference_context: Optional[ReferenceContext] = None
+    summaries: tuple = ()
+
+    def __post_init__(self):
+        object.__setattr__(self, "summaries", unique_summaries(self.summaries))
+        if self.summaries:
+            model = self.model
+            for summary in self.summaries:
+                summary.validate_orf(model)
 
     @property
     def model(self):
@@ -140,7 +165,7 @@ class ORFRecord:
 
     @property
     def evidence(self):
-        return ORFEvidence(self.ribosome_studies, self.peptides)
+        return ORFEvidence(self.ribosome_studies, self.peptides, self.summaries)
 
     @classmethod
     def from_model(cls, model, evidence=None, *, initiation_context=None):
@@ -154,6 +179,7 @@ class ORFRecord:
             **fields,
             ribosome_studies=evidence.ribosome_studies,
             peptides=evidence.peptides,
+            summaries=evidence.summaries,
             initiation_context=initiation_context,
         )
 
@@ -164,6 +190,8 @@ class ORFRecord:
     def to_dict(self):
         """Return a serializable copy of this record."""
         result = asdict(self)
+        if not self.summaries:
+            result.pop("summaries")
         if self.reference_context is None:
             result.pop("reference_context")
         if self.initiation_context is not None:
@@ -284,9 +312,10 @@ class ORFRecord:
             translation_change="not_measured",
         )
 
-    def has_evidence(self, method, *, require_unique=False, require_reviewed=False):
+    def has_evidence(self, method, *, require_unique=False, require_reviewed=False, require_resolved=False):
         return self.evidence.has_evidence(
-            method, require_unique=require_unique, require_reviewed=require_reviewed
+            method, require_unique=require_unique, require_reviewed=require_reviewed,
+            require_resolved=require_resolved,
         )
 
     def _coding_offset(self, position):
@@ -423,6 +452,13 @@ class ORFCatalog:
                     ):
                         raise ValueError(f"Peptide sequence does not match {r.orf_id}")
 
+        self._evidence_summaries = unique_summaries(s for r in self.records for s in r.summaries)
+
+    @property
+    def evidence_summaries(self):
+        """Distinct source counts, without multiplying transcript assignments."""
+        return self._evidence_summaries
+
     @property
     def metadata(self):
         """Return a copy of dataset version, sources, scope and provenance."""
@@ -472,6 +508,7 @@ class ORFCatalog:
         evidence=None,
         require_unique=False,
         require_reviewed=False,
+        require_resolved=False,
         biotype=None,
         include_initiation_context=False,
     ):
@@ -483,6 +520,8 @@ class ORFCatalog:
         are unversioned identifiers. Empty results do not prove no translation.
         ``require_unique`` means unique within the evidence source's mapping
         scope, not unique in every normal human proteome.
+        ``require_resolved`` excludes aggregate-only support: MS needs a peptide
+        observation and ribosome evidence needs a named study.
         ``include_initiation_context`` also intersects placed spliced start
         flanks, for example an upstream Kozak SNV. The default remains coding
         blocks only. It does not include introns between context bases.
@@ -504,6 +543,8 @@ class ORFCatalog:
             raise ValueError("require_unique applies to MS evidence only")
         if require_reviewed and evidence not in EVIDENCE_METHODS[1:]:
             raise ValueError("require_reviewed applies to MS evidence only")
+        if require_resolved and evidence is None:
+            raise ValueError("require_resolved requires an evidence method")
 
         return tuple(
             r
@@ -530,7 +571,8 @@ class ORFCatalog:
             and (
                 evidence is None
                 or r.has_evidence(
-                    evidence, require_unique=require_unique, require_reviewed=require_reviewed
+                    evidence, require_unique=require_unique, require_reviewed=require_reviewed,
+                    require_resolved=require_resolved,
                 )
             )
         )
@@ -604,6 +646,7 @@ def _load_catalog(path=None, *, expected_sha256=None, resource="orf-evidence"):
             p["spectrum_ids"] = tuple(p.get("spectrum_ids", ()))
             peptides.append(PeptideEvidence(**p))
         row["peptides"] = tuple(peptides)
+        row["summaries"] = tuple(EvidenceSummary.from_dict(s) for s in row.get("summaries", ()))
         records.append(ORFRecord(**row))
     return ORFCatalog(records, metadata)
 

{orfdata-0.16.0 → orfdata-0.17.0}/orfdata/cli.py

@@ -24,6 +24,8 @@ def run(argv=None, prog=None, *, catalog_loader=load_catalog):
     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-resolved", action="store_true",
+                        help="Require resolved peptides or named ribosome studies; exclude aggregate-only support")
     parser.add_argument(
         "--require-unique", action="store_true", help="Require one protein mapping in the MS source"
     )
@@ -69,6 +71,7 @@ def run(argv=None, prog=None, *, catalog_loader=load_catalog):
             "gene": args.gene,
             "transcript_id": args.transcript,
             "evidence": args.evidence,
+            "require_resolved": args.require_resolved,
             "require_unique": args.require_unique,
             "require_reviewed": args.require_reviewed,
             "biotype": args.biotype,

orfdata-0.17.0/orfdata/evidence_summary.py

@@ -0,0 +1,108 @@
+"""Source-reported support counts, separate from resolved observations."""
+
+import hashlib
+import re
+from dataclasses import asdict, dataclass, replace
+from typing import Optional
+from urllib.parse import urlparse
+
+from .reference import ReferenceContext, ScopedTarget
+
+
+@dataclass(frozen=True)
+class EvidenceSummary:
+    """One native count of experimental support for an exact source entity.
+
+    ``value`` is a nonnegative integer or unknown (None), never a confidence
+    score or abundance. ``definition`` preserves the source's counting rules;
+    a sum of unique peptides per study is not a globally unique peptide count.
+    A protein-sequence summary can support several transcript assignments,
+    which retain the same ``key`` instead of multiplying independent evidence.
+    """
+
+    source: str
+    release: str
+    target: ScopedTarget
+    protein_sha256: str
+    method: str
+    metric: str
+    value: Optional[int]
+    definition: str
+    scope: str
+    source_url: str
+    source_sha256: str
+
+    def __post_init__(self):
+        if not isinstance(self.target, ScopedTarget):
+            raise TypeError("Evidence summaries require a ScopedTarget")
+        if self.method not in ("ribosome", "shotgun", "mhc", "hla", "ms_unclassified", "ms"):
+            raise ValueError("Unknown summary evidence method")
+        if self.method == "hla" and self.target.reference.taxon_id != 9606:
+            raise ValueError("Use mhc for non-human immunopeptidomics evidence")
+        if self.scope not in ("protein_sequence", "orf") or self.target.kind != {
+            "protein_sequence": "protein", "orf": "orf"
+        }.get(self.scope):
+            raise ValueError("Evidence summary scope and target kind disagree")
+        if any(not isinstance(x, str) or not x.strip() for x in (self.source, self.release, self.metric, self.definition)):
+            raise ValueError("Source, release, native metric and counting definition are required")
+        for value in (self.protein_sha256, self.source_sha256):
+            if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{64}", value):
+                raise ValueError("Evidence summaries require lowercase SHA-256 pins")
+        if not isinstance(self.source_url, str) or urlparse(self.source_url).scheme not in ("https", "http") or not urlparse(self.source_url).netloc:
+            raise ValueError("Evidence summaries require a source URL")
+        if self.value is not None and (type(self.value) is not int or self.value < 0):
+            raise ValueError("A support count must be a nonnegative integer or None")
+
+    @property
+    def key(self):
+        """Shared source metric identity, independent of transcript assignment."""
+        return (self.source, self.release, self.target.key, self.scope, self.method, self.metric)
+
+    @property
+    def is_supporting(self):
+        """Positive reported support; zero and unknown both fail selection."""
+        return self.value is not None and self.value > 0
+
+    def validate_orf(self, model):
+        """Reject attachment to another species, protein sequence or native ORF."""
+        if self.target.reference.taxon_id != model.taxon_id:
+            raise ValueError("Summary and ORF species disagree")
+        reference = self.target.reference
+        if reference.genome_build is not None and reference.genome_build != model.genome_build:
+            raise ValueError("Summary and ORF assemblies disagree")
+        for field in ("strain", "strain_taxon_id"):
+            source = getattr(reference, field)
+            destination = getattr(model.reference_context, field, None)
+            if source != destination:
+                raise ValueError("Summary and ORF strain contexts disagree")
+        if self.protein_sha256 != hashlib.sha256(model.protein_sequence.encode("ascii")).hexdigest():
+            raise ValueError("Summary and ORF protein sequences disagree")
+        if self.scope == "orf" and (
+            self.target.identifier != model.orf_id
+            or reference.genome_build != model.genome_build
+            or (model.reference_context is not None and reference.key != model.reference_context.key)
+        ):
+            raise ValueError("Summary and native ORF identities disagree")
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, record):
+        record = dict(record)
+        target = dict(record["target"])
+        target["reference"] = ReferenceContext(**target["reference"])
+        record["target"] = ScopedTarget(**target)
+        return cls(**record)
+
+
+def unique_summaries(summaries):
+    """Preserve first occurrence; conflicting facts for one identity are errors."""
+    result = {}
+    for summary in summaries:
+        if not isinstance(summary, EvidenceSummary):
+            raise TypeError("Expected EvidenceSummary")
+        previous = result.setdefault(summary.key, summary)
+        if previous != replace(summary, target=previous.target):
+            raise ValueError("Conflicting evidence summaries for one source metric")
+    return tuple(result.values())

orfdata-0.17.0/orfdata/version.py

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

{orfdata-0.16.0 → orfdata-0.17.0/orfdata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.16.0
+Version: 0.17.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.16.0 → orfdata-0.17.0}/orfdata.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ orfdata/cli.py
 orfdata/dataset.py
 orfdata/dataset_cli.py
 orfdata/datasets.py
+orfdata/evidence_summary.py
 orfdata/initiation_context.py
 orfdata/measurements.py
 orfdata/model.py
@@ -60,6 +61,7 @@ tests/conftest.py
 tests/test_copy.py
 tests/test_cross_reference_pairing.py
 tests/test_ensembl_search_reference.py
+tests/test_evidence_summary.py
 tests/test_ingolia.py
 tests/test_initiation_context.py
 tests/test_local_build_queries.py
@@ -77,6 +79,7 @@ tests/test_selectors.py
 tests/test_storage.py
 tests/test_uorf_catalog.py
 tests/test_wang.py
+tests/data/aggregate_evidence.json
 tests/data/copy/GSM1905474.soft
 tests/data/copy/GSM1905474_KL9_fpkm.txt.gz
 tests/data/copy/GSM1905476.soft