pen-stack 0.1.0__py3-none-any.whl

pen_stack/wgenome/offtarget_data.py

@@ -0,0 +1,148 @@
+"""Off-target ground-truth + provenance for the cross-family nomination engine.
+
+The ground truth is harmonized, PUBLISHED, unbiased genome-wide off-target assays over canonical Cas9 guides;
+the derived risk calibration and the Off-Target-Bench headline (the REAL CRISOT predictor vs the homology
+baseline) are embedded in-code so the axis is available everywhere (CI / bare install / live app), while the
+full sealed fixture + per-guide metrics live under ``benchmarks/offtarget/`` for the bench harness.
+
+LICENSING / SCOPE: the CRISOT predictor (Chen et al., Nat Commun 2023) is CC-BY-NC and runs ONLY on the VM,
+its binaries/weights are NEVER redistributed; only DERIVED scores are cached (exactly like the licensed MHC
+tools). Off-target SITE sequences are facts from the public assay supplements (cited below). A nominated
+off-target is a CANDIDATE, never a claim.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+# ---- validated assay provenance (independently verified 2026-06-19) -----------------------------
+ASSAY_PROVENANCE = {
+    "guideseq": {"name": "GUIDE-seq", "kind": "cell-based, unbiased, genome-wide",
+                 "citation": "Tsai et al., Nat Biotechnol 2015", "doi": "10.1038/nbt.3117"},
+    "circleseq": {"name": "CIRCLE-seq", "kind": "in vitro (cell-free), unbiased, genome-wide",
+                  "citation": "Tsai et al., Nat Methods 2017", "doi": "10.1038/nmeth.4278"},
+    "changeseq": {"name": "CHANGE-seq", "kind": "in vitro, unbiased, high-throughput (110 sgRNAs)",
+                  "citation": "Lazzarotto et al., Nat Biotechnol 2020", "doi": "10.1038/s41587-020-0555-7"},
+    "siteseq": {"name": "SITE-seq", "kind": "in vitro biochemical, unbiased",
+                "citation": "Cameron et al., Nat Methods 2017", "doi": "10.1038/nmeth.4284"},
+}
+PREDICTOR_PROVENANCE = {
+    "crisot": {"name": "CRISOT-Score", "approach": "XGBoost RNA-DNA interaction fingerprint",
+               "citation": "Chen et al., Nat Commun 2023", "doi": "10.1038/s41467-023-42695-4",
+               "license": "CC-BY-NC (run on the VM; only derived scores cached, weights never redistributed)"},
+}
+# integrase off-target assays (large serine integrases), for the assay recommender; data-thin, preprints
+INTEGRASE_ASSAY_PROVENANCE = {
+    "cryptic_seq": {"name": "Cryptic-seq / HIDE-seq", "kind": "unbiased LSI off-target discovery",
+                    "citation": "Hazelbaker et al. (Tome Biosciences), bioRxiv 2024",
+                    "doi": "10.1101/2024.08.23.609471"},
+    "intquery": {"name": "IntQuery", "kind": "LSI off-target deep-learning predictor (paper-only, no public weights)",
+                 "citation": "Bakalar et al. (Tome Biosciences), bioRxiv 2024", "doi": "10.1101/2024.10.10.617699"},
+}
+
+# canonical Cas9 guides present in the bench (20-nt protospacers; Tsai 2015/2017)
+CANONICAL_GUIDES = {
+    "EMX1": "GAGTCCGAGCAGAAGAAGAA", "VEGFA_site1": "GGGTGGGGGGAGTTTGCTCC",
+    "VEGFA_site2": "GACCCCCTCCACCCCGCCTC", "VEGFA_site3": "GGTGAGTGAGTGTGTGCGTG",
+    "FANCF": "GGAATCCCTTCTGCAGCACC", "HEK293_site2": "GAACACAAAGCATAGACTGC",
+    "HEK293_site3": "GGCCCAGACTGAGCACGTGA", "HEK293_site4": "GGCACTGCGGCTGGAGGTGG",
+}
+
+# ---- DERIVED, real-data risk calibration: empirical active fraction by mismatch count -----------
+# (computed on the VM over ALL candidates per assay; the off-target nomination risk band is grounded in how often a
+# candidate at k mismatches was actually validated-active, not a guessed curve. Missing k -> abstain, not extrapolate.)
+MISMATCH_ACTIVE_FRACTION = {
+    "guideseq": {0: 1.0, 1: 1.0, 2: 0.76471, 3: 0.23129, 4: 0.033, 5: 0.00276, 6: 0.00014},
+    "circleseq": {0: 1.0, 1: 1.0, 2: 1.0, 3: 0.67146, 4: 0.26566, 5: 0.05924, 6: 0.00985},
+    "changeseq": {0: 0.95, 2: 0.80851, 3: 0.56625, 4: 0.231, 5: 0.05505, 6: 0.00751},
+    "siteseq": {0: 1.0, 1: 1.0, 2: 1.0, 3: 0.67188, 4: 0.2491, 5: 0.03554, 6: 0.00478},
+}
+
+# ---- chromatin-accessibility validation: a CONTROLLED test of whether accessibility predicts off-target activity
+# (Lazzarotto 2020). An earlier revision used a CROSS-CELL K562 proxy (weak/inconsistent); a later revision used a CELL-TYPE-MATCHED
+# ENCODE HEK293T DNase track and SETTLED it. VERDICT: VALIDATED (moderate, cell-type-matched) for WT-Cas9 cell-based
+# off-target activity, GUIDE-seq AUROC rises 0.58 (cross-cell) -> 0.671 (matched), in-vitro control null (method
+# sound). Moderate effect (sequence/CRISOT still dominates); TTISS is the expected outlier (a Cas9-VARIANT assay).
+# Full result: benchmarks/offtarget/chromatin_validation.json.
+CHROMATIN_VALIDATION = {
+    "verdict": "validated (moderate, cell-type-matched) for WT-Cas9 cell-based off-target activity",
+    "validated": True,
+    "effect": "moderate",
+    "auroc_accessibility_for_activity": {
+        # cell-type-MATCHED HEK293T DNase (ENCFF529BOG); k562 = the earlier cross-cell proxy
+        "guideseq": {"modality": "cell-based (WT Cas9)", "auroc": 0.671, "k562_cross_cell": 0.58, "ci95": [0.642, 0.701]},
+        "ttiss": {"modality": "cell-based (Cas9 variants, outlier)", "auroc": 0.383, "k562_cross_cell": 0.346,
+                  "ci95": [0.362, 0.405]},
+        "siteseq": {"modality": "in_vitro_control", "auroc": 0.494, "k562_cross_cell": 0.469, "ci95": [0.475, 0.514]},
+    },
+    "matched_track": "ENCODE HEK293T DNase-seq (ENCFF529BOG, GRCh38)",
+    # Does accessibility add INCREMENTAL value over the CRISOT sequence score? Tested at two imbalances:
+    # a small REAL conditional signal (logreg acc coef ~0.35, CI excludes 0) but NO held-out ranking improvement
+    # (CRISOT+acc AUPRC gap CI includes 0). DECISION: annotation, NOT a re-ranker. Full result:
+    # benchmarks/offtarget/chromatin_incremental.json.
+    "incremental_over_crisot": {
+        "conditional_acc_coef": 0.351, "conditional_acc_coef_ci95": [0.2385, 0.5584], "adds_conditional_signal": True,
+        "heldout_auprc_gap": 0.0027, "heldout_auprc_gap_ci95": [-0.014, 0.0214], "improves_ranking": False,
+        "decision": "annotation only, accessibility carries a small real conditional signal but does NOT improve "
+                    "held-out nomination ranking over the CRISOT sequence score (at realistic imbalance); a "
+                    "re-ranking combiner is NOT wired in (no demonstrated benefit).",
+    },
+    "changes_numeric_risk_score": False,
+    "note": "cell-type-matched accessibility predicts WT-Cas9 cell-based off-target activity (GUIDE-seq AUROC "
+            "0.58 cross-cell -> 0.671 matched; in-vitro control null -> method sound). MODERATE effect (the "
+            "sequence/CRISOT score dominates nomination) and CELL-TYPE-SPECIFIC. Does NOT transfer to the "
+            "Cas9-VARIANT assay TTISS (0.383, the expected outlier). Tested the incremental value over "
+            "CRISOT: a small real conditional signal but NO held-out ranking improvement -> chromatin is surfaced "
+            "as a VALIDATED ANNOTATION and does NOT change the numeric risk score (CRISOT captures the ranking).",
+}
+
+# ---- Off-Target-Bench headline (REAL full-data result; per-guide AUPRC, held-out-guide bootstrap CI) -----
+# CRISOT-Score is the MD-physics, assay-AGNOSTIC scorer (not fit on these labels) -> a leakage-clean held-out
+# evaluation on every assay. GUIDE/CIRCLE-seq use canonical guides; CHANGE/SITE-seq use INDEPENDENT broad guide
+# panels (cross-assay generalization). CRISOT beats the homology baseline on ALL FOUR (per-guide bootstrap CI > 0).
+BENCH_SUMMARY = {
+    "guideseq": {"n_guides": 8, "guide_panel": "canonical", "crisot_auprc": 0.6458, "homology_auprc": 0.4668,
+                 "auprc_gap": 0.179, "gap_ci95": [0.0136, 0.3292], "crisot_beats_homology": True},
+    "circleseq": {"n_guides": 8, "guide_panel": "canonical", "crisot_auprc": 0.5197, "homology_auprc": 0.2664,
+                  "auprc_gap": 0.2533, "gap_ci95": [0.1463, 0.3704], "crisot_beats_homology": True},
+    "changeseq": {"n_guides": 20, "guide_panel": "independent_broad", "crisot_auprc": 0.541, "homology_auprc": 0.2486,
+                  "auprc_gap": 0.2924, "gap_ci95": [0.2349, 0.3477], "crisot_beats_homology": True},
+    "siteseq": {"n_guides": 11, "guide_panel": "independent_broad", "crisot_auprc": 0.5207, "homology_auprc": 0.2332,
+                "auprc_gap": 0.2874, "gap_ci95": [0.2388, 0.3354], "crisot_beats_homology": True},
+    "metric": "per-guide AUPRC; baseline = ascending mismatch count; learned = real CRISOT-Score (assay-agnostic, "
+              "VM, cached); CRISOT beats homology on all 4 assays (bootstrap CI excludes 0)",
+}
+
+
+def assay_provenance() -> dict:
+    """Validated provenance for every assay + predictor the off-target engine is grounded on."""
+    return {"nuclease_assays": ASSAY_PROVENANCE, "nuclease_predictor": PREDICTOR_PROVENANCE,
+            "integrase_assays": INTEGRASE_ASSAY_PROVENANCE}
+
+
+@lru_cache(maxsize=1)
+def bench_records() -> list[dict]:
+    """The committed Off-Target-Bench fixture (real validated off-targets + cached CRISOT scores) as a list of
+    dicts, or [] when the data tree is absent (bare wheel). Columns: assay, guide, On, Off, mismatch, active,
+    crisot_score."""
+    try:
+        import csv
+
+        from pen_stack._resources import resource
+        path = resource("benchmarks/offtarget/offtarget_bench_fixture.csv")
+        with open(path, encoding="utf-8") as fh:
+            rows = list(csv.DictReader(fh))
+        for r in rows:
+            r["mismatch"] = int(r["mismatch"])
+            r["active"] = int(r["active"])
+            r["crisot_score"] = float(r["crisot_score"])
+        return rows
+    except Exception: # noqa: BLE001 (bare wheel / no data tree -> the bench harness is checkout-only)
+        return []
+
+
+def calibrated_active_fraction(n_mismatch: int, assay: str = "guideseq") -> float | None:
+    """The empirical fraction of candidate sites at ``n_mismatch`` mismatches that were validated-active in the
+    named assay (grounded risk). None if the mismatch count is outside the calibrated range (then the axis
+    abstains rather than extrapolating)."""
+    table = MISMATCH_ACTIVE_FRACTION.get(assay, MISMATCH_ACTIVE_FRACTION["guideseq"])
+    return table.get(int(n_mismatch))

pen_stack/wgenome/offtarget_enumerate.py

@@ -0,0 +1,274 @@
+"""Genome-wide off-target ENUMERATION, the search step of the off-target finder.
+
+The off-target scorer previously only SCORED candidate sites a caller supplied. This module adds the missing half: given a guide +
+enzyme, ENUMERATE every genomic site within the mismatch tolerance across GRCh38, returning coordinates, strand,
+matched sequence, and mismatch count, so the downstream scorer ranks a genome-wide candidate set, not a
+hand-typed one (the caller supplies a guide and gets the off-target sites back).
+
+**Where it runs.** A full GRCh38 scan is heavy, so enumeration executes ONLY where Cas-OFFinder + the genome are
+present, the VM, via the `casoffinder:tools` Docker image (Bae, Park & Kim, Bioinformatics 2014,
+10.1093/bioinformatics/btu048). A build-time script enumerates the canonical guides on the VM and commits the
+resulting coordinates to `data/offtarget/enumerated_cache.parquet`. Everywhere else (the live app, CI, the laptop)
+this module REPLAYS that cache for a cached guide, or ABSTAINS with a pointer for a novel one, the same
+replay-or-abstain pattern the heavy structure oracles use. The enumerated coordinates are facts derivable from the
+public GRCh38 assembly (no license restriction, unlike the CRISOT weights), so committing the cache is clean.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from functools import lru_cache
+
+# Per-enzyme PAM + protospacer length. IUPAC PAMs are passed to Cas-OFFinder verbatim (it resolves R/V/etc.).
+# pam_side: 3 = PAM 3' of the protospacer (Cas9); 5 = PAM 5' of the protospacer (Cas12a).
+_ENZYME = {
+    "SpCas9":   {"pam": "NGG",    "pam_side": 3, "guide_len": 20},
+    "SaCas9":   {"pam": "NNGRRT", "pam_side": 3, "guide_len": 21},
+    "AsCas12a": {"pam": "TTTV",   "pam_side": 5, "guide_len": 23},
+    "LbCas12a": {"pam": "TTTV",   "pam_side": 5, "guide_len": 23},
+}
+_ALIAS = {"cas9": "SpCas9", "spcas9": "SpCas9", "nuclease": "SpCas9", "nickase": "SpCas9",
+          "sacas9": "SaCas9", "ascas12a": "AsCas12a", "lbcas12a": "LbCas12a", "cas12a": "AsCas12a",
+          # Cpf1 is the original name for Cas12a and remains in common use, so it resolves to the same enzymes
+          # rather than falling through as unrecognized.
+          "cpf1": "AsCas12a", "ascpf1": "AsCas12a", "lbcpf1": "LbCas12a"}
+DEFAULT_MAX_MISMATCH = 5
+_CACHE_PATH = "data/offtarget/enumerated_cache.parquet"
+_MOTIF_CACHE_PATH = "data/offtarget/motif_cache.parquet"  # att / CAST-spacer genome scans (label-keyed)
+
+
+def resolve_enzyme(name: str) -> str | None:
+    """Map a free-text enzyme/family to a supported nuclease key, or None if unsupported."""
+    n = (name or "").strip()
+    if n in _ENZYME:
+        return n
+    return _ALIAS.get(n.lower())
+
+
+def _strip_pam(guide: str, spec: dict) -> str:
+    """Return just the protospacer (drop a PAM the caller may have appended/prepended, and any spaces)."""
+    g = "".join(c for c in (guide or "").upper() if c in "ACGT")
+    return g[:spec["guide_len"]] if spec["pam_side"] == 3 else g[-spec["guide_len"]:]
+
+
+def build_casoffinder_input(guide: str, enzyme: str, genome_path: str, max_mismatch: int) -> str:
+    """The Cas-OFFinder v2.4 input text: genome path, the pattern (protospacer Ns + PAM in IUPAC), and the query
+    (the guide with N in the PAM positions) with the mismatch tolerance. Handles 3' (Cas9) and 5' (Cas12a) PAMs."""
+    spec = _ENZYME[enzyme]
+    g = _strip_pam(guide, spec)
+    pam, gl = spec["pam"], spec["guide_len"]
+    if spec["pam_side"] == 3:
+        pattern = "N" * gl + pam
+        query = g + "N" * len(pam)
+    else:
+        pattern = pam + "N" * gl
+        query = "N" * len(pam) + g
+    return f"{genome_path}\n{pattern}\n{query} {int(max_mismatch)}\n"
+
+
+def parse_casoffinder_output(text: str, enzyme: str) -> list[dict]:
+    """Parse Cas-OFFinder v2.4 (no-bulge) output into off-target records. The default output is 6 tab-separated
+    columns: query-pattern, chromosome-header, 0-based position, matched-DNA (lowercase = mismatch), strand,
+    mismatch-count. GRCh38's FASTA headers are verbose (``chr3  AC:...  AS:GRCh38``), so the contig name is the
+    first whitespace token of the chromosome field. Skips bulge rows (v2.0 enumerates substitutions only)."""
+    spec = _ENZYME[enzyme]
+    gl, plen = spec["guide_len"], spec["guide_len"] + len(spec["pam"])
+    out: list[dict] = []
+    for line in text.splitlines():
+        if not line.strip() or line.startswith("#") or line.lower().startswith(("crrna", "id", "bulge")):
+            continue
+        f = line.split("\t")
+        if len(f) < 6:
+            continue
+        try:
+            pos, n_mm = int(f[2]), int(f[5])
+        except ValueError:
+            continue
+        strand, dna = f[4], f[3].upper()
+        if strand not in ("+", "-") or "-" in dna:  # '-' => a bulge/gap row, skip
+            continue
+        # the query column (f[0]) encodes the guide; a batch run mixes guides, so tag each record with its guide
+        q = "".join(c for c in f[0].upper() if c in "ACGT")
+        guide = q[:gl] if spec["pam_side"] == 3 else q[-gl:]
+        out.append({"guide": guide, "chrom": f[1].split()[0], "position": pos, "strand": strand,
+                    "sequence": dna[:plen], "n_mismatch": n_mm})
+    return out
+
+
+def _casoffinder_bin() -> str | None:
+    return shutil.which("cas-offinder")
+
+
+def scan_local(guide: str, enzyme: str, genome_path: str, max_mismatch: int = DEFAULT_MAX_MISMATCH,
+               device: str = "C", workdir: str | None = None) -> list[dict]:
+    """Run Cas-OFFinder locally (VM / casoffinder:tools) and return the enumerated off-target records. Raises if
+    the binary or genome is absent, callers gate on `casoffinder_available()`. Used by the VM cache-build script."""
+    import os
+    import tempfile
+    binary = _casoffinder_bin()
+    if not binary:
+        raise RuntimeError("cas-offinder not on PATH (run inside casoffinder:tools on the VM)")
+    wd = workdir or tempfile.mkdtemp(prefix="offtgt_")
+    inp, outp = os.path.join(wd, "in.txt"), os.path.join(wd, "out.txt")
+    with open(inp, "w", encoding="utf-8") as fh:
+        fh.write(build_casoffinder_input(guide, enzyme, genome_path, max_mismatch))
+    subprocess.run([binary, inp, device, outp], check=True, capture_output=True, text=True)
+    with open(outp, encoding="utf-8") as fh:
+        return parse_casoffinder_output(fh.read(), enzyme)
+
+
+def casoffinder_available() -> bool:
+    return _casoffinder_bin() is not None
+
+
+@lru_cache(maxsize=1)
+def _cache_df():
+    """The committed genome-wide enumeration cache (enzyme, guide, chrom, position, strand, sequence, n_mismatch),
+    or None when absent (bare wheel). Enumerated on the VM over GRCh38; coordinates are public-genome facts."""
+    try:
+        import pandas as pd
+
+        from pen_stack._resources import resource
+        return pd.read_parquet(resource(_CACHE_PATH))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+# ---- generic motif (att / CAST-spacer) genome scan: an all-N pattern finds every L-mer within k mismatches ----
+def build_sequence_input(seq: str, genome_path: str, max_mismatch: int) -> str:
+    """Cas-OFFinder input for a fixed-sequence genome scan (no PAM): an all-N pattern of the sequence length, so
+    the query's specific bases match every genomic L-mer within ``max_mismatch``. Used for pseudo-att (integrase)
+    and CAST-spacer scans, where recognition is a sequence match rather than a protospacer+PAM."""
+    s = "".join(c for c in (seq or "").upper() if c in "ACGT")
+    return f"{genome_path}\n{'N' * len(s)}\n{s} {int(max_mismatch)}\n"
+
+
+def parse_sequence_output(text: str, seq_len: int) -> list[dict]:
+    """Parse a fixed-sequence (all-N pattern) Cas-OFFinder scan: same 6-column layout as the nuclease parser but
+    the query column is not enzyme-structured, so there is no guide/PAM split."""
+    out: list[dict] = []
+    for line in text.splitlines():
+        if not line.strip() or line.startswith("#"):
+            continue
+        f = line.split("\t")
+        if len(f) < 6:
+            continue
+        try:
+            pos, n_mm = int(f[2]), int(f[5])
+        except ValueError:
+            continue
+        strand, dna = f[4], f[3].upper()
+        if strand not in ("+", "-") or "-" in dna:
+            continue
+        out.append({"chrom": f[1].split()[0], "position": pos, "strand": strand,
+                    "sequence": dna[:seq_len], "n_mismatch": n_mm})
+    return out
+
+
+def scan_sequence_local(seq: str, genome_path: str, max_mismatch: int, device: str = "C",
+                        workdir: str | None = None) -> list[dict]:
+    """Run a fixed-sequence genome scan via Cas-OFFinder locally (VM). Raises if the binary/genome is absent."""
+    import os
+    import tempfile
+    binary = _casoffinder_bin()
+    if not binary:
+        raise RuntimeError("cas-offinder not on PATH (run inside casoffinder:tools on the VM)")
+    s = "".join(c for c in (seq or "").upper() if c in "ACGT")
+    wd = workdir or tempfile.mkdtemp(prefix="motif_")
+    inp, outp = os.path.join(wd, "in.txt"), os.path.join(wd, "out.txt")
+    with open(inp, "w", encoding="utf-8") as fh:
+        fh.write(build_sequence_input(s, genome_path, max_mismatch))
+    subprocess.run([binary, inp, device, outp], check=True, capture_output=True, text=True)
+    with open(outp, encoding="utf-8") as fh:
+        return parse_sequence_output(fh.read(), len(s))
+
+
+@lru_cache(maxsize=1)
+def _motif_cache_df():
+    """The committed motif (att / CAST-spacer) genome-scan cache, or None when absent. Columns: label, kind, doi,
+    query, chrom, position, strand, sequence, n_mismatch."""
+    try:
+        import pandas as pd
+
+        from pen_stack._resources import resource
+        return pd.read_parquet(resource(_MOTIF_CACHE_PATH))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def enumerate_motif(label: str) -> dict:
+    """Replay a cached genome-wide motif scan (pseudo-att for an integrase, or a CAST spacer) by label, or abstain
+    (its scan runs on the VM). Coordinates are public-genome facts; the app never fabricates sites."""
+    df = _motif_cache_df()
+    if df is not None and not df.empty:
+        sub = df[df["label"] == label]
+        if not sub.empty:
+            cols = ["chrom", "position", "strand", "sequence", "n_mismatch"]
+            rec = sub.iloc[0]
+            return {"available": True, "abstain": False, "label": label, "source": "cache",
+                    "query": str(rec.get("query", "")), "doi": str(rec.get("doi", "")),
+                    "n_sites": len(sub), "sites": sub.sort_values("n_mismatch")[cols].to_dict("records")}
+    return {"available": False, "abstain": True, "label": label, "source": "none",
+            "cached_motifs": sorted(df["label"].unique().tolist()) if df is not None and not df.empty else [],
+            "note": "genome-wide motif scan runs on the VM (casoffinder:tools over GRCh38); this surface replays "
+                    "the committed cache or abstains (no fabricated sites)."}
+
+
+@lru_cache(maxsize=1)
+def enumerated_guides() -> tuple:
+    """The (enzyme, guide) pairs whose genome-wide enumeration is cached (so the live app behaves like a finder for
+    them). Empty when no cache is present."""
+    df = _cache_df()
+    if df is None or df.empty:
+        return ()
+    return tuple(sorted({(str(r.enzyme), str(r.guide)) for r in df.itertuples()}))
+
+
+def _replay_cache(guide: str, enzyme: str, max_mismatch: int) -> list[dict] | None:
+    df = _cache_df()
+    if df is None or df.empty:
+        return None
+    spec = _ENZYME[enzyme]
+    g = _strip_pam(guide, spec)
+    sub = df[(df["enzyme"] == enzyme) & (df["guide"] == g) & (df["n_mismatch"] <= int(max_mismatch))]
+    if sub.empty:
+        return None
+    cols = ["chrom", "position", "strand", "sequence", "n_mismatch"]
+    return sub.sort_values("n_mismatch")[cols].to_dict("records")
+
+
+def enumerate_offtargets(guide: str, enzyme: str = "SpCas9", max_mismatch: int = DEFAULT_MAX_MISMATCH,
+                         allow_scan: bool = False, genome_path: str | None = None) -> dict:
+    """Genome-wide off-target enumeration for a guide. Returns a dict with the enumerated `sites` (coordinates +
+    strand + sequence + mismatch count) and the `source` (cache | scan), or an abstention.
+
+    The live app calls with ``allow_scan=False`` (never runs a genome scan in-request): it replays the committed
+    cache for a cached guide, or abstains for a novel one. The VM cache-build script calls with ``allow_scan=True``
+    inside ``casoffinder:tools`` to run the real scan. Never fabricates sites."""
+    enz = resolve_enzyme(enzyme)
+    if enz is None:
+        return {"available": False, "abstain": True, "enzyme": enzyme,
+                "note": f"enumeration supports {sorted(_ENZYME)}; {enzyme!r} is not a supported nuclease"}
+    spec = _ENZYME[enz]
+    g = _strip_pam(guide, spec)
+    if len(g) < spec["guide_len"]:
+        return {"available": False, "abstain": True, "enzyme": enz,
+                "note": f"{enz} needs a {spec['guide_len']}-nt protospacer (got {len(g)})"}
+
+    cached = _replay_cache(g, enz, max_mismatch)
+    if cached is not None:
+        return {"available": True, "abstain": False, "enzyme": enz, "guide": g, "pam": spec["pam"],
+                "source": "cache", "max_mismatch": int(max_mismatch), "n_sites": len(cached), "sites": cached,
+                "note": "genome-wide enumeration replayed from the committed GRCh38 Cas-OFFinder cache"}
+
+    if allow_scan and casoffinder_available() and genome_path:
+        sites = scan_local(g, enz, genome_path, max_mismatch)
+        return {"available": True, "abstain": False, "enzyme": enz, "guide": g, "pam": spec["pam"],
+                "source": "scan", "max_mismatch": int(max_mismatch), "n_sites": len(sites), "sites": sites,
+                "note": "genome-wide Cas-OFFinder scan over GRCh38 (VM)"}
+
+    return {"available": False, "abstain": True, "enzyme": enz, "guide": g, "pam": spec["pam"],
+            "source": "none", "cached_guides": [gg for (ee, gg) in enumerated_guides() if ee == enz],
+            "note": "genome-wide enumeration for a novel guide runs on the VM (casoffinder:tools over GRCh38); "
+                    "this surface replays the committed cache or abstains. Cached guides are listed; a VM scan "
+                    "is required to enumerate a new guide (no fabrication of sites)."}

