pooledscreenid 0.1.1__py3-none-any.whl

pooledscreenid/__init__.py

@@ -0,0 +1,14 @@
+"""Public API for PooledScreenID."""
+
+from .audit import evaluate_evidence, run_audit, summarize_fold_gains
+from .models import AuditConfig, EvidenceVector
+
+__all__ = [
+    "AuditConfig",
+    "EvidenceVector",
+    "evaluate_evidence",
+    "run_audit",
+    "summarize_fold_gains",
+]
+
+__version__ = "0.1.1"

pooledscreenid/audit.py

@@ -0,0 +1,186 @@
+"""Evidence-vector construction and priority-ordered claim resolution."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+from pathlib import Path
+from statistics import mean
+from typing import Any
+
+from .ledger import build_claim_ledger
+from .models import AuditConfig, EvidenceVector
+
+
+def sha256_file(path: str | Path) -> str:
+    target = Path(path)
+    return hashlib.sha256(target.read_bytes()).hexdigest()
+
+
+def summarize_fold_gains(path: str | Path) -> dict[str, Any]:
+    """Summarize a frozen fold table.
+
+    Required columns are `fold`, `unadjusted_gain` and `adjusted_gain`.
+    Folds are descriptive repetitions, not independent biological units.
+    """
+    target = Path(path)
+    with target.open(newline="", encoding="utf-8") as handle:
+        rows = list(csv.DictReader(handle))
+    if not rows:
+        raise ValueError("fold-gain table is empty")
+    required = {"fold", "unadjusted_gain", "adjusted_gain"}
+    missing = required - set(rows[0])
+    if missing:
+        raise ValueError(f"missing fold columns: {sorted(missing)}")
+    folds = [row["fold"] for row in rows]
+    if len(folds) != len(set(folds)):
+        raise ValueError("fold identifiers must be unique")
+    unadjusted = [float(row["unadjusted_gain"]) for row in rows]
+    adjusted = [float(row["adjusted_gain"]) for row in rows]
+    return {
+        "folds": len(rows),
+        "unadjusted_gain_mean": mean(unadjusted),
+        "adjusted_gain_mean": mean(adjusted),
+        "unadjusted_gain_range": [min(unadjusted), max(unadjusted)],
+        "adjusted_gain_range": [min(adjusted), max(adjusted)],
+        "input_sha256": sha256_file(target),
+    }
+
+
+def evaluate_evidence(config: AuditConfig, summary: dict[str, Any]) -> EvidenceVector:
+    threshold = config.materiality_threshold
+    unadjusted = float(summary["unadjusted_gain_mean"])
+    adjusted = float(summary["adjusted_gain_mean"])
+    material = unadjusted >= threshold
+    control_associated = material and adjusted < threshold
+
+    distance: float | None = None
+    if config.eta is None or config.eta_boundary is None:
+        separability = "not_evaluated"
+    else:
+        distance = config.eta_boundary - config.eta
+        if config.eta > config.eta_boundary:
+            separability = "non_identifiable"
+        elif distance <= config.boundary_zone:
+            separability = "boundary_proximal"
+        else:
+            separability = "within_calibrated_region"
+
+    external_status = str(config.external_calibration.get("status", "not_evaluated"))
+    if separability == "non_identifiable":
+        resolution = "non_identifiable"
+    elif separability == "boundary_proximal":
+        resolution = "restricted_boundary_proximal"
+    elif not material:
+        resolution = "no_material_increment"
+    elif control_associated:
+        resolution = "control_associated"
+    elif external_status == "supportive_same_estimand":
+        resolution = "externally_supported_surviving_increment"
+    else:
+        resolution = "surviving_increment"
+
+    allowed = [
+        f"The frozen {config.estimand} and its uncertainty may be reported.",
+        "Cold-start transport and information-source attribution are reported separately.",
+    ]
+    restricted: list[str] = []
+    prohibited = [
+        "Prediction alone does not establish a binding or causal mechanism.",
+        "This analysis does not support patient-level treatment recommendation.",
+    ]
+    if not material:
+        restricted.append("No material increment was observed at the frozen threshold.")
+        prohibited.append("Do not interpret the result as equivalence or a biological null.")
+    if control_associated:
+        restricted.append("The apparent increment is associated with the outcome-blind control channel.")
+        prohibited.append("Do not claim that adjustment proves the shared signal is purely technical.")
+    if separability in {"non_identifiable", "boundary_proximal"}:
+        restricted.append("Fine-grained attribution is restricted by the prespecified separability assessment.")
+        prohibited.append("Do not make a structure-specific attribution from this dataset.")
+    if separability == "not_evaluated":
+        prohibited.append("Do not claim that representation separability was established.")
+    if external_status == "supportive_distinct_estimand":
+        restricted.append(
+            "External positive calibration concerns a distinct estimand and does not validate the target representation."
+        )
+    elif external_status in {"not_evaluated", "external_contrast_only"}:
+        prohibited.append("Do not claim external calibration of the target estimand.")
+
+    context = {
+        "prediction_unit": config.prediction_unit,
+        "independent_unit": config.independent_unit,
+        "block_unit": config.block_unit,
+        "target_representation": config.target_representation,
+        "outcome_blind_control": config.outcome_blind_control,
+        "source_id": config.source_id,
+        "fold_summary": summary,
+        "folds_are_independent_biological_units": False,
+    }
+    return EvidenceVector(
+        dataset_id=config.dataset_id,
+        folds=int(summary["folds"]),
+        unadjusted_gain_mean=unadjusted,
+        adjusted_gain_mean=adjusted,
+        materiality_threshold=threshold,
+        material_signal="supported" if material else "below_threshold",
+        control_association="supported" if control_associated else "not_supported",
+        separability=separability,
+        external_calibration=config.external_calibration,
+        eta=config.eta,
+        eta_boundary=config.eta_boundary,
+        boundary_distance=distance,
+        claim_resolution=resolution,
+        allowed_claims=tuple(allowed),
+        restricted_claims=tuple(restricted),
+        prohibited_claims=tuple(prohibited),
+        audit_context=context,
+    )
+
+
+def _markdown(report: dict[str, Any]) -> str:
+    return "\n".join(
+        [
+            f"# {report['dataset_id']} PooledScreenID report",
+            "",
+            f"- Claim resolution: `{report['claim_resolution']}`",
+            f"- Unadjusted gain: `{report['unadjusted_gain_mean']:.6f}`",
+            f"- Adjusted gain: `{report['adjusted_gain_mean']:.6f}`",
+            f"- Materiality threshold: `{report['materiality_threshold']:.6f}`",
+            f"- Separability: `{report['separability']}`",
+            f"- External calibration: `{report['external_calibration']['status']}`",
+            "",
+            "## Allowed claims",
+            *[f"- {x}" for x in report["allowed_claims"]],
+            "",
+            "## Restricted claims",
+            *([f"- {x}" for x in report["restricted_claims"]] or ["- None recorded."]),
+            "",
+            "## Prohibited interpretations",
+            *[f"- {x}" for x in report["prohibited_claims"]],
+            "",
+        ]
+    )
+
+
+def run_audit(config_path: str | Path, output_dir: str | Path) -> tuple[dict[str, Any], dict[str, Any]]:
+    config_file = Path(config_path).resolve()
+    config = AuditConfig.from_dict(json.loads(config_file.read_text(encoding="utf-8")))
+    fold_file = (config_file.parent / config.fold_gains_csv).resolve()
+    summary = summarize_fold_gains(fold_file)
+    vector = evaluate_evidence(config, summary)
+    report = vector.to_dict()
+    report["software"] = {"name": "pooledscreenid", "version": "0.1.1"}
+    report["config_sha256"] = sha256_file(config_file)
+    ledger = build_claim_ledger(report)
+    target = Path(output_dir)
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "report.json").write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    (target / "report.md").write_text(_markdown(report), encoding="utf-8")
+    (target / "claim_ledger.json").write_text(json.dumps(ledger, indent=2) + "\n", encoding="utf-8")
+    if config.expected_claim_resolution and report["claim_resolution"] != config.expected_claim_resolution:
+        raise RuntimeError(
+            f"frozen expectation mismatch: {report['claim_resolution']} != {config.expected_claim_resolution}"
+        )
+    return report, ledger

pooledscreenid/cli.py

@@ -0,0 +1,23 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .audit import run_audit
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="pooledscreenid")
+    sub = parser.add_subparsers(dest="command", required=True)
+    audit = sub.add_parser("audit", help="run an evidence-to-claim audit")
+    audit.add_argument("--config", required=True)
+    audit.add_argument("--output-dir", required=True)
+    args = parser.parse_args()
+    report, _ = run_audit(args.config, args.output_dir)
+    print(json.dumps({"dataset_id": report["dataset_id"], "claim_resolution": report["claim_resolution"]}))
+
+
+if __name__ == "__main__":
+    main()

pooledscreenid/ledger.py

@@ -0,0 +1,42 @@
+"""Versioned machine-readable claim ledger."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_claim_ledger(report: dict[str, Any]) -> dict[str, Any]:
+    evidence_id = f"{report['dataset_id']}:screen-audit-v1"
+    return {
+        "schema_version": "1.1.0",
+        "software": report["software"],
+        "dataset_id": report["dataset_id"],
+        "evidence": [
+            {
+                "evidence_id": evidence_id,
+                "material_signal": report["material_signal"],
+                "control_association": report["control_association"],
+                "separability": report["separability"],
+                "external_calibration": report["external_calibration"],
+                "claim_resolution": report["claim_resolution"],
+                "resolution_inputs": {
+                    "material_signal": report["material_signal"],
+                    "control_association": report["control_association"],
+                    "separability": report["separability"],
+                    "external_calibration": report["external_calibration"]["status"],
+                },
+                "config_sha256": report["config_sha256"],
+                "input_sha256": report["audit_context"]["fold_summary"]["input_sha256"],
+            }
+        ],
+        "allowed_claims": [
+            {"text": text, "evidence_ids": [evidence_id]} for text in report["allowed_claims"]
+        ],
+        "restricted_claims": [
+            {"text": text, "evidence_ids": [evidence_id]} for text in report["restricted_claims"]
+        ],
+        "prohibited_claims": [
+            {"text": text, "evidence_ids": [evidence_id]} for text in report["prohibited_claims"]
+        ],
+        "human_review_required": True,
+    }

