pen-stack 3.1.0__py3-none-any.whl

pen_stack/wgenome/providers.py

@@ -0,0 +1,245 @@
+"""External sequence-to-function providers (v3.1, WS-C).
+
+AlphaGenomeProvider wraps Google DeepMind's AlphaGenome (free, non-commercial) behind a small, cached,
+provider-agnostic interface so the rest of PEN-STACK never imports `alphagenome` directly. It supplies:
+
+  * tracks(interval, outputs, ontology)  -> per-base predictions (ATAC/DNASE/RNA_SEQ/CHIP_HISTONE/...)
+  * expression(interval, ontology)       -> scalar endogenous expression proxy (mean RNA_SEQ over interval)
+  * contact_map(interval)                -> predicted Hi-C contact matrix (3D structural-risk feature, WS-C2)
+
+Design rules (match the rest of the stack):
+  * The LLM and the provider are NON-load-bearing for reproducibility - every cached value is keyed by an
+    explicit (assembly, interval, output, ontology) tuple and written to disk, so a run is reproducible
+    offline from the cache without re-querying the API.
+  * The API key is read from env (ALPHAGENOME_API_KEY) or a gitignored file; NEVER committed.
+  * `alphagenome` is an optional dependency. If the package or key is absent, `available()` is False and the
+    dependent baselines (WS-B1, WS-C) report `pending` rather than crashing - the core stack is unaffected.
+
+Caching: predictions are large (up to ~1M rows). We cache the *reduced* features we actually consume
+(scalar expression, mean track signal, contact-map summary statistics) as small JSON/parquet, not the raw
+1 Mb tensors, keyed by a content hash of the request.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parents[2]
+_CACHE = _ROOT / "data" / "alphagenome_cache"
+_KEY_FILE = _ROOT / "configs" / "alphagenome_api_key.txt"
+_KEY_ENV = "ALPHAGENOME_API_KEY"
+
+# 1 Mb is AlphaGenome's max; expression/structural features use it for full regulatory context.
+SEQ_LEN_1MB = 1_048_576
+
+# Model version recorded in track-cache keys + artifacts (C1 reproducibility). Bump when the served model
+# changes so stale predictions are not silently reused.
+MODEL_VERSION = "alphagenome-2025-06"
+
+# The seven measured-atlas tracks and their AlphaGenome sources. The five histone marks come from the single
+# CHIP_HISTONE output selected by its `histone_mark` metadata column.
+_HISTONES = ["H3K27ac", "H3K4me1", "H3K4me3", "H3K9me3", "H3K27me3"]
+TRACK_NAMES = ["atac", "dnase", *_HISTONES]
+
+# K562 / HepG2 cell-type ontologies (verified against AlphaGenome human output_metadata).
+CT_ONTOLOGY = {"k562": "EFO:0002067", "hepg2": "EFO:0001187"}
+
+
+def _resolve_key() -> str | None:
+    """API key from env first, then a gitignored file. Returns None if neither is present."""
+    k = os.environ.get(_KEY_ENV)
+    if k:
+        return k.strip()
+    if _KEY_FILE.exists():
+        for line in _KEY_FILE.read_text(encoding="utf-8").splitlines():
+            s = line.strip().rstrip('",; ')
+            if s and not s.lower().startswith("alphagenome") and len(s) > 20:
+                return s
+    return None
+
+
+def package_available() -> bool:
+    try:
+        import alphagenome  # noqa: F401
+        return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _cache_key(*parts) -> str:
+    return hashlib.sha256("|".join(str(p) for p in parts).encode()).hexdigest()[:24]
+
+
+class AlphaGenomeProvider:
+    """Cached wrapper around AlphaGenome's dna_client. Construct with `AlphaGenomeProvider()`."""
+
+    def __init__(self, api_key: str | None = None, assembly: str = "hg38", cache_dir: Path = _CACHE):
+        self.assembly = assembly
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._key = api_key or _resolve_key()
+        self._model = None  # lazily created on first live call
+
+    # -- availability ------------------------------------------------------
+    def available(self) -> bool:
+        """True when both the package and a key are present (a live call is possible)."""
+        return package_available() and self._key is not None
+
+    def _client(self):
+        if self._model is None:
+            from alphagenome.models import dna_client
+            self._model = dna_client.create(self._key)
+        return self._model
+
+    # -- cache helpers -----------------------------------------------------
+    def _load(self, key: str):
+        f = self.cache_dir / f"{key}.json"
+        if f.exists():
+            return json.loads(f.read_text(encoding="utf-8"))
+        return None
+
+    def _store(self, key: str, value: dict) -> None:
+        (self.cache_dir / f"{key}.json").write_text(json.dumps(value, default=str), encoding="utf-8")
+
+    # -- features ----------------------------------------------------------
+    def expression(self, chrom: str, start: int, end: int, ontology: str, organism: str = "human",
+                   center_bp: int = 20_000, offline: bool = False) -> dict:
+        """Scalar endogenous-expression proxy: mean predicted RNA_SEQ in a central window (cached).
+
+        The 1 Mb model context is needed for regulatory reach, but the proxy averages only the central
+        `center_bp` (host-locus expression at the integration site) rather than the whole 1 Mb, which would
+        wash out the local signal.
+        """
+        key = _cache_key("expr", self.assembly, organism, chrom, start, end, ontology, center_bp)
+        hit = self._load(key)
+        if hit is not None:
+            return hit
+        if offline:
+            return {"available": False, "reason": "offline: not in cache", "key": key}
+        if not self.available():
+            return {"available": False, "reason": "alphagenome package or key absent", "key": key}
+        from alphagenome.data import genome
+        from alphagenome.models import dna_client
+        org = (dna_client.Organism.MUS_MUSCULUS if organism == "mouse"
+               else dna_client.Organism.HOMO_SAPIENS)
+        interval = genome.Interval(chromosome=chrom, start=start, end=end).resize(SEQ_LEN_1MB)
+        out = self._client().predict_interval(
+            interval=interval, organism=org,
+            requested_outputs=[dna_client.OutputType.RNA_SEQ], ontology_terms=[ontology])
+        import numpy as np
+        arr = np.asarray(out.rna_seq.values)            # (1_048_576, n_tracks)
+        mid = arr.shape[0] // 2
+        half = max(1, center_bp // 2)
+        central = arr[max(0, mid - half):mid + half]
+        rec = {"available": True, "rna_seq_mean": float(central.mean()),
+               "rna_seq_max": float(central.max()), "center_bp": center_bp,
+               "chrom": chrom, "start": start, "end": end,
+               "ontology": ontology, "organism": organism, "key": key}
+        self._store(key, rec)
+        return rec
+
+    def tracks(self, chrom: str, bin: int, ct: str, bin_size: int = 1000, center_bp: int = 1000,
+               offline: bool = False) -> dict:
+        """Predicted values of the seven measured-atlas tracks at a 1 kb bin (central-window mean, cached).
+
+        `ct` is "k562" or "hepg2"; the bin centre is `bin*bin_size + bin_size/2`, predicted in 1 Mb context.
+        Returns {atac, dnase, H3K27ac, H3K4me1, H3K4me3, H3K9me3, H3K27me3, model_version, ...}.
+        """
+        ontology = CT_ONTOLOGY.get(ct.lower(), ct)
+        key = _cache_key("tracks", self.assembly, MODEL_VERSION, chrom, bin, ontology, bin_size, center_bp)
+        hit = self._load(key)
+        if hit is not None:
+            return hit
+        if offline:
+            return {"available": False, "reason": "offline: not in cache", "key": key}
+        if not self.available():
+            return {"available": False, "reason": "alphagenome package or key absent", "key": key}
+        import numpy as np
+        from alphagenome.data import genome
+        from alphagenome.models import dna_client
+        pos = bin * bin_size + bin_size // 2
+        interval = genome.Interval(chromosome=chrom, start=pos, end=pos).resize(SEQ_LEN_1MB)
+        out = self._client().predict_interval(
+            interval=interval,
+            requested_outputs=[dna_client.OutputType.ATAC, dna_client.OutputType.DNASE,
+                               dna_client.OutputType.CHIP_HISTONE],
+            ontology_terms=[ontology])
+
+        def central(values) -> np.ndarray:
+            arr = np.asarray(values)
+            mid = arr.shape[0] // 2
+            half = max(1, center_bp // 2)
+            return arr[max(0, mid - half):mid + half]
+
+        rec = {"available": True, "chrom": chrom, "bin": int(bin), "ct": ct, "ontology": ontology,
+               "model_version": MODEL_VERSION, "center_bp": center_bp, "key": key,
+               "atac": float(central(out.atac.values).mean()),
+               "dnase": float(central(out.dnase.values).mean())}
+        ch = out.chip_histone
+        md, vals = ch.metadata.reset_index(drop=True), central(ch.values)
+        for mark in _HISTONES:
+            cols = md.index[md["histone_mark"] == mark].to_numpy()
+            rec[mark] = float(vals[:, cols].mean()) if len(cols) else float("nan")
+        self._store(key, rec)
+        return rec
+
+    def contact_map_summary(self, chrom: str, start: int, end: int, ontology: str) -> dict:
+        """3D structural-risk summary (WS-C2): variance + mean of the predicted contact map (cached)."""
+        key = _cache_key("contact", self.assembly, chrom, start, end, ontology)
+        hit = self._load(key)
+        if hit is not None:
+            return hit
+        if not self.available():
+            return {"available": False, "reason": "alphagenome package or key absent", "key": key}
+        from alphagenome.data import genome
+        from alphagenome.models import dna_client
+        interval = genome.Interval(chromosome=chrom, start=start, end=end).resize(SEQ_LEN_1MB)
+        out = self._client().predict_interval(
+            interval=interval, requested_outputs=[dna_client.OutputType.CONTACT_MAPS],
+            ontology_terms=[ontology])
+        import numpy as np
+        m = np.asarray(out.contact_maps.values)
+        rec = {"available": True, "contact_mean": float(m.mean()), "contact_var": float(m.var()),
+               "chrom": chrom, "start": start, "end": end, "ontology": ontology, "key": key}
+        self._store(key, rec)
+        return rec
+
+
+class MeasuredTrackProvider:
+    """The existing measured-ENCODE backbone: reads `phase_1/features/chromatin_{ct}.parquet` per bin.
+
+    Same `tracks()` signature as AlphaGenomeProvider so C2 can compare predicted vs measured on identical
+    bins, and so downstream code can swap providers without branching.
+    """
+
+    _P1 = _ROOT.parent / "phase_1" / "features"
+
+    def __init__(self, ct: str):
+        import pandas as pd
+        self.ct = ct.lower()
+        self._df = pd.read_parquet(self._P1 / f"chromatin_{self.ct}.parquet").set_index(["chrom", "bin"])
+
+    def available(self) -> bool:
+        return True
+
+    def tracks(self, chrom: str, bin: int, ct: str | None = None, **_: object) -> dict:
+        try:
+            row = self._df.loc[(chrom, int(bin))]
+        except KeyError:
+            return {"available": False, "reason": "bin not in measured grid"}
+        return {"available": True, "chrom": chrom, "bin": int(bin), "ct": self.ct,
+                **{t: float(row[t]) for t in TRACK_NAMES if t in row}}
+
+
+def smoke() -> dict:
+    """Lightweight readiness probe used by tests/CLI - reports availability without a live call."""
+    p = AlphaGenomeProvider()
+    return {"package_available": package_available(), "key_present": _resolve_key() is not None,
+            "available": p.available(), "model_version": MODEL_VERSION, "track_names": TRACK_NAMES,
+            "cache_dir": str(_CACHE)}
+
+
+if __name__ == "__main__":  # pragma: no cover
+    print(json.dumps(smoke(), indent=2))

pen_stack/wgenome/safety.py

@@ -0,0 +1,69 @@
+"""Safety layer (Phase 1, Step 1.6) - calibrated genotoxicity-risk model.
+
+Position features -> P(genotoxic) with isotonic calibration and CHROMOSOME-BLOCK cross-validation
+(so adjacent 1 kb bins never leak between train/test). Always reported against the honest baseline:
+distance-to-nearest-oncogene. Output is a calibrated risk per bin.
+"""
+from __future__ import annotations
+
+import lightgbm as lgb
+import numpy as np
+import pandas as pd
+from sklearn.isotonic import IsotonicRegression
+from sklearn.metrics import average_precision_score, roc_auc_score
+from sklearn.model_selection import GroupKFold
+
+from pen_stack.wgenome.features import feature_columns
+
+
+def _blocks(chrom: pd.Series) -> np.ndarray:
+    """Chromosome-block groups for leakage-free CV."""
+    return chrom.astype("category").cat.codes.to_numpy()
+
+
+def train_safety(df: pd.DataFrame, label: str = "genotoxic_cis", n_splits: int = 5,
+                 seed: int = 42) -> dict:
+    feats = feature_columns(df)
+    X = df[feats].astype("float32").fillna(0.0)
+    y = df[label].astype(int).to_numpy()
+    groups = _blocks(df["chrom"])
+
+    gkf = GroupKFold(n_splits=min(n_splits, len(np.unique(groups))))
+    oof = np.zeros(len(df), dtype="float64")
+    for tr, te in gkf.split(X, y, groups):
+        pos = max(1, int(y[tr].sum()))
+        spw = max(1.0, (len(tr) - pos) / pos)   # class imbalance
+        clf = lgb.LGBMClassifier(n_estimators=400, learning_rate=0.03, num_leaves=63,
+                                 subsample=0.8, colsample_bytree=0.8, scale_pos_weight=spw,
+                                 random_state=seed, n_jobs=-1, verbosity=-1)
+        clf.fit(X.iloc[tr], y[tr])
+        raw = clf.predict_proba(X.iloc[te])[:, 1]
+        # isotonic calibration fit on the training fold's OOB-ish raw scores
+        iso = IsotonicRegression(out_of_bounds="clip")
+        raw_tr = clf.predict_proba(X.iloc[tr])[:, 1]
+        iso.fit(raw_tr, y[tr])
+        oof[te] = iso.transform(raw)
+
+    auroc = roc_auc_score(y, oof)
+    auprc = average_precision_score(y, oof)
+
+    # honest baseline: closer to oncogene => riskier
+    base = -df["dist_oncogene"].fillna(df["dist_oncogene"].max()).to_numpy()
+    auroc_base = roc_auc_score(y, base)
+    auprc_base = average_precision_score(y, base)
+
+    # final model on all data (for scoring), + feature importance
+    pos = max(1, int(y.sum()))
+    spw = max(1.0, (len(y) - pos) / pos)
+    final = lgb.LGBMClassifier(n_estimators=400, learning_rate=0.03, num_leaves=63,
+                               subsample=0.8, colsample_bytree=0.8, scale_pos_weight=spw,
+                               random_state=seed, n_jobs=-1, verbosity=-1).fit(X, y)
+    imp = dict(sorted(zip(feats, final.feature_importances_.tolist()),
+                      key=lambda kv: kv[1], reverse=True))
+    return {
+        "n": int(len(df)), "n_pos": int(y.sum()), "features": feats,
+        "auroc_model": float(auroc), "auprc_model": float(auprc),
+        "auroc_baseline": float(auroc_base), "auprc_baseline": float(auprc_base),
+        "auroc_delta": float(auroc - auroc_base),
+        "feature_importance": imp, "model": final, "oof": oof,
+    }

pen_stack/wgenome/structure3d.py

@@ -0,0 +1,168 @@
+"""WS-C3 - 3D structural-risk via AlphaGenome contact-map deltas.
+
+A cassette insertion can rewire 3D contacts and bring a distal enhancer into contact with an oncogene
+promoter (enhancer hijacking). We simulate the insertion with AlphaGenome's `predict_variant` (the cassette
+is the alternate allele - an insertion - so the model applies it to its own reference and handles the
+coordinate shift server-side; no local FASTA needed). We predict the reference and edited 1 Mb contact maps
+and compute:
+
+  * insulation change at the insertion site (diamond insulation score, ref vs edited);
+  * aberrant contact gain between the insertion site and a target oncogene promoter bin.
+
+To isolate the *regulatory* effect from the pure coordinate-shift artifact, every metric is reported for a
+strong-enhancer insert AND a length-matched neutral insert; the strong-minus-neutral difference is the
+signal. Output is a `structural_risk` score + flag with a confidence field.
+
+GATE G-C: this ships as a FLAG WITH CONFIDENCE, never a hard pass/fail. No ground-truth dataset of
+insertion-induced hijacking exists, so this is NOT validated as a predictor - only sanity-checked on known
+enhancer-hijacking loci (TAL1, LMO2, GFI1B, MYC) where a strong-enhancer insert should raise aberrant
+contacts above a matched neutral insert. Contacts are cell-type-specific (default GM12878, EFO:0002784 -
+K562 has no AlphaGenome Hi-C track); insertion changes coordinates in ways the model was not trained on.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import urllib.request
+from pathlib import Path
+
+import numpy as np
+
+from pen_stack.wgenome.providers import SEQ_LEN_1MB, AlphaGenomeProvider
+
+_ROOT = Path(__file__).resolve().parents[2]
+_CACHE = _ROOT / "data" / "alphagenome_cache"
+HIC_ONTOLOGY = "EFO:0002784"   # GM12878 - canonical deep Hi-C; K562 has no AlphaGenome contact track
+CONTACT_BINS = 512             # 1 Mb / 512 ~ 2048 bp per contact bin
+
+
+def _ucsc_ref(chrom: str, pos: int, length: int = 1) -> str:
+    """Reference bases [pos, pos+length) on hg38 via the UCSC REST API (cached on disk)."""
+    key = f"ucsc_{chrom}_{pos}_{length}"
+    f = _CACHE / f"{key}.json"
+    if f.exists():
+        return json.loads(f.read_text(encoding="utf-8"))["dna"].upper()
+    u = (f"https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom={chrom};"
+         f"start={pos};end={pos + length}")
+    d = json.load(urllib.request.urlopen(u))  # noqa: S310
+    _CACHE.mkdir(parents=True, exist_ok=True)
+    f.write_text(json.dumps({"dna": d["dna"]}), encoding="utf-8")
+    return d["dna"].upper()
+
+
+def strong_enhancer_insert(n: int = 1600) -> str:
+    """Simulated strong enhancer: tiled clusters of active-enhancer TF motif cores (ETS/GATA/AP-1/RUNX)."""
+    motif = "GGAAGTGATAAGTGACTCAGGAAGTGACCACA"   # GGAA(ETS) / GATA / TGACTCA(AP-1) / TGTGGT(RUNX-rc)
+    return (motif * (n // len(motif) + 1))[:n]
+
+
+def neutral_insert(n: int = 1600) -> str:
+    """Length-matched neutral insert: low-complexity AT-rich filler (poor regulatory potential)."""
+    return ("ATATATTAATTATAAT" * (n // 16 + 1))[:n]
+
+
+def _contact_matrices(provider: AlphaGenomeProvider, chrom: str, pos: int, insert: str,
+                      ontology: str = HIC_ONTOLOGY):
+    """Reference + edited (insertion) 1 Mb contact matrices via predict_variant."""
+    from alphagenome.data import genome
+    from alphagenome.models import dna_client
+    anchor = _ucsc_ref(chrom, pos, 1)
+    var = genome.Variant(chromosome=chrom, position=pos, reference_bases=anchor,
+                         alternate_bases=anchor + insert)
+    interval = var.reference_interval.resize(SEQ_LEN_1MB)
+    out = provider._client().predict_variant(  # noqa: SLF001
+        interval=interval, variant=var,
+        requested_outputs=[dna_client.OutputType.CONTACT_MAPS], ontology_terms=[ontology])
+    ref = np.asarray(out.reference.contact_maps.values)
+    alt = np.asarray(out.alternate.contact_maps.values)
+    return ref[..., 0] if ref.ndim == 3 else ref, alt[..., 0] if alt.ndim == 3 else alt
+
+
+def insulation_score(mat: np.ndarray, idx: int, w: int = 10) -> float:
+    """Diamond insulation: mean contact in the w x w square straddling position `idx`."""
+    n = mat.shape[0]
+    a, b = max(0, idx - w), min(n, idx + w)
+    if a >= idx or b <= idx:
+        return float("nan")
+    return float(mat[a:idx, idx:b].mean())
+
+
+def _bin_of(offset_bp: int) -> int:
+    """Contact-map bin index for a genomic offset (bp) from the 1 Mb interval centre."""
+    return int(round(CONTACT_BINS / 2 + offset_bp / (SEQ_LEN_1MB / CONTACT_BINS)))
+
+
+def structural_risk(chrom: str, site_pos: int, oncogene_pos: int, ontology: str = HIC_ONTOLOGY,
+                    provider: AlphaGenomeProvider | None = None, offline: bool = False) -> dict:
+    """Strong-enhancer vs neutral insertion at `site_pos`; aberrant contact gain toward `oncogene_pos`."""
+    provider = provider or AlphaGenomeProvider(assembly="hg38")
+    ins_strong, ins_neutral = strong_enhancer_insert(), neutral_insert()
+    key_src = f"struct3d|{chrom}|{site_pos}|{oncogene_pos}|{ontology}|{hashlib.sha256((ins_strong+ins_neutral).encode()).hexdigest()[:8]}"
+    key = hashlib.sha256(key_src.encode()).hexdigest()[:24]
+    cf = _CACHE / f"{key}.json"
+    if cf.exists():
+        return json.loads(cf.read_text(encoding="utf-8"))
+    if offline or not provider.available():
+        return {"available": False, "reason": "offline or AlphaGenome key absent", "key": key}
+
+    site_idx = CONTACT_BINS // 2
+    tgt_idx = _bin_of(oncogene_pos - site_pos)
+    res = {}
+    for label, insert in (("strong_enhancer", ins_strong), ("neutral", ins_neutral)):
+        ref, alt = _contact_matrices(provider, chrom, site_pos, insert, ontology)
+        ins_ref, ins_alt = insulation_score(ref, site_idx), insulation_score(alt, site_idx)
+        t = min(tgt_idx, CONTACT_BINS - 1)
+        contact_ref = float(ref[site_idx, t]) if 0 <= t < CONTACT_BINS else float("nan")
+        contact_alt = float(alt[site_idx, t]) if 0 <= t < CONTACT_BINS else float("nan")
+        res[label] = {"insulation_change": round(ins_alt - ins_ref, 5),
+                      "oncogene_contact_gain": round(contact_alt - contact_ref, 5)}
+    gain_strong = res["strong_enhancer"]["oncogene_contact_gain"]
+    gain_neutral = res["neutral"]["oncogene_contact_gain"]
+    aberrant = gain_strong - gain_neutral
+    out = {"available": True, "chrom": chrom, "site_pos": site_pos, "oncogene_pos": oncogene_pos,
+           "ontology": ontology, "target_bin_offset": tgt_idx - site_idx,
+           "per_insert": res, "aberrant_contact_gain_strong_minus_neutral": round(aberrant, 5),
+           "structural_risk": round(float(max(0.0, aberrant)), 5),
+           "flag": bool(aberrant > 0),
+           "confidence": "heuristic; not a calibrated probability (Gate G-C); sanity-check only",
+           "key": key}
+    _CACHE.mkdir(parents=True, exist_ok=True)
+    cf.write_text(json.dumps(out, default=str), encoding="utf-8")
+    return out
+
+
+# Known enhancer-hijacking loci (hg38) for the qualitative sanity check. Insertion site placed ~120 kb from
+# the oncogene promoter (within a 1 Mb window / typical TAD reach).
+HIJACK_LOCI = {
+    "TAL1":  {"chrom": "chr1",  "oncogene_pos": 47_209_257, "site_pos": 47_209_257 - 120_000},
+    "LMO2":  {"chrom": "chr11", "oncogene_pos": 33_859_520, "site_pos": 33_859_520 - 120_000},
+    "GFI1B": {"chrom": "chr9",  "oncogene_pos": 132_990_996, "site_pos": 132_990_996 - 120_000},
+    "MYC":   {"chrom": "chr8",  "oncogene_pos": 127_735_434, "site_pos": 127_735_434 - 120_000},
+}
+
+
+def sanity(ontology: str = HIC_ONTOLOGY, offline: bool = False, out: str | Path | None = None) -> dict:
+    """C3 sanity check across the known hijacking loci: strong-enhancer insert should raise aberrant
+    contacts above a matched neutral insert at more loci than not (qualitative, not a validated predictor)."""
+    provider = AlphaGenomeProvider(assembly="hg38")
+    rows = {}
+    for name, c in HIJACK_LOCI.items():
+        r = structural_risk(c["chrom"], c["site_pos"], c["oncogene_pos"], ontology, provider, offline)
+        rows[name] = r
+    scored = [v["aberrant_contact_gain_strong_minus_neutral"] for v in rows.values() if v.get("available")]
+    report = {"available": bool(scored), "ontology": ontology, "n_loci": len(rows),
+              "n_strong_gt_neutral": int(sum(1 for s in scored if s > 0)),
+              "per_locus": {k: (v.get("aberrant_contact_gain_strong_minus_neutral") if v.get("available")
+                                else v.get("reason")) for k, v in rows.items()},
+              "sanity_pass": bool(scored and sum(1 for s in scored if s > 0) > len(scored) / 2),
+              "scope": "qualitative sanity check only; ships as a flag with confidence (Gate G-C), never "
+                       "a hard pass/fail; contacts are cell-type-specific (GM12878)."}
+    if out:
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        Path(out).write_text(json.dumps({"loci": rows, "summary": report}, indent=2, default=str),
+                             encoding="utf-8")
+    return report
+
+
+if __name__ == "__main__":  # pragma: no cover
+    print(json.dumps(sanity(out=_ROOT / "out" / "structure3d_sanity.json"), indent=2, default=str))

pen_stack/wgenome/writability.py

@@ -0,0 +1,72 @@
+"""Writability integration (Phase 1, Step 1.9).
+
+Combines the three layers into a transparent, DECOMPOSABLE per-locus writability profile (components
+kept visible; never collapsed into one opaque number):
+
+    writability = f(safety, durability, reachability)
+
+- safety:      1 - P(genotoxic) from the safety model (calibrated risk; safe-harbour discriminating).
+- durability:  P(durable | epigenome) = 1 - P(silenced), the mouse-trained conditional function APPLIED
+               to the human epigenome's histone marks (the cell-type-transfer the design hinges on).
+- reachability: WT-KB writer set + tier (Tier-1 reprogrammable writers are broadly available at 1 kb;
+               fine-grained site choice is a design-time concern handled by the Planner).
+"""
+from __future__ import annotations
+
+import pickle
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from pen_stack.wgenome.features import feature_columns
+
+
+def load_pickle(path: str):
+    with open(path, "rb") as fh:
+        return pickle.load(fh)
+
+
+def apply_safety(matrix: pd.DataFrame, safety_model) -> np.ndarray:
+    feats = feature_columns(matrix)
+    p_genotoxic = safety_model.predict_proba(matrix[feats].astype("float32").fillna(0.0))[:, 1]
+    return 1.0 - p_genotoxic   # safety = 1 - risk
+
+
+def apply_durability(matrix: pd.DataFrame, dur_models: dict) -> tuple[np.ndarray, np.ndarray]:
+    """Apply the mouse-trained conditional function to the human epigenome's histone marks.
+
+    ROBUST to partial chromatin panels (e.g. CD34+ HSPC lacks some tracks): every model feature is
+    provided in the trained order; tracks absent from this cell type are passed as NaN, which LightGBM
+    handles natively. This is the 'graceful degradation under partial annotation' behaviour, by design.
+    """
+    X = pd.DataFrame(index=matrix.index)
+    for f in dur_models["features"]:                 # exact training feature set + order
+        X[f] = matrix[f].astype("float32") if f in matrix.columns else np.nan
+    expr = dur_models["reg"].predict(X)
+    p_silenced = dur_models["clf"].predict_proba(X)[:, 1]
+    return expr, 1.0 - p_silenced     # predicted expression, P(durable)
+
+
+def build_writability(matrix: pd.DataFrame, safety_model, dur_models: dict,
+                      w_safety: float = 0.5, w_durability: float = 0.5,
+                      out_parquet: str | None = None) -> pd.DataFrame:
+    out = matrix[["chrom", "bin"]].copy()
+    out["safety"] = apply_safety(matrix, safety_model)
+    expr, p_durable = apply_durability(matrix, dur_models)
+    out["pred_expression"] = expr
+    out["p_durable"] = p_durable
+    # reachability: Tier-1 reprogrammable writers broadly available at locus level (honest annotation)
+    out["reachable_tier1"] = "bridge_IS110;Cas9;Cas12a"
+    # decomposable composite (documented weights; components above stay visible)
+    out["writability"] = w_safety * out["safety"] + w_durability * out["p_durable"]
+    if out_parquet:
+        Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+        out.to_parquet(out_parquet, index=False)
+    return out
+
+
+def rank_loci_near(writ_df: pd.DataFrame, chrom: str, start: int, end: int, k: int = 10) -> pd.DataFrame:
+    """Inverse query seed (Phase-3 Planner): rank writable bins in a window."""
+    w = writ_df.query("chrom == @chrom and bin*1000 >= @start and bin*1000 <= @end")
+    return w.sort_values("writability", ascending=False).head(k)