pen-stack 0.1.0__py3-none-any.whl

pen_stack/wgenome/providers.py

@@ -0,0 +1,278 @@
+"""External sequence-to-function providers.
+
+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)
+
+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 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 score_variant(self, chrom: str, position: int, ref: str, alt: str, ontology: str | None = None,
+                      output: str = "RNA_SEQ", offline: bool = False) -> dict:
+        """Variant-effect magnitude via AlphaGenome's `score_variant` (REF vs ALT, recommended scorer, cached).
+
+        Returns a scalar effect summary (max & mean |score| over the predicted tracks) for the requested output
+        type, a real regulatory variant-effect prediction, not a fabricated tier. Cached by (variant, output,
+        ontology). When the package/key is absent it reports `available=False` (the oracle then defers)."""
+        key = _cache_key("variant", self.assembly, MODEL_VERSION, chrom, position, ref, alt, output, ontology)
+        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, variant_scorers
+        variant = genome.Variant(chromosome=chrom, position=int(position),
+                                 reference_bases=ref, alternate_bases=alt)
+        interval = variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)
+        scorer = variant_scorers.RECOMMENDED_VARIANT_SCORERS[output]
+        scores = self._client().score_variant(interval=interval, variant=variant, variant_scorers=[scorer])
+        x = np.asarray(scores[0].X, dtype=float) # (n_tracks/genes, ...) effect scores
+        finite = x[np.isfinite(x)]
+        rec = {"available": True, "output": output, "scorer": str(scorer),
+               "effect_max_abs": float(np.abs(finite).max()) if finite.size else 0.0,
+               "effect_mean_abs": float(np.abs(finite).mean()) if finite.size else 0.0,
+               "n_scores": int(finite.size), "chrom": chrom, "position": int(position),
+               "ref": ref, "alt": alt, "ontology": ontology, "model_version": MODEL_VERSION, "key": key}
+        self._store(key, rec)
+        return rec
+
+    def contact_map_summary(self, chrom: str, start: int, end: int, ontology: str) -> dict:
+        """3D structural-risk summary: 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 - 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 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)
+
+    # 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,212 @@
+"""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 11 known
+enhancer-hijacking oncogenes (TAL1/LMO1/LMO2/TLX3/BCL11B/MYB in T-ALL, MECOM-GATA2 in AML, MYCN in
+neuroblastoma, 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)))
+
+
+# calibrated confidence and abstention for the qualitative 3D flag. No calibrated probability is
+# claimed. The only computable confidence signal is the MAGNITUDE of the strong-minus-neutral
+# separation: when it is within +/-ABSTAIN_EPS the strong and neutral inserts are indistinguishable, so the
+# flag ABSTAINS rather than emit a direction it cannot justify. Larger separations are a low-confidence
+# qualitative flag, never a calibrated risk.
+ABSTAIN_EPS = 0.01
+
+
+def uq4_confidence(aberrant: float) -> dict:
+    """Structured confidence/abstention for the 3D structural-risk flag (UQ4). Heuristic, not calibrated."""
+    mag = abs(float(aberrant))
+    if mag <= ABSTAIN_EPS:
+        level, abstain = "abstain", True
+    elif mag <= 0.05:
+        level, abstain = "low", False
+    else:
+        level, abstain = "qualitative_flag", False
+    return {"calibrated": False, "level": level, "abstain": abstain,
+            "epistemic_status": "not-computable" if abstain else "grounded-extrapolating",
+            "basis": f"strong-minus-neutral separation magnitude {mag:.4f} vs abstain_eps {ABSTAIN_EPS}",
+            "scope": "qualitative flag with confidence; no calibrated probability, no coverage "
+                     "guarantee - no ground-truth enhancer-hijacking dataset exists to calibrate against"}
+
+
+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():
+        cached = json.loads(cf.read_text(encoding="utf-8"))
+        if cached.get("available") and not isinstance(cached.get("confidence"), dict):
+            # upgrade legacy string-confidence cache entries to the UQ4 structured form (no recompute)
+            cached["confidence"] = uq4_confidence(
+                cached.get("aberrant_contact_gain_strong_minus_neutral", 0.0))
+        return cached
+    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": uq4_confidence(aberrant),
+           "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 oncogenes (hg38) for the qualitative sanity check. Insertion site placed ~120 kb
+# from the oncogene promoter (within a 1 Mb window / typical TAD reach). Scaled from 4 to 11 loci;
+# oncogene_pos for the added loci is the GENCODE TSS (data/curated/gene_coords.parquet) - no hand-transcribed
+# coordinates. These are canonical enhancer-hijacking oncogenes from the leukaemia/neuroblastoma literature
+# (e.g. TAL1/LMO1/LMO2/TLX3/BCL11B/MYB in T-ALL, MECOM-GATA2 in AML, MYCN in neuroblastoma).
+def _hj(chrom: str, pos: int) -> dict:
+    return {"chrom": chrom, "oncogene_pos": pos, "site_pos": pos - 120_000}
+
+
+HIJACK_LOCI = {
+    "TAL1": _hj("chr1", 47_209_257),
+    "LMO2": _hj("chr11", 33_859_520),
+    "GFI1B": _hj("chr9", 132_990_996),
+    "MYC": _hj("chr8", 127_735_434),
+    "MYCN": _hj("chr2", 15_940_550), # neuroblastoma
+    "MECOM": _hj("chr3", 169_083_499), # AML 3q26 (GATA2 distal enhancer hijacking)
+    "GATA2": _hj("chr3", 128_479_427), # AML inv(3)/t(3;3)
+    "LMO1": _hj("chr11", 8_224_309), # T-ALL
+    "BCL11B": _hj("chr14", 99_169_287), # T-ALL (t(5;14))
+    "MYB": _hj("chr6", 135_181_308), # T-ALL
+    "TLX3": _hj("chr5", 171_309_248), # T-ALL (HOX11L2, t(5;14) BCL11B enhancer)
+}
+
+
+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, 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))