pen-stack 0.1.0__py3-none-any.whl

pen_stack/wgenome/offtarget_nuclease.py

@@ -0,0 +1,123 @@
+"""Nuclease off-target FINDER: enumerate -> CRISOT -> risk -> chromatin.
+
+Chains the genome-wide enumeration into the existing, validated nuclease scorer, so a GUIDE returns a
+genome-wide ranked off-target set rather than a hand-supplied one. The scoring is
+UNCHANGED from the prior release, the real CRISOT-Score, the mismatch-calibrated risk band, and the chromatin annotation
+(validated, not a re-ranker). v2 only adds the enumeration front end. Status: **validated** (CRISOT beats
+homology on four unbiased assays; enumeration reproduces the documented off-target set).
+
+Enumeration runs on the VM; this surface replays the committed cache or abstains (so the finder works for the
+cached guides and abstains for a novel one), exactly like the heavy oracles.
+"""
+from __future__ import annotations
+
+from pen_stack.wgenome.offtarget_data import BENCH_SUMMARY, CHROMATIN_VALIDATION, calibrated_active_fraction
+from pen_stack.wgenome.offtarget_enumerate import _ENZYME, enumerate_offtargets, resolve_enzyme
+from pen_stack.wgenome.offtarget_predict import (
+    _chromatin_modifier,
+    _crisot_cache,
+    _ham20,
+    _risk_band,
+    locus_accessibility,
+)
+
+_BIN = 1000  # accessibility track bins are 1 kb (matches the off-target chromatin validation)
+_CAS12A = {"AsCas12a", "LbCas12a"}  # enumeration-supported, but the CRISOT scorer + risk calibration are SpCas9-only
+
+
+def unsupported_nuclease_abstention(enzyme: str | None, mode: str = "finder") -> dict | None:
+    """Return an abstention when no validated off-target model covers ``enzyme``, else None.
+
+    The off-target scorer (CRISOT-Score) and the mismatch-calibrated empirical risk band are both SpCas9-specific,
+    so every nuclease path declines rather than apply a SpCas9 model to a different enzyme. Two cases decline. A
+    Cas12a variant can be ENUMERATED but not scored, so it carries the Cas12a note. Any other named enzyme the
+    registry does not carry would otherwise be substituted by SpCas9 and returned under the caller's name, with a
+    PAM the caller never asked for, so it declines with a note naming what is carried. Only an unnamed enzyme falls
+    through to the SpCas9 default.
+
+    The gate is shared by the genome-wide finder and the score-my-candidates path so the two cannot drift: a caller
+    who supplies candidate sites gets the same abstention as a caller who does not.
+    """
+    requested = (enzyme or "").strip()
+    enz = resolve_enzyme(requested)
+    if enz in _CAS12A:
+        status, note = "unvalidated", (
+            "Cas12a genome-wide enumeration is supported (Cas-OFFinder, TTTV 5' PAM), but the validated off-target "
+            "scorer (CRISOT-Score) and the mismatch-calibrated empirical risk band are SpCas9-specific. No "
+            "validated Cas12a off-target model is mounted, so this path does not rank Cas12a sites with a SpCas9 "
+            "scorer, which would mis-rank them. AsCas12a is listed as a Tier-1 nuclease in the Writer Atlas; a "
+            "validated Cas12a off-target scorer is future work.")
+    elif requested and enz is None:
+        status, note = "unsupported_enzyme", (
+            f"No validated off-target model is mounted for {requested!r}. The enumerator carries "
+            f"{', '.join(sorted(_ENZYME))}, each with its own PAM, and the scorer (CRISOT-Score) with its "
+            f"mismatch-calibrated risk band is SpCas9-specific. Scoring this request would report SpCas9 sites "
+            f"under a different enzyme's name and PAM.")
+    else:
+        return None
+    return {"family": "nuclease", "enzyme": enz or requested or None, "available": False, "abstain": True,
+            "mode": mode, "status": status, "cached_guides": [], "nomination_is_not_clearance": True, "note": note}
+
+
+def find_nuclease_offtargets(guide: str, enzyme: str = "SpCas9", max_mismatch: int = 5, assay: str = "guideseq",
+                             cell_type: str = "k562", top: int = 50) -> dict:
+    """Genome-wide nuclease off-target FINDER. Enumerates every genomic site within ``max_mismatch`` for the guide
+    (Cas-OFFinder over GRCh38, replayed from cache), scores each with the real CRISOT-Score + the mismatch-
+    calibrated empirical risk band, and annotates chromatin accessibility (from the accessibility track when present). Returns
+    the genome-wide ranked candidates with coordinates, or an abstention when the guide is not cached and no
+    VM scan is available. Never fabricates sites."""
+    declined = unsupported_nuclease_abstention(enzyme, mode="finder")
+    if declined is not None:
+        return declined
+    enz = resolve_enzyme(enzyme) or "SpCas9"
+    enum = enumerate_offtargets(guide, enz, max_mismatch)
+    if enum.get("abstain"):
+        return {"family": "nuclease", "enzyme": enz, "available": False, "abstain": True, "mode": "finder",
+                "status": "validated", "note": enum["note"], "cached_guides": enum.get("cached_guides", []),
+                "nomination_is_not_clearance": True}
+    g20 = enum["guide"][:20]
+    cache = _crisot_cache()
+    noms = []
+    for s in enum["sites"]:
+        seq = s["sequence"].upper()
+        nmm = int(s.get("n_mismatch", _ham20(g20, seq)))
+        af = calibrated_active_fraction(nmm, assay)
+        crisot = cache.get((g20, seq[:20]))
+        locus_acc = locus_accessibility(s["chrom"], s["position"] // _BIN, cell_type)  # REAL accessibility track (or None)
+        noms.append({"chrom": s["chrom"], "position": s["position"], "strand": s["strand"], "site": seq,
+                     "n_mismatch": nmm, "empirical_active_fraction": af, "risk_band": _risk_band(af),
+                     "crisot_score": crisot,
+                     "crisot_source": "cached_bench" if crisot is not None else "on-VM tool (not cached)",
+                     "chromatin": _chromatin_modifier(None, locus_acc), "output_kind": "candidate"})
+    # rank by the real CRISOT score where cached, else by empirical risk (descending), then fewer mismatches
+    noms.sort(key=lambda n: (n["crisot_score"] if n["crisot_score"] is not None else -1.0,
+                             n["empirical_active_fraction"] or 0.0, -n["n_mismatch"]), reverse=True)
+    n_on = sum(1 for n in noms if n["n_mismatch"] == 0)
+    # chromatin is a REAL accessibility annotation, populated per-site only when the accessibility track is mounted.
+    # Be explicit instead of silently returning null everywhere (which reads as if the layer were delivered).
+    chromatin_available = any(n.get("chromatin") is not None for n in noms)
+    _cv = CHROMATIN_VALIDATION["auroc_accessibility_for_activity"]["guideseq"]
+    chromatin_note = (
+        "Chromatin accessibility is a VALIDATED standalone annotation (open chromatin predicts cell-based "
+        "off-target activity: GUIDE-seq AUROC 0.671, cell-type-matched HEK293T DNase) but is ANNOTATION-ONLY, it "
+        "does NOT change the CRISOT-driven ranking. It is populated per-site only when the accessibility "
+        "track (chromatin_{ct}.parquet) is mounted; that track is not present on this deployment, so the per-site "
+        "column is omitted (ranking unaffected)." if not chromatin_available else
+        "Per-site chromatin accessibility from the mounted track, annotation-only, does not change the "
+        "CRISOT-driven ranking.")
+    return {"family": "nuclease", "enzyme": enz, "available": True, "abstain": False, "mode": "finder",
+            "guide": g20, "pam": enum["pam"], "source": enum["source"], "max_mismatch": int(max_mismatch),
+            "n_sites_genome_wide": enum["n_sites"], "n_on_target": n_on, "n_offtargets": len(noms) - n_on,
+            "assay_calibration": assay, "nominations": noms[:top], "bench": BENCH_SUMMARY.get(assay),
+            "status": "validated",
+            "chromatin_available": chromatin_available, "chromatin_note": chromatin_note,
+            "chromatin_validation": {"verdict": CHROMATIN_VALIDATION["verdict"], "guideseq_auroc": _cv["auroc"],
+                                     "ci95": _cv["ci95"], "matched_track": CHROMATIN_VALIDATION["matched_track"],
+                                     "is_reranker": False},
+            "method": ("genome-wide Cas-OFFinder enumeration over GRCh38 -> real CRISOT-Score -> mismatch-"
+                       "calibrated risk band" + (" -> chromatin accessibility annotation (validated, annotation-"
+                       "only, NOT a re-ranker)" if chromatin_available else
+                       "; chromatin accessibility is a validated annotation surfaced when the accessibility track is "
+                       "mounted (annotation-only, not a re-ranker)")),
+            "honesty": "genome-wide CANDIDATES, NOT a clearance; confirm with the recommended empirical assay",
+            "nomination_is_not_clearance": True}

pen_stack/wgenome/offtarget_paste.py

@@ -0,0 +1,41 @@
+"""PASTE / (ee)PASSIGE off-target composition.
+
+PASTE installs a landing-site attB with a prime editor (a Cas9 **nickase** + reverse transcriptase directed by a
+pegRNA), then a serine **integrase** (Bxb1) inserts the cargo at the installed attB. Its off-target profile is
+therefore the COMPOSITION of two mechanisms, each with its own status:
+  * the Cas9-nickase off-targets of the pegRNA spacer  -> the validated nuclease finder, and
+  * the integrase pseudo-attP sites of the installed att -> the semi-validated integrase scan.
+
+Returns BOTH candidate sets, labelled by component, and recommends BOTH a nuclease assay and an integrase assay.
+Never fabricates; each component carries its own truthful status.
+"""
+from __future__ import annotations
+
+from pen_stack.wgenome.offtarget_integrase import nominate_integrase
+from pen_stack.wgenome.offtarget_nuclease import find_nuclease_offtargets
+
+
+def nominate_paste(guide: str | None = None, integrase: str = "Bxb1", max_mismatch: int = 5,
+                   assay: str = "guideseq", cell_type: str = "k562", top: int = 20) -> dict:
+    """Compose the nuclease (pegRNA-directed Cas9 nickase) and integrase (installed attB) off-target components.
+    Returns both candidate sets with their own statuses + the dual confirm-assay recommendation. Abstains per
+    component when its input/cache is unavailable (never fabricates)."""
+    nuclease = (find_nuclease_offtargets(guide, "SpCas9", max_mismatch=max_mismatch, assay=assay,
+                                         cell_type=cell_type, top=top)
+                if guide else {"available": False, "abstain": True, "status": "validated",
+                               "note": "provide the pegRNA spacer (guide) for the Cas9-nickase off-target scan"})
+    integ = nominate_integrase(integrase, top=top)
+    statuses = {"nuclease_component": nuclease.get("status", "validated"),
+                "integrase_component": integ.get("status", "mechanism_based_unvalidated")}
+    return {"family": "paste", "available": True, "abstain": False, "status": "composite",
+            "component_statuses": statuses,
+            "nuclease_component": nuclease,   # Cas9-nickase off-targets (pegRNA-directed), validated finder
+            "integrase_component": integ,     # installed-attB pseudo-attP, semi-validated scan
+            "confirm_assay": {"nuclease": ["GUIDE-seq", "CHANGE-seq"], "integrase": ["Cryptic-seq", "HIDE-seq"],
+                              "note": "PASTE requires BOTH a nuclease off-target assay (for the nickase) AND an "
+                                      "integrase off-target assay (for the installed att)."},
+            "method": ("compose the validated nuclease finder (nickase, pegRNA spacer) with the semi-validated "
+                       "integrase pseudo-attP scan (installed att); return both candidate sets by component"),
+            "honesty": "two component candidate sets, each with its own status; NOT a clearance. Confirm with "
+                       "both a nuclease assay and an integrase assay.",
+            "nomination_is_not_clearance": True}

pen_stack/wgenome/offtarget_predict.py

@@ -0,0 +1,282 @@
+"""Cross-writer-family, chromatin-aware off-target NOMINATION engine.
+
+One interface over nucleases, serine integrases, and bridge recombinases. By construction:
+
+  * **nuclease** (Cas9): rank candidate off-target sites by the GROUNDED empirical risk (the real-data fraction
+    of candidates at k mismatches that were validated-active, `offtarget_data.MISMATCH_ACTIVE_FRACTION`), surface
+    the REAL CRISOT-Score when the (guide, site) is in the cached bench, and annotate with a documented
+    **chromatin-accessibility signal** (a validated annotation, NOT a re-ranker: open chromatin raises realized
+    off-target activity, Lazzarotto 2020, but it added no held-out ranking gain over CRISOT in an
+    incremental analysis, so it is not folded into the risk score). The annotation
+    reads the **chromatin accessibility track** (`phase_1/features/chromatin_{ct}.parquet`) when a candidate's
+    genomic locus + cell type are supplied AND the feature store is present, or accepts a caller-supplied
+    accessibility value; it **abstains** otherwise (the bare wheel / current deployed atlas do not ship the raw
+    accessibility track). The Off-Target-Bench shows the real CRISOT predictor BEATS the homology baseline on
+    FOUR unbiased assays (GUIDE/CIRCLE/CHANGE/SITE-seq; per-guide bootstrap CI excludes 0 on each).
+  * **serine integrase** (Bxb1): nominate cryptic **pseudo-attB** sites using the REAL documented Bxb1 attB core
+    (GCGGTCTC / central GT), candidate-flagged; the validating assay is Cryptic-seq/HIDE-seq.
+  * **bridge / seek**: delegate to the existing Perry-DMS pseudosite engine (`pen_stack.bridge.offtarget`).
+
+A nominated off-target is a CANDIDATE, never a claim, and nomination is **not** a safety clearance, every result
+ships with the empirical assay that would confirm it (`offtarget_assay`). Abstains without inputs; never invents
+sites. The CRISOT predictor (CC-BY-NC) runs only on the VM; only derived scores are cached.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.wgenome.offtarget_data import (
+    BENCH_SUMMARY,
+    bench_records,
+    calibrated_active_fraction,
+)
+
+_NUCLEASE = {"cas9", "spcas9", "nuclease", "sacas9", "ascas12a", "cas12a", "nickase"}
+_INTEGRASE = {"serine_integrase", "bxb1", "phic31", "pe_integrase"}
+_BRIDGE = {"bridge_is110", "seek_is1111", "bridge", "is110", "is621", "iscro4"}
+_PASTE = {"paste", "passige", "ee_passige", "eepassige", "prime_editing_integrase"}
+_CAST = {"cast", "shcast", "vchcast", "evocast", "cast_vk", "cast_v-k", "cast_if", "cas12k", "type_v-k", "type_i-f"}
+
+
+def _ham20(a: str, b: str) -> int:
+    """Mismatches over the 20-nt protospacer (Hamming; ignores the PAM)."""
+    a, b = a[:20].upper(), b[:20].upper()
+    return sum(1 for x, y in zip(a, b) if x != y)
+
+
+def _risk_band(active_fraction: float | None) -> str:
+    if active_fraction is None:
+        return "uncalibrated"
+    if active_fraction >= 0.5:
+        return "high"
+    if active_fraction >= 0.1:
+        return "medium"
+    if active_fraction >= 0.01:
+        return "low"
+    return "minimal"
+
+
+@lru_cache(maxsize=1)
+def _crisot_cache() -> dict:
+    """(On20, Off20) -> cached real CRISOT score, from the committed bench fixture (VM-computed)."""
+    out: dict = {}
+    for r in bench_records():
+        out[(r["On"][:20].upper(), r["Off"][:20].upper())] = r["crisot_score"]
+    return out
+
+
+@lru_cache(maxsize=8)
+def _chromatin_store(ct: str):
+    """The per-cell-type chromatin feature store (chrom,bin -> unified accessibility) + its median, or
+    None when the raw track is not present (bare wheel / CI / current deployed atlas). Real, data-gated."""
+    try:
+        import pandas as pd
+
+        from pen_stack._resources import project_root
+        from pen_stack.wgenome.features import add_accessibility
+        p = project_root() / "phase_1" / "features" / f"chromatin_{ct.lower()}.parquet"
+        if not p.exists():
+            return None
+        df = add_accessibility(pd.read_parquet(p))
+        if "accessibility" not in df.columns:
+            return None
+        med = float(df["accessibility"].median())
+        return df.set_index(["chrom", "bin"]), med
+    except Exception: # noqa: BLE001
+        return None
+
+
+def locus_accessibility(chrom: str, bin_idx: int, ct: str = "k562") -> dict | None:
+    """REAL chromatin accessibility for a genomic bin (ATAC/DNase), or None (abstain) when the chromatin feature
+    store is absent or the bin is off-grid. `accessible` = above the cell-type median (relative, grounded)."""
+    store = _chromatin_store(ct)
+    if store is None:
+        return None
+    df, med = store
+    try:
+        val = float(df.loc[(chrom, int(bin_idx)), "accessibility"])
+    except Exception: # noqa: BLE001
+        return None
+    return {"accessibility_signal": round(val, 4), "cell_type": ct, "median": round(med, 4),
+            "accessible": bool(val >= med), "source": "chromatin_{ct}.parquet (ATAC/DNase)"}
+
+
+def _chromatin_modifier(accessibility: float | None = None, locus_acc: dict | None = None) -> dict | None:
+    """Documented chromatin-accessibility ANNOTATION (NOT a validated quantitative axis): open chromatin raises
+    realized off-target activity (Lazzarotto et al. 2020, CHANGE-seq, 10.1038/s41587-020-0555-7). Uses the REAL
+    chromatin accessibility (`locus_acc`) when available, else a caller-supplied 0..1 scalar; abstains (None) when
+    neither is given. It is QUALITATIVE and does NOT change the numeric risk score, a controlled test on our data
+    found the signal weak/inconsistent (see `offtarget_data.CHROMATIN_VALIDATION`)."""
+    val = {"validated": True, "effect_size": "moderate", "changes_risk_score": False,
+           "validation": "validated standalone (moderate, cell-type-matched: GUIDE-seq off-target AUROC 0.58 "
+           "cross-cell -> 0.671 matched HEK293T DNase). ANNOTATION ONLY, tested the incremental value over "
+           "CRISOT: small real conditional signal but NO held-out ranking improvement, so it does NOT change the "
+           "numeric risk score (CRISOT sequence score captures the ranking).",
+           "doi": "10.1038/s41587-020-0555-7"}
+    if locus_acc is not None:
+        raises = bool(locus_acc.get("accessible"))
+        return {**val, "raises_realized_risk": raises, "source": "stage_b_track",
+                "accessibility_signal": locus_acc.get("accessibility_signal"), "cell_type": locus_acc.get("cell_type"),
+                "effect": ("accessible (open) chromatin in this cell type -> realized off-target activity tends "
+                           "HIGHER for the same sequence match (qualitative; Lazzarotto 2020)" if raises
+                           else "inaccessible (closed) chromatin -> realized off-target activity tends lower")}
+    if accessibility is None:
+        return None
+    acc = max(0.0, min(1.0, float(accessibility)))
+    raises = acc >= 0.5
+    return {**val, "accessibility": round(acc, 3), "raises_realized_risk": raises, "source": "caller_supplied",
+            "effect": ("open/accessible chromatin -> realized off-target activity tends HIGHER (qualitative; "
+                       "Lazzarotto 2020)" if raises else "closed/inaccessible chromatin -> realized risk tends lower")}
+
+
+def nominate_nuclease(guide: str, candidate_sites: list[str] | None, accessibility: list[float] | None = None,
+                      assay: str = "guideseq", loci: list | None = None, cell_type: str = "k562",
+                      top: int = 20) -> dict:
+    """Nominate + rank candidate nuclease off-target sites for a guide. ``candidate_sites`` are 20-23-nt genomic
+    protospacers (e.g. from a Cas-OFFinder scan). ``loci`` (optional) is a per-candidate (chrom, bin) for the REAL
+    chromatin-accessibility modifier; ``accessibility`` (optional) is a per-candidate 0..1 fallback scalar.
+    Abstains (no fabrication) when no candidates are supplied, genome-wide candidate ENUMERATION needs the on-VM
+    scan; this engine SCORES + RANKS + risk-bands them."""
+    g = (guide or "").upper()
+    if len(g) < 20:
+        return {"family": "nuclease", "available": False, "abstain": True,
+                "note": "guide must be >=20 nt (protospacer)"}
+    if not candidate_sites:
+        return {"family": "nuclease", "available": False, "abstain": True,
+                "note": "no candidate sites supplied, provide Cas-OFFinder/on-VM genome-scan candidates "
+                        "(20-23 nt protospacers); this engine scores+ranks+risk-bands them, it does not "
+                        "fabricate sites", "method": "homology + real-data mismatch calibration + cached CRISOT"}
+    cache = _crisot_cache()
+    g20 = g[:20]
+    noms = []
+    for i, site in enumerate(candidate_sites):
+        s = (site or "").upper()
+        nmm = _ham20(g20, s)
+        af = calibrated_active_fraction(nmm, assay)
+        crisot = cache.get((g20, s[:20]))
+        locus_acc = None
+        if loci and i < len(loci) and loci[i]:
+            locus_acc = locus_accessibility(loci[i][0], loci[i][1], cell_type) # REAL accessibility track (or None)
+        acc = accessibility[i] if (accessibility and i < len(accessibility)) else None
+        noms.append({"site": s, "n_mismatch": nmm, "empirical_active_fraction": af,
+                     "risk_band": _risk_band(af), "crisot_score": crisot,
+                     "crisot_source": ("cached_bench" if crisot is not None else "on-VM tool (not cached)"),
+                     "chromatin": _chromatin_modifier(acc, locus_acc), "output_kind": "candidate"})
+    # rank by the real CRISOT score when available, else by empirical risk (descending), then fewer mismatches
+    noms.sort(key=lambda n: (n["crisot_score"] if n["crisot_score"] is not None else -1.0,
+                             n["empirical_active_fraction"] or 0.0, -n["n_mismatch"]), reverse=True)
+    return {"family": "nuclease", "available": True, "abstain": False, "guide": g20,
+            "n_candidates": len(noms), "assay_calibration": assay,
+            "nominations": noms[:top],
+            "method": ("risk = empirical active fraction at k mismatches (real GUIDE-seq/CIRCLE-seq data); "
+                       "ranked by the real CRISOT-Score when the (guide,site) is cached, else by empirical risk"),
+            "bench": BENCH_SUMMARY.get(assay), "output_kind": "candidate",
+            "honesty": "candidates, NOT a clearance, confirm with the recommended empirical assay"}
+
+
+def pseudo_attb_sites(sequence: str, integrase: str = "Bxb1", max_arm_mismatch: int = 4, top: int = 20) -> dict:
+    """Nominate cryptic **pseudo-attB** sites in a provided sequence for a serine integrase, seeding on the REAL
+    documented attB core (e.g. Bxb1 GCGGTCTC / central GT) and tolerating arm mismatches. Candidate-flagged; the
+    validating assay is Cryptic-seq/HIDE-seq. Abstains when no documented att core is bundled for the integrase."""
+    from pen_stack.atlas.guide_design import _INTEGRASE_ATT
+    att = _INTEGRASE_ATT.get(integrase)
+    if not att:
+        return {"family": "serine_integrase", "available": False, "abstain": True,
+                "note": f"no documented att core bundled for {integrase!r}, cannot scan without fabricating"}
+    core, attb = att["core"].upper(), att["attB"].upper()
+    seq = (sequence or "").upper()
+    L = len(attb)
+    # locate the core within the full attB so we can align scanned windows to the documented site
+    c0 = attb.find(core)
+    hits = []
+    idx = seq.find(core)
+    while idx != -1:
+        start = idx - c0
+        if 0 <= start and start + L <= len(seq):
+            window = seq[start:start + L]
+            if "N" not in window:
+                arm_mm = sum(1 for a, b in zip(window, attb) if a != b)
+                if arm_mm <= max_arm_mismatch:
+                    hits.append({"pos": start, "site": window, "arm_mismatch": arm_mm,
+                                 "core_matched": True, "output_kind": "candidate"})
+        idx = seq.find(core, idx + 1)
+    hits.sort(key=lambda h: h["arm_mismatch"])
+    return {"family": "serine_integrase", "integrase": integrase, "available": True, "abstain": False,
+            "att_core": core, "n_candidates": len(hits), "nominations": hits[:top],
+            "method": (f"cryptic pseudo-attB scan: seed on the documented {integrase} core {core} (central "
+                       f"{att['central_dinucleotide']}), verify the {L}-nt attB with <= {max_arm_mismatch} arm "
+                       "mismatches"),
+            "validating_assay": "Cryptic-seq / HIDE-seq (Hazelbaker et al., bioRxiv 2024.08.23.609471)",
+            "honesty": "CANDIDATE cryptic sites, recombination at a pseudo-attB is not claimed; confirm by "
+                       "Cryptic-seq/HIDE-seq. Quantitative LSI off-target prediction (IntQuery) is paper-only "
+                       "(no public weights), not run here."}
+
+
+def nominate_offtargets(writer_family: str, guide: str | None = None, candidate_sites: list[str] | None = None,
+                        sequence: str | None = None, accessibility: list[float] | None = None,
+                        target_core: str | None = None, fasta=None, chroms: list[str] | None = None,
+                        assay: str = "guideseq", loci: list | None = None, cell_type: str = "k562",
+                        enzyme: str | None = None, max_mismatch: int = 5) -> dict:
+    """Cross-family dispatcher. Returns a nomination dict (candidates, never claims) + the recommended validation
+    assay, or an abstention. Never fabricates off-target sites. ``loci`` (per-candidate (chrom, bin)) +
+    ``cell_type`` enable the REAL chromatin-accessibility modifier for nucleases.
+
+    For a nuclease guide WITHOUT supplied ``candidate_sites``, this runs the genome-wide FINDER
+    (enumerate GRCh38 -> CRISOT -> risk -> chromatin) by default. Supplying ``candidate_sites`` keeps the
+    score-my-candidates path (backward compatible)."""
+    from pen_stack.wgenome.offtarget_assay import recommend_assay
+    fam = (writer_family or "").lower()
+    assay_rec = recommend_assay(writer_family)
+    # PASTE first (its name embeds an integrase) → compose nuclease + integrase
+    if fam in _PASTE or "paste" in fam or "passige" in fam:
+        from pen_stack.wgenome.offtarget_paste import nominate_paste
+        res = nominate_paste(guide=guide, integrase="Bxb1", max_mismatch=max_mismatch, assay=assay,
+                             cell_type=cell_type)
+    elif fam in _CAST or "cast" in fam or "cas12k" in fam:
+        from pen_stack.wgenome.offtarget_cast import nominate_cast
+        res = nominate_cast(system=enzyme or writer_family or "ShCAST", spacer=guide, max_mismatch=max_mismatch)
+    elif fam in _NUCLEASE or "cas9" in fam or "nuclease" in fam or "cas12" in fam:
+        from pen_stack.wgenome.offtarget_nuclease import find_nuclease_offtargets, unsupported_nuclease_abstention
+        # The CRISOT scorer and the mismatch-calibrated risk band are SpCas9-specific, so BOTH nuclease paths are
+        # gated on the same abstention: supplying candidate_sites must not route around the finder's gate.
+        declined = unsupported_nuclease_abstention(enzyme or writer_family,
+                                                   mode="candidate_scoring" if candidate_sites else "finder")
+        if declined is not None:
+            res = declined
+        elif candidate_sites:  # score/rank the caller-supplied candidates
+            res = nominate_nuclease(guide or "", candidate_sites, accessibility, assay, loci=loci,
+                                    cell_type=cell_type)
+        else:  # finder: enumerate genome-wide, then score (replays the VM cache or abstains)
+            res = find_nuclease_offtargets(guide or "", enzyme=enzyme or writer_family or "SpCas9",
+                                           max_mismatch=max_mismatch, assay=assay, cell_type=cell_type)
+    elif fam in _INTEGRASE or "integrase" in fam or "bxb1" in fam or "phic31" in fam:
+        from pen_stack.wgenome.offtarget_integrase import nominate_integrase, resolve_integrase
+        # honour the explicit integrase/system selector (``enzyme``); fall back to the family string. This is why
+        # system="phiC31" must reach the phiC31 branch instead of defaulting to Bxb1.
+        sel = enzyme or ("PhiC31" if "phic31" in fam else "Bxb1")
+        integrase = resolve_integrase(sel)
+        if integrase is None:
+            # A named integrase with no curated attachment-site record. The pseudo-att scan is driven by the att
+            # core of the SPECIFIC enzyme, so substituting another integrase's att would report a Bxb1 scan under a
+            # different enzyme's name. Abstain and name what is carried instead.
+            from pen_stack.wgenome.offtarget_integrase import integrase_att
+            known = sorted((integrase_att().get("integrases") or {}).keys())
+            res = {"family": "serine_integrase", "requested_integrase": sel, "available": False, "abstain": True,
+                   "status": "unsupported_integrase", "nomination_is_not_clearance": True,
+                   "note": (f"No curated attachment-site record for integrase {sel!r}, so the pseudo-att scan does "
+                            f"not run: it is driven by the att core of the specific enzyme, and substituting a "
+                            f"different integrase's att would misattribute the sites. Carried integrases: "
+                            f"{', '.join(known)}.")}
+        elif sequence:  # scan a supplied locus for cryptic pseudo-attB
+            res = pseudo_attb_sites(sequence, integrase)
+        else:  # genome-wide pseudo-attP scan
+            res = nominate_integrase(integrase)
+    elif fam in _BRIDGE or "bridge" in fam or "is110" in fam or "is621" in fam or "seek" in fam:
+        from pen_stack.wgenome.offtarget_bridge import nominate_bridge
+        res = nominate_bridge(target_core=target_core, writer_family=writer_family, fasta=fasta, chroms=chroms)
+    else:
+        res = {"family": writer_family, "available": False, "abstain": True,
+               "note": f"no off-target nomination model for family {writer_family!r}"}
+    res["recommended_assay"] = assay_rec
+    res["nomination_is_not_clearance"] = True
+    return res

pen_stack/wgenome/ood.py

@@ -0,0 +1,135 @@
+"""Out-of-distribution / extrapolation detection.
+
+A model's prediction is only as trustworthy as the resemblance of the query to what the model was trained
+on. This detector scores how far a query sits from the training feature distribution and, when far,
+**widens the conformal interval / lowers the confidence** (the hook into :mod:`wgenome.uncertainty`). It is
+the difference between "grounded-confident" and "grounded-extrapolating" in the epistemic taxonomy.
+
+Methods (pick per data size):
+  * ``mahalanobis`` (default) - distance to the training mean under the (shrunk) training covariance;
+    natural for the low-dimensional chromatin/distance feature spaces here.
+  * ``knn`` - mean distance to the k nearest training points (non-parametric; robust to non-Gaussianity).
+  * ``isolation_forest`` - tree-based density (sklearn), for larger feature sets.
+
+Scope: OOD is defined **relative to the training data, not ground truth** - it flags "far from what I
+have seen," never "wrong." The threshold is calibrated on a held-out in-distribution-vs-deliberately-OOD
+construction (e.g. a held-out cell type or a sequence-divergent locus class) and the separation AUROC is
+reported; it is a heuristic confidence signal, not a guarantee.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from pen_stack.adapt.report import _auroc
+
+
+@dataclass
+class OODDetector:
+    method: str = "mahalanobis"
+    k: int = 10
+    shrinkage: float = 1e-3 # ridge on the covariance (numerical + small-N stability)
+    # fitted state
+    mean_: np.ndarray | None = None
+    inv_cov_: np.ndarray | None = None
+    train_: np.ndarray | None = None
+    iforest_: object | None = None
+    threshold_: float = float("nan")
+    train_quantiles_: dict = field(default_factory=dict)
+
+    # ---- fit -------------------------------------------------------------------------------------
+    def fit(self, X_train) -> "OODDetector":
+        X = np.asarray(X_train, float)
+        X = np.nan_to_num(X, nan=0.0)
+        self.mean_ = X.mean(axis=0)
+        if self.method == "mahalanobis":
+            cov = np.cov(X, rowvar=False)
+            cov = np.atleast_2d(cov) + self.shrinkage * np.eye(X.shape[1])
+            self.inv_cov_ = np.linalg.pinv(cov)
+        elif self.method == "knn":
+            self.train_ = X
+            try:
+                from scipy.spatial import cKDTree
+                self._kdtree = cKDTree(X) # O(log n) queries instead of an O(n) row-loop
+            except Exception: # noqa: BLE001 - scipy absent -> fall back to the brute-force loop
+                self._kdtree = None
+        elif self.method == "isolation_forest":
+            from sklearn.ensemble import IsolationForest
+            self.iforest_ = IsolationForest(n_estimators=200, random_state=42).fit(X)
+        else:
+            raise ValueError(f"unknown OOD method: {self.method}")
+        # store the in-distribution score distribution (for a default threshold + monotone widening)
+        s = self.score(X)
+        self.train_quantiles_ = {q: float(np.quantile(s, q)) for q in (0.5, 0.9, 0.95, 0.99)}
+        self.threshold_ = self.train_quantiles_[0.95] # default: 95th in-dist percentile
+        return self
+
+    # ---- score -----------------------------------------------------------------------------------
+    def score(self, X) -> np.ndarray:
+        """Higher = more out-of-distribution."""
+        X = np.nan_to_num(np.asarray(X, float), nan=0.0)
+        if X.ndim == 1:
+            X = X.reshape(1, -1)
+        if self.method == "mahalanobis":
+            d = X - self.mean_
+            m2 = np.einsum("ij,jk,ik->i", d, self.inv_cov_, d)
+            return np.sqrt(np.clip(m2, 0, None))
+        if self.method == "knn":
+            kk = min(self.k, len(self.train_))
+            if getattr(self, "_kdtree", None) is not None:
+                d, _ = self._kdtree.query(X, k=kk) # (n, kk) nearest-neighbour distances
+                d = np.atleast_2d(d)
+                return d.mean(axis=1)
+            out = []
+            for row in X:
+                dist = np.sqrt(((self.train_ - row) ** 2).sum(axis=1))
+                out.append(float(np.sort(dist)[:kk].mean()))
+            return np.asarray(out)
+        if self.method == "isolation_forest":
+            return -self.iforest_.score_samples(X) # higher = more anomalous
+        raise ValueError(self.method)
+
+    # ---- threshold calibration on a held-out in-dist vs OOD set ----------------------------------
+    def calibrate_threshold(self, X_id, X_ood) -> dict:
+        """Pick a threshold separating held-out in-distribution from deliberately-OOD queries and report
+        the separation AUROC (acceptance: >= 0.75). Threshold = Youden-J-optimal point on the ROC."""
+        s_id = self.score(X_id)
+        s_ood = self.score(X_ood)
+        scores = np.concatenate([s_id, s_ood])
+        labels = np.concatenate([np.zeros(len(s_id)), np.ones(len(s_ood))]) # 1 = OOD
+        auroc = _auroc(list(scores), list(labels))
+        # Youden J over candidate thresholds (the unique scores), VECTORIZED via searchsorted so this is
+        # O(n log n), not O(n^2) - the naive per-threshold mean loop is prohibitive at n in the thousands.
+        thr = np.unique(scores)
+        id_sorted, ood_sorted = np.sort(s_id), np.sort(s_ood)
+        tpr = 1.0 - np.searchsorted(ood_sorted, thr, side="left") / len(ood_sorted) # P(s_ood >= t)
+        fpr = 1.0 - np.searchsorted(id_sorted, thr, side="left") / len(id_sorted) # P(s_id >= t)
+        j = tpr - fpr
+        best = int(np.argmax(j))
+        best_t, best_j = float(thr[best]), float(j[best])
+        self.threshold_ = best_t
+        return {"auroc": auroc, "threshold": best_t, "youden_j": best_j,
+                "n_id": int(len(s_id)), "n_ood": int(len(s_ood)),
+                "separates": bool(auroc >= 0.75)}
+
+    def is_ood(self, X) -> np.ndarray:
+        return self.score(X) >= self.threshold_
+
+    # ---- widening hook into the conformal interval -----------------------------------------------
+    def widen_factor(self, X, cap: float = 3.0) -> np.ndarray:
+        """Monotone interval-widening / confidence-deflation multiplier in [1, cap].
+
+        1.0 at/below the in-distribution median; rises smoothly with the OOD score, saturating at ``cap``.
+        Monotonicity is the UQ2 acceptance property: more OOD never narrows the interval.
+        """
+        s = self.score(X)
+        lo = self.train_quantiles_.get(0.5, float(np.median(s)))
+        hi = self.train_quantiles_.get(0.99, lo + 1.0)
+        span = max(hi - lo, 1e-9)
+        frac = np.clip((s - lo) / span, 0.0, 1.0)
+        return 1.0 + frac * (cap - 1.0)
+
+    def confidence(self, X) -> np.ndarray:
+        """A 0-1 confidence that DECREASES monotonically with the OOD score (1 / widen_factor)."""
+        return 1.0 / self.widen_factor(X)