pen_stack/wgenome/offtarget_integrase.py

@@ -0,0 +1,155 @@
+"""Serine-integrase pseudo-att genome scan.
+
+A serine integrase recombines a donor attB with genomic **pseudo-attP** sites resembling the phage attP. This
+enumerates pseudo-attP genome-wide: a fixed-sequence Cas-OFFinder scan of the attP core window over GRCh38 (heavy;
+runs on the VM, replayed from cache here), scored by att-arm similarity.
+
+**Status: mechanism-based, with a SEALED NEGATIVE recall benchmark.** Bxb1 and PhiC31 att are
+independently verified (Bxb1: FlyBase FBto0000359 / Ghosh 2003; PhiC31: PDB 9U2T/9U2S + Groth 2000), and the
+PhiC31 human pseudo-attP set is verified (Thyagarajan 2001, GenBank AF333429/30/31). But a sealed recall benchmark
+on those documented pseudosites is **NEGATIVE**, att-sequence-similarity does not recover them above random
+background (all three at the background median). So the genome-wide pseudo-attP SIMILARITY RANKING is a
+mechanism-based scan that is **not validated** as a predictor (φC31 recognition needs palindrome architecture /
+a learned model, not raw identity). The documented pseudosites are surfaced as verified known-off-target loci.
+Confirming assay: Cryptic-seq / HIDE-seq. Never fabricates sites or a validated status.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.wgenome.offtarget_enumerate import enumerate_motif
+
+_STATUS = "mechanism_based_unvalidated"  # the similarity ranking; sealed PhiC31 recall benchmark is NEGATIVE
+_ALIAS = {"bxb1": "Bxb1", "serine_integrase": "Bxb1", "pe_integrase": "Bxb1",
+          "phic31": "PhiC31", "phic31_integrase": "PhiC31"}
+_CONFIRM = "Cryptic-seq / HIDE-seq (Tome Biosciences, 2024 preprint)"
+
+# Capability disclosure: be PRECISE about what the sealed benchmark showed. What failed is a specific
+# METHOD (attP sequence-similarity scanning), NOT the existence of predictable pseudosites, the signal is real
+# (Chalberg's ~30-bp palindromic consensus; IntQuery's success on 410,776 cryptic attB), just not capturable by
+# simple similarity. The claim is narrow: "sequence similarity is insufficient", never "unpredictable".
+# φC31 carries its OWN sealed benchmark (verified documented pseudosites); other serine integrases (e.g. Bxb1) get
+# the GENERIC wording, the φC31 benchmark is cited as CROSS-INTEGRASE evidence, never as if it were their own.
+_CAPABILITY_PHIC31 = {
+    "badge": "mechanism-based · not predictive by sequence alone",
+    "microcopy": ("phiC31 pseudosite activity is sequence-guided but NOT predictable from similarity alone "
+                  "(sealed benchmark, negative); confirm empirically (Cryptic-seq / HIDE-seq)."),
+    "what_failed": ("attP sequence-SIMILARITY scanning (a specific method), NOT the existence of predictable "
+                    "pseudosites."),
+    "signal_is_real": ("the pseudosite signal IS real, Chalberg's ~30-bp palindromic consensus and IntQuery's "
+                       "success on 410,776 cryptic attB show it, just not capturable by simple sequence identity."),
+    "indicated_next_step": ("a learned / DMS model (as IntQuery uses); this sealed negative is the empirical "
+                            "justification for it, not evidence that pseudosites are unpredictable."),
+}
+_CAPABILITY_GENERIC = {
+    "badge": "mechanism-based · not predictive by sequence alone",
+    "microcopy": ("Serine-integrase pseudosite activity is sequence-guided but NOT predictable from att-similarity "
+                  "alone, so this genome-wide similarity ranking is unvalidated; confirm empirically "
+                  "(Cryptic-seq / HIDE-seq)."),
+    "what_failed": ("att sequence-SIMILARITY scanning (a specific method), NOT the existence of predictable "
+                    "pseudosites."),
+    "signal_is_real": ("the pseudosite signal IS real, Chalberg's ~30-bp palindromic consensus and IntQuery's "
+                       "success on 410,776 cryptic attB show it, just not capturable by simple sequence identity."),
+    "indicated_next_step": ("a learned / DMS model (as IntQuery uses)."),
+    "evidence_basis": ("cross-integrase: a sealed φC31 recall benchmark is NEGATIVE, the empirical basis for "
+                       "treating serine-integrase att-similarity ranking as unvalidated. No integrase-specific "
+                       "pseudosite benchmark exists here (Bxb1, for one, is highly specific)."),
+}
+
+
+def _capability(integrase: str) -> dict:
+    """φC31 owns its benchmark → φC31-specific wording; every other serine integrase gets the generic wording that
+    cites the φC31 result as cross-integrase evidence (never as if the benchmark were their own)."""
+    return _CAPABILITY_PHIC31 if integrase == "PhiC31" else _CAPABILITY_GENERIC
+
+
+@lru_cache(maxsize=1)
+def integrase_att() -> dict:
+    try:
+        import yaml
+
+        from pen_stack._resources import resource
+        return yaml.safe_load(resource("data/curated/integrase_att.yaml").read_text(encoding="utf-8")) or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def resolve_integrase(name: str) -> str | None:
+    n = (name or "").strip()
+    if n in (integrase_att().get("integrases") or {}):
+        return n
+    return _ALIAS.get(n.lower())
+
+
+def _sealed_benchmark() -> dict | None:
+    return ((integrase_att().get("integrases") or {}).get("PhiC31") or {}).get("recall_benchmark")
+
+
+def nominate_integrase(integrase: str = "Bxb1", top: int = 20) -> dict:
+    """Genome-wide pseudo-attP nomination for a serine integrase. PhiC31 returns its verified documented human
+    pseudo-attP (ψA/ψC/ψD) plus the sealed recall benchmark (NEGATIVE, verbatim). Bxb1 (and any integrase with a
+    committed genome-scan cache) returns genome-wide similarity candidates carrying the same unvalidated-ranking
+    caveat. Never fabricates sites or a validated status."""
+    att = integrase_att()
+    key = resolve_integrase(integrase)
+    bench = _sealed_benchmark()
+    if key is None or key not in (att.get("integrases") or {}):
+        return {"family": "serine_integrase", "integrase": integrase, "available": False, "abstain": True,
+                "status": _STATUS, "note": f"no encoded att for integrase {integrase!r}; encoded: "
+                f"{sorted((att.get('integrases') or {}))}", "confirm_assay": _CONFIRM,
+                "nomination_is_not_clearance": True}
+    rec = att["integrases"][key]
+
+    if key == "PhiC31":
+        # promiscuous integrase: surface the VERIFIED documented pseudo-attP + the sealed NEGATIVE recall benchmark
+        return {"family": "serine_integrase", "integrase": "PhiC31", "available": True, "abstain": False,
+                "status": _STATUS, "att_core": rec["core"], "central_dinucleotide": rec["central_dinucleotide"],
+                "att_doi": rec["doi"], "pdb": rec.get("pdb"),
+                "documented_pseudo_attP": rec.get("pseudo_attP_positive_set"),
+                "documented_source": rec.get("positive_set_source"), "documented_doi": rec.get("positive_set_doi"),
+                "sealed_recall_benchmark": bench, "benchmark_integrase": "PhiC31",
+                "benchmark_is_cross_integrase": False,
+                "similarity_ranking_validated": False, "capability": _capability("PhiC31"),
+                "specificity_note": rec.get("specificity_note"),
+                "method": ("PhiC31 documented human pseudo-attP (verified GenBank AF333429/30/31, Thyagarajan 2001) "
+                           "are surfaced as verified known off-target loci. Separately, the att-SIMILARITY genome "
+                           "scan is a mechanism-based method whose sealed recall benchmark is NEGATIVE: sequence "
+                           "similarity is INSUFFICIENT to rank these sites (the signal is real but needs a learned "
+                           "model, not raw identity). Reported verbatim."),
+                "confirm_assay": _CONFIRM,
+                "honesty": "verified documented pseudosites (grounded facts) PLUS an explicit capability disclosure: "
+                           "sequence-similarity scanning does not reliably rank them; NOT a clearance. Confirm "
+                           "empirically.",
+                "nomination_is_not_clearance": True}
+
+    # Bxb1 (and any integrase with a committed genome-scan cache): genome-wide similarity candidates
+    window = rec["scan_window"]
+    enum = enumerate_motif(f"{key}_pseudo_attP")
+    if enum.get("abstain"):
+        return {"family": "serine_integrase", "integrase": key, "available": False, "abstain": True,
+                "status": _STATUS, "att_core": rec["core"], "note": enum["note"],
+                "cached_motifs": enum.get("cached_motifs", []), "sealed_recall_benchmark": bench,
+                "confirm_assay": _CONFIRM, "nomination_is_not_clearance": True}
+    wlen = len(window)
+    noms = []
+    for s in enum["sites"]:
+        nmm = int(s["n_mismatch"])
+        noms.append({"chrom": s["chrom"], "position": s["position"], "strand": s["strand"], "site": s["sequence"],
+                     "n_mismatch": nmm, "arm_similarity": round(1.0 - nmm / wlen, 3), "output_kind": "candidate"})
+    noms.sort(key=lambda n: n["n_mismatch"])
+    return {"family": "serine_integrase", "integrase": key, "available": True, "abstain": False, "mode": "finder",
+            "status": _STATUS, "att_core": rec["core"], "central_dinucleotide": rec["central_dinucleotide"],
+            "scan_window": window, "source": enum["source"], "att_doi": rec["doi"],
+            "n_sites_genome_wide": len(noms), "nominations": noms[:top],
+            "specificity_note": rec.get("specificity_note"),
+            "sealed_recall_benchmark": bench, "benchmark_integrase": "PhiC31",
+            "benchmark_is_cross_integrase": (key != "PhiC31"),
+            "similarity_ranking_validated": False, "capability": _capability(key),
+            "method": ("fixed-sequence Cas-OFFinder scan of the attP core window over GRCh38, scored by att-arm "
+                       "similarity. The similarity RANKING is mechanism-based and NOT predictive by sequence alone: "
+                       "the sealed PhiC31 recall benchmark is NEGATIVE (sequence similarity is insufficient to "
+                       "rank pseudo-attP; the signal is real but needs a learned model, per IntQuery)."),
+            "confirm_assay": _CONFIRM,
+            "honesty": "genome-wide pseudo-attP candidates by att similarity; sequence similarity is insufficient "
+                       "to rank them (sealed-negative benchmark) -> mechanism-based, confirm empirically. NOT a clearance.",
+            "nomination_is_not_clearance": True}