pooledscreenid/models.py

@@ -0,0 +1,64 @@
+"""Typed configuration and evidence objects."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AuditConfig:
+    dataset_id: str
+    fold_gains_csv: str
+    materiality_threshold: float
+    target_representation: str
+    outcome_blind_control: str
+    prediction_unit: str
+    independent_unit: str
+    block_unit: str
+    estimand: str
+    eta: float | None = None
+    eta_boundary: float | None = None
+    boundary_zone: float = 0.0
+    source_id: str = ""
+    external_calibration: dict[str, Any] = field(
+        default_factory=lambda: {
+            "status": "not_evaluated",
+            "source": "",
+            "estimand": "",
+            "note": "No external calibration was supplied for this audit.",
+        }
+    )
+    expected_claim_resolution: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "AuditConfig":
+        return cls(**value)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class EvidenceVector:
+    dataset_id: str
+    folds: int
+    unadjusted_gain_mean: float
+    adjusted_gain_mean: float
+    materiality_threshold: float
+    material_signal: str
+    control_association: str
+    separability: str
+    external_calibration: dict[str, Any]
+    eta: float | None
+    eta_boundary: float | None
+    boundary_distance: float | None
+    claim_resolution: str
+    allowed_claims: tuple[str, ...]
+    restricted_claims: tuple[str, ...]
+    prohibited_claims: tuple[str, ...]
+    audit_context: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

pooledscreenid-0.1.1.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pooledscreenid
+Version: 0.1.1
+Summary: Outcome-blind shortcut and separability diagnostics for pooled variant-effect screens
+Author: Niu Niu, Fang Wei, Yan Wang, Hu Liu, Bin Wu
+License-Expression: MIT
+Project-URL: Documentation, https://doi.org/10.5281/zenodo.22156510
+Project-URL: Repository, https://doi.org/10.5281/zenodo.22156510
+Keywords: deep mutational scanning,cold start,negative control,identifiability,variant effect
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PooledScreenID
+
+PooledScreenID is a small, installable Python package for reporting four
+quantities separately in cold-start pooled variant-effect analyses:
+
+1. material predictive gain;
+2. association with an outcome-blind control channel;
+3. representation separability at a prespecified operating scale;
+4. external calibration, kept distinct from the target estimand; and
+5. the resulting allowed, restricted and prohibited claims.
+
+The package does not infer a molecular mechanism and does not make treatment
+recommendations. A cold split is treated as a transport test, not as proof of
+the information source used by a model.
+
+## Install
+
+```bash
+python -m pip install pooledscreenid-0.1.1-py3-none-any.whl
+```
+
+For a source checkout:
+
+```bash
+python -m pip install -e .
+```
+
+## Minimal Python API
+
+```python
+from pooledscreenid import run_audit
+
+report, ledger = run_audit(
+    config_path="examples/configs/egfr.json",
+    output_dir="example_output/egfr",
+)
+print(report["claim_resolution"])
+```
+
+## Command line
+
+```bash
+pooledscreenid audit \
+  --config examples/configs/egfr.json \
+  --output-dir example_output/egfr
+
+pooledscreenid audit \
+  --config examples/configs/met.json \
+  --output-dir example_output/met
+```
+
+Each run writes `report.json`, `report.md` and `claim_ledger.json`. Inputs,
+configuration, source hashes and expected outputs are frozen in the release.
+The ledger exposes `material_signal`, `control_association`, `separability` and
+`external_calibration` as independent fields. `claim_resolution` is generated
+from those fields under priority-ordered rules and never replaces them.
+
+PooledScreenID 0.1.1 is the article-linked frozen release. The public API is
+managed with semantic versioning. It supports Python 3.10-3.13 and has no
+third-party runtime dependencies; the test suite uses pytest.
+
+## Included end-to-end examples
+
+- `EGFR`: ten frozen variant-cold folds from the L858R-background pooled EGFR
+  inhibitor screen, plus the outcome-free geometry and conditional operating
+  boundary used in the manuscript.
+- `MET`: ten frozen variant-cold folds from an independently selected pooled
+  MET inhibitor screen. The example demonstrates a result below the materiality
+  gate and explicitly leaves separability unevaluated.
+
+These examples begin with frozen, source-derived fold diagnostics rather than
+raw sequencing reads. They reproduce the evidence-to-claim stage of the
+framework; raw count processing and model fitting remain documented in the
+accompanying analysis repository.
+
+## Interpretation order
+
+The software reports the four-axis evidence vector before returning a summary label. If
+shared predictability exceeds its prespecified boundary, or lies inside a
+prespecified boundary zone, fine-grained attribution is restricted before any
+control-specific contrast is interpreted. Absence of a material increment is
+not an equivalence or biological-null claim.
+
+## Release integrity
+
+`RELEASE_MANIFEST.json` and `SHA256SUMS.txt` bind the software, tests, continuous-integration configuration, examples,
+configuration files and claim ledger to this release. The Zenodo record is the
+permanent release series: <https://doi.org/10.5281/zenodo.22156510>.

pooledscreenid-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+pooledscreenid/__init__.py,sha256=9o0NnQxjPSiEPOkB9CSV8WQ4a6mjQk92ps2c4VZb67I,305
+pooledscreenid/audit.py,sha256=b2p55RmTYJWwQ5gGv2Cx2MsIYB0qIGJtlCP0Rs_uOh4,8092
+pooledscreenid/cli.py,sha256=HhIgkN4tyI5ekIT1b4XgAsdIkBQYlPqqj4IE_FOGrRI,684
+pooledscreenid/ledger.py,sha256=Mj0jD49eyXyPrTb_Ob4VH6AkRDFt_wg51lXAsuSdGxA,1746
+pooledscreenid/models.py,sha256=p7tUH6kJ0xbHHyV4e5Tb7DHxia6o1BdRIBjEI0Et1A4,1737
+pooledscreenid-0.1.1.dist-info/licenses/LICENSE,sha256=LLLMBRn7oZ4PwrMz6U8UCSVYRigdirt1qhSA6mP7ju0,1084
+pooledscreenid-0.1.1.dist-info/METADATA,sha256=tZFvDpwtXnWJdX_jtAn4adM1Br5fmAbQyHpKujTZ0xA,4236
+pooledscreenid-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pooledscreenid-0.1.1.dist-info/entry_points.txt,sha256=yf1FXDIoXcQunmZ58K4UJO4nuO7LsTcSELBm6TEvAqU,59
+pooledscreenid-0.1.1.dist-info/top_level.txt,sha256=j6eeGZFsoHs0t_XDOw04BjRL8Tl_otA3G0bpwccAtTQ,15
+pooledscreenid-0.1.1.dist-info/RECORD,,

pooledscreenid-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pooledscreenid-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pooledscreenid = pooledscreenid.cli:main

pooledscreenid-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PooledScreenID contributors
+
+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.

pooledscreenid-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pooledscreenid