pen-stack 0.1.0__py3-none-any.whl

pen_stack/build/protocol.py

@@ -0,0 +1,82 @@
+"""Safety-gated protocol export, the digital→physical bridge.
+
+A cleared, legal design becomes a runnable protocol, emitted as a reviewed DRAFT carrying its immune-risk
+profile in the metadata, never auto-run, and refused outright if the safety gate flags it. Protocols are
+drafts for human/lab review, never auto-executed.
+"""
+from __future__ import annotations
+
+import json
+
+from pen_stack.verify import verify
+
+_TARGETS = ("opentrons", "pylabrobot", "cloudlab")
+
+
+class ProtocolExportError(RuntimeError):
+    """Raised when a design cannot be exported (safety-refused or illegal)."""
+
+
+def _to_protocol_ir(design: dict, experiment: dict) -> dict:
+    """Minimal, platform-agnostic protocol intermediate representation (a DRAFT plan, not lab-tuned steps)."""
+    return {
+        "assay": experiment.get("assay", "cassette_expression_readout"),
+        "cell_type": design.get("cell_type", "k562"),
+        "delivery_vehicle": design.get("delivery_vehicle"),
+        "writer_family": design.get("writer_family"),
+        "cargo_bp": design.get("cargo_bp"),
+        "round": experiment.get("round"),
+        "steps": ["seed cells", "prepare delivery vehicle + cargo", "deliver", "incubate", "assay readout"],
+    }
+
+
+def _emit_opentrons(ir: dict) -> str:
+    return (f"# Opentrons Python Protocol API v2 (DRAFT)\nmetadata = {{'apiLevel': '2.15'}}\n"
+            f"def run(protocol):\n"
+            f" # assay: {ir['assay']} | cell_type: {ir['cell_type']} | vehicle: {ir['delivery_vehicle']}\n"
+            f" # steps: {ir['steps']}\n"
+            f" pass # DRAFT - human/lab review required; fill in labware + liquid handling\n")
+
+
+def _emit_pylabrobot(ir: dict) -> str:
+    return (f"# PyLabRobot protocol (DRAFT)\nfrom pylabrobot.liquid_handling import LiquidHandler\n"
+            f"async def run(lh: LiquidHandler):\n"
+            f" # assay: {ir['assay']} | vehicle: {ir['delivery_vehicle']} | steps: {ir['steps']}\n"
+            f" ... # DRAFT - human/lab review required\n")
+
+
+def _emit_cloudlab(ir: dict) -> str:
+    return ("# Cloud-lab protocol request (DRAFT)\n"
+            + json.dumps({"assay": ir["assay"], "cell_type": ir["cell_type"], "steps": ir["steps"],
+                          "status": "DRAFT - human/lab review required"}, indent=2) + "\n")
+
+
+_EMITTERS = {"opentrons": _emit_opentrons, "pylabrobot": _emit_pylabrobot, "cloudlab": _emit_cloudlab}
+
+
+def _stamp_draft(code: str, *, provenance: dict) -> str:
+    header = ("# ============================================================\n"
+              "# DRAFT, human/lab review required. NOT auto-executed.\n"
+              f"# provenance: {json.dumps(provenance, default=str)}\n"
+              "# ============================================================\n")
+    return header + code
+
+
+def export_protocol(design: dict, experiment: dict, *, target: str = "opentrons",
+                    actor: str = "anonymous") -> str:
+    """Cleared design + experiment -> a runnable protocol DRAFT, with the immune-risk profile in the
+    metadata. HARD GATE: refuses anything the safety gate flags, or any illegal design."""
+    if target not in _TARGETS:
+        raise ProtocolExportError(f"unknown target {target!r}; choose from {_TARGETS}")
+    v = verify(dict(design), actor=actor)
+    if v.safety is not None and v.safety.decision == "refuse":
+        raise ProtocolExportError(f"export blocked by safety gate: {v.safety.reason}")
+    if v.legal is not True:
+        raise ProtocolExportError(f"export blocked: design not legal ({v.summary()})")
+    ir = _to_protocol_ir(design, experiment)
+    code = _EMITTERS[target](ir)
+    return _stamp_draft(code, provenance={
+        "verify": v.summary(), "safety": (v.safety.decision if v.safety else None),
+        "immune_profile": v.immune_profile, # metadata travels with the protocol
+        "target": target, "actor": actor,
+        "note": "immune profile is a screen carrying its known-unknowns, not a patient prediction"})

pen_stack/build/simlab.py

@@ -0,0 +1,30 @@
+"""Simulated-lab harness, run the closed loop without hardware.
+
+Executes a protocol in silico: samples an "observed" result from the twin + measurement noise, clearly
+labelled SIMULATED. This lets the closed loop run end-to-end before any hardware exists. Sim outcomes
+inherit the twin's limits and NEVER enter the curated world-model as measured truth, they are for development /
+loop-validation only.
+"""
+from __future__ import annotations
+
+import random
+
+
+def run_simulated(protocol_ir: dict, design: dict, cell_state: str, *, seed: int = 0) -> dict:
+    """Execute a protocol in silico: sample an 'observed' readout from the twin + measurement noise. Labelled
+    SIMULATED; the loop (export -> sim-run -> ingest) completes without a wet lab."""
+    from pen_stack.twin.outcome import predict_outcome
+    out = predict_outcome(design, cell_state)
+    truth = out["predicted_outcome"]
+    rng = random.Random(seed)
+    base = truth.get("relative_expression")
+    readout = None if base is None else round(base + rng.gauss(0.0, 0.05), 4)
+    return {
+        "assay": protocol_ir.get("assay", "cassette_expression_readout"),
+        "readout": readout,
+        "units": truth.get("units"),
+        "design_id": design.get("design_id", "design:sim"),
+        "confidence": out.get("interval"),
+        "provenance": {"source": "simlab", "seed": seed, "label": "SIMULATED",
+                       "note": "sampled from the twin + measurement noise; NOT measured truth"},
+    }

pen_stack/cli.py

@@ -0,0 +1,126 @@
+"""PEN-STACK unified CLI (subcommands: atlas, score, writable, crosslink, monitor).
+
+One entry point - ``pen-stack`` - over the whole stack. Heavy data (the writability atlas) is
+loaded lazily and degrades gracefully when absent, so ``info`` / ``atlas`` work from a clean install.
+"""
+from __future__ import annotations
+
+import click
+
+from pen_stack import __version__
+
+
+@click.group()
+@click.version_option(__version__, prog_name="pen-stack")
+def main():
+    """PEN-STACK - open infrastructure for genome writing."""
+
+
+@main.command()
+def info():
+    """Show stack status and module map."""
+    click.echo(f"PEN-STACK v{__version__}")
+    click.echo("Pillar B (flagship): wgenome - Writable Genome (safety x durability x reachability)")
+    click.echo("Pillar A (companion): atlas, mech, score - Writer Atlas + WT-KB")
+    click.echo("Engine: planner - Write Planner (inverse design)")
+    click.echo("Beachhead: bridge - bridge-recombinase off-target engine")
+    click.echo("Services: monitor, rag, agent, ui, server")
+
+
+@main.command()
+@click.option("--family", default=None, help="Filter to one writer family.")
+@click.option("--coverage", is_flag=True, help="Show per-family coverage + confidence breakdown.")
+@click.option("--limit", default=10, help="Max rows to print.")
+def atlas(family, coverage, limit):
+    """Query the Writer Atlas."""
+    import pandas as pd
+
+    from pen_stack.atlas.crosslink import _ATLAS
+    df = pd.read_parquet(_ATLAS)
+    if coverage:
+        cov = (df.groupby("family")
+                 .agg(n=("representative_system", "size"),
+                      measured=("confidence", lambda s: (s == "measured").sum()),
+                      tier=("reachability_tier", "first"))
+                 .reset_index())
+        click.echo(cov.to_string(index=False))
+        click.echo(f"\nTOTAL systems: {len(df):,} across {df['family'].nunique()} families")
+        return
+    if family:
+        df = df[df["family"] == family]
+    cols = [c for c in ["representative_system", "family", "confidence", "deliv_class",
+                        "readiness", "reachability_tier"] if c in df.columns]
+    click.echo(df[cols].head(limit).to_string(index=False))
+
+
+@main.command()
+@click.option("--gene", required=True, help="Target gene symbol.")
+@click.option("--ct", default="k562", help="Cell type (k562/hepg2/hspc).")
+@click.option("--top", default=10, help="Top writable bins to show.")
+def writable(gene, ct, top):
+    """Rank writable loci overlapping a gene."""
+    from pen_stack.atlas.crosslink import loci_for_gene
+    try:
+        g = loci_for_gene(gene, ct)
+    except FileNotFoundError as e:
+        raise click.ClickException(f"writability atlas not available: {e}") from e
+    if g.empty:
+        click.echo(f"No writable bins found for {gene} in {ct}.")
+        return
+    click.echo(g[["chrom", "bin", "safety", "p_durable", "writability"]].head(top).to_string(index=False))
+
+
+@main.command()
+@click.option("--family", help="Writer family -> ranked reachable loci.")
+@click.option("--chrom", help="Locus chrom (with --bin) -> reachable writers.")
+@click.option("--bin", "bin_idx", type=int, help="Locus 1kb bin index.")
+@click.option("--ct", default="k562")
+@click.option("--top", default=10)
+def crosslink(family, chrom, bin_idx, ct, top):
+    """Writer<->locus cross-link queries."""
+    from pen_stack.atlas import crosslink as cl
+    try:
+        if family:
+            click.echo(cl.loci_for_writer(family, ct, top=top).to_string(index=False))
+        elif chrom and bin_idx is not None:
+            click.echo(cl.writers_for_locus(chrom, bin_idx, ct).head(top).to_string(index=False))
+        else:
+            raise click.UsageError("provide --family OR (--chrom and --bin)")
+    except FileNotFoundError as e:
+        raise click.ClickException(f"writability atlas not available: {e}") from e
+
+
+@main.command()
+@click.option("--gene", required=True, help="Target gene symbol.")
+@click.option("--intent", required=True,
+              type=click.Choice(["safe_harbour_insertion", "knock_in_with_disruption",
+                                 "high_durability_insertion", "regulatory_excision", "repeat_excision"]))
+@click.option("--cargo-bp", default=2000, help="Payload size (bp).")
+@click.option("--ct", default="k562", help="Cell type (k562/hepg2/hspc).")
+@click.option("--k", default=3, help="Number of ranked plans.")
+def plan(gene, intent, cargo_bp, ct, k):
+    """Write Planner: goal + edit_intent -> ranked, traceable plans."""
+    from pen_stack.planner.optimize import EditIntent
+    from pen_stack.planner.pipeline import plan_write
+    from pen_stack.planner.report import render_plans
+    try:
+        plans = plan_write(gene, EditIntent(intent), cargo_bp, ct, k=k)
+    except FileNotFoundError as e:
+        raise click.ClickException(f"writability atlas not available: {e}") from e
+    click.echo(render_plans(plans))
+
+
+@main.command()
+@click.option("--since", default="2026-01-01", help="Earliest publication date (YYYY-MM-DD).")
+@click.option("--back-test", is_flag=True, help="Run the ISPpu10 back-test window.")
+def monitor(since, back_test):
+    """Run the living-literature monitor (Europe PMC scan -> curation queue)."""
+    from pen_stack.monitor.run import run_monitor
+    res = run_monitor(since=since, back_test=back_test)
+    click.echo(f"Monitor: {res['n_hits']} hits, {res['n_candidates']} candidates -> {res['queue']}")
+    if res.get("isppu10_found") is not None:
+        click.echo(f"ISPpu10 back-test: {'FOUND' if res['isppu10_found'] else 'not found'}")
+
+
+if __name__ == "__main__":
+    main()

pen_stack/data/__init__.py

@@ -0,0 +1 @@
+"""pen_stack.data - see PEN-STACK program doc."""

pen_stack/data/encode.py

@@ -0,0 +1,84 @@
+"""ENCODE REST resolver.
+
+Resolves released hg38 bigWig SIGNAL files for a (biosample, assay/target) pair via the ENCODE
+Portal REST API - so we never hard-code possibly-wrong file accessions. Returns accession + href.
+"""
+from __future__ import annotations
+
+import requests
+
+ENCODE = "https://www.encodeproject.org"
+HEADERS = {"accept": "application/json"}
+
+# preferred processed signal output per assay (fold-change over control where available)
+_PREF_OUTPUT = [
+    "fold change over control",
+    "signal p-value",
+    "read-depth normalized signal",
+    "signal",
+]
+
+
+def _search(params: dict) -> list[dict]:
+    r = requests.get(f"{ENCODE}/search/", params=params, headers=HEADERS, timeout=60)
+    if r.status_code == 404:
+        return [] # ENCODE returns 404 for zero-result searches with some param combos
+    r.raise_for_status()
+    return r.json().get("@graph", [])
+
+
+def find_bigwig(biosample: str, assay_title: str, target: str | None = None,
+                assembly: str = "GRCh38") -> dict | None:
+    """Find one released bigWig signal file for a biosample + assay (+ histone target).
+
+    biosample e.g. 'K562'; assay_title e.g. 'Histone ChIP-seq' / 'ATAC-seq' / 'DNase-seq';
+    target e.g. 'H3K27ac' (None for ATAC/DNase).
+    """
+    params = {
+        "type": "File",
+        "file_format": "bigWig",
+        "output_type": _PREF_OUTPUT,
+        "assembly": assembly,
+        "status": "released",
+        "biosample_ontology.term_name": biosample,
+        "assay_title": assay_title,
+        "format": "json",
+        "limit": "50",
+    }
+    if target:
+        params["target.label"] = target
+    files = _search(params)
+    if not files:
+        return None
+    # rank by preferred output_type order, prefer non-isogenic-replicate consensus where present
+    def rank(f):
+        ot = f.get("output_type", "")
+        return _PREF_OUTPUT.index(ot) if ot in _PREF_OUTPUT else len(_PREF_OUTPUT)
+    f = sorted(files, key=rank)[0]
+    return {"accession": f["accession"], "href": ENCODE + f["href"],
+            "output_type": f.get("output_type"), "assembly": assembly,
+            "biosample": biosample, "assay": assay_title, "target": target}
+
+
+# default track panel per the prereg (durability features)
+DEFAULT_PANEL = [
+    ("ATAC-seq", None),
+    ("DNase-seq", None),
+    ("Histone ChIP-seq", "H3K27ac"),
+    ("Histone ChIP-seq", "H3K4me1"),
+    ("Histone ChIP-seq", "H3K4me3"),
+    ("Histone ChIP-seq", "H3K9me3"),
+    ("Histone ChIP-seq", "H3K27me3"),
+]
+
+
+def resolve_panel(biosample: str, panel=DEFAULT_PANEL, assembly: str = "GRCh38") -> dict[str, dict]:
+    """Return {track_name: file_record} for the panel, skipping assays with no released bigWig.
+    Partial panels are returned as-is (e.g. a cell type lacking some histone marks) - graceful."""
+    out = {}
+    for assay, target in panel:
+        rec = find_bigwig(biosample, assay, target, assembly=assembly)
+        name = target or assay.split("-")[0].lower() # H3K27ac / atac / dnase
+        if rec:
+            out[name] = rec
+    return out

pen_stack/data/genome.py

@@ -0,0 +1,71 @@
+"""hg38 genome scaffolding.
+
+Fetches hg38 chromosome sizes and builds the canonical 1 kb bin grid (autosomes + X) that every
+feature store is keyed on. Pure-CPU, small; runs in any container.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+UCSC_CHROM_SIZES = "https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes"
+MAIN_CHROMS = [f"chr{i}" for i in range(1, 23)] + ["chrX"]
+BIN_BP = 1000
+
+
+def fetch_chrom_sizes(out_tsv: str | Path, url: str = UCSC_CHROM_SIZES,
+                      chroms: list[str] = MAIN_CHROMS) -> dict[str, int]:
+    txt = requests.get(url, timeout=60).text
+    sizes = {}
+    for line in txt.splitlines():
+        if not line.strip():
+            continue
+        c, n = line.split("\t")[:2]
+        if c in chroms:
+            sizes[c] = int(n)
+    sizes = {c: sizes[c] for c in chroms if c in sizes} # canonical order
+    Path(out_tsv).parent.mkdir(parents=True, exist_ok=True)
+    Path(out_tsv).write_text("".join(f"{c}\t{n}\n" for c, n in sizes.items()))
+    return sizes
+
+
+def build_bin_grid(chrom_sizes: dict[str, int], out_parquet: str | Path | None = None,
+                   bin_bp: int = BIN_BP) -> pd.DataFrame:
+    rows = []
+    for c, n in chrom_sizes.items():
+        nbins = n // bin_bp
+        starts = range(0, nbins * bin_bp, bin_bp)
+        rows.append(pd.DataFrame({"chrom": c, "start": starts}))
+    grid = pd.concat(rows, ignore_index=True)
+    grid["end"] = grid["start"] + bin_bp
+    grid["bin"] = grid["start"] // bin_bp
+    if out_parquet:
+        Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+        grid.to_parquet(out_parquet, index=False)
+    return grid
+
+
+def load_chrom_sizes(tsv: str | Path) -> dict[str, int]:
+    out = {}
+    for line in Path(tsv).read_text().splitlines():
+        if line.strip():
+            c, n = line.split("\t")[:2]
+            out[c] = int(n)
+    return out
+
+
+def main() -> None:
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--sizes-out", default="/data/raw/hg38.chrom.sizes")
+    ap.add_argument("--grid-out", default="/data/features/bin_grid_1kb.parquet")
+    a = ap.parse_args()
+    sizes = fetch_chrom_sizes(a.sizes_out)
+    grid = build_bin_grid(sizes, a.grid_out)
+    print(f"chroms={len(sizes)} total_bins={len(grid)} -> {a.grid_out}")
+
+
+if __name__ == "__main__":
+    main()

pen_stack/data/ingest_chromatin.py

@@ -0,0 +1,119 @@
+"""Chromatin feature store.
+
+Resolves the ENCODE bigWig panel for a cell type, downloads tracks IN PARALLEL, bins each to the
+canonical 1 kb grid (mean signal per bin) IN PARALLEL across cores, merges into one feature-store
+parquet, and deletes the raw bigWigs (500 GB discipline). Run in Docker on the VM.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pyBigWig
+import requests
+
+from pen_stack.data.encode import resolve_panel
+from pen_stack.data.genome import MAIN_CHROMS, load_chrom_sizes
+
+BIN_BP = 1000
+
+
+def download(href: str, dest: str) -> str:
+    dest = str(dest)
+    if os.path.exists(dest) and os.path.getsize(dest) > 0:
+        return dest
+    Path(dest).parent.mkdir(parents=True, exist_ok=True)
+    with requests.get(href, stream=True, timeout=900) as r:
+        r.raise_for_status()
+        with open(dest, "wb") as fh:
+            for chunk in r.iter_content(chunk_size=1 << 20):
+                fh.write(chunk)
+    return dest
+
+
+def bin_one(args) -> tuple[str, pd.DataFrame]:
+    """Bin one bigWig to 1 kb mean per bin (module-level for ProcessPool picklability)."""
+    name, path, sizes = args
+    bw = pyBigWig.open(path)
+    bw_chroms = set(bw.chroms().keys())
+    frames = []
+    for c in MAIN_CHROMS:
+        if c not in sizes:
+            continue
+        n = sizes[c] // BIN_BP
+        key = c if c in bw_chroms else c.replace("chr", "")
+        if key not in bw_chroms:
+            frames.append(pd.DataFrame({"chrom": c, "bin": range(n), name: np.zeros(n, "float32")}))
+            continue
+        vals = bw.stats(key, 0, n * BIN_BP, nBins=n, type="mean")
+        v = np.array([0.0 if x is None else float(x) for x in vals], dtype="float32")
+        frames.append(pd.DataFrame({"chrom": c, "bin": range(n), name: v}))
+    bw.close()
+    return name, pd.concat(frames, ignore_index=True)
+
+
+def build_feature_store(biosample: str, chrom_sizes_tsv: str, raw_dir: str, out_parquet: str,
+                        max_dl: int = 7, max_bin: int = 7) -> pd.DataFrame:
+    sizes = load_chrom_sizes(chrom_sizes_tsv)
+    panel = resolve_panel(biosample)
+    print(f"[{biosample}] resolved tracks: {list(panel.keys())}", flush=True)
+    if not panel:
+        raise SystemExit(f"no ENCODE bigWig tracks resolved for {biosample}")
+
+    # 1) parallel download
+    paths = {}
+    with ThreadPoolExecutor(max_workers=max_dl) as ex:
+        futs = {ex.submit(download, rec["href"],
+                          os.path.join(raw_dir, f"{biosample}_{name}_{rec['accession']}.bigWig")): name
+                for name, rec in panel.items()}
+        for fut in futs:
+            name = futs[fut]
+            paths[name] = fut.result()
+            print(f" downloaded {name}", flush=True)
+
+    # 2) parallel bin
+    binned = {}
+    with ProcessPoolExecutor(max_workers=max_bin) as ex:
+        for name, df in ex.map(bin_one, [(n, paths[n], sizes) for n in panel]):
+            binned[name] = df
+            print(f" binned {name}", flush=True)
+
+    base = None
+    for name in panel:
+        base = binned[name] if base is None else base.merge(binned[name], on=["chrom", "bin"])
+    base["biosample"] = biosample
+
+    # 3) clean raws
+    for p in paths.values():
+        try:
+            os.remove(p)
+        except OSError:
+            pass
+
+    Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+    base.to_parquet(out_parquet, index=False)
+    pd.DataFrame([{"track": n, "accession": panel[n]["accession"],
+                   "output_type": panel[n]["output_type"]} for n in panel]
+                 ).to_csv(out_parquet.replace(".parquet", "_manifest.csv"), index=False)
+    return base
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--biosample", required=True)
+    ap.add_argument("--sizes", default="/data/raw/hg38.chrom.sizes")
+    ap.add_argument("--raw-dir", default="/data/raw/encode")
+    ap.add_argument("--out", default=None)
+    a = ap.parse_args()
+    out = a.out or f"/data/features/chromatin_{a.biosample.lower()}.parquet"
+    df = build_feature_store(a.biosample, a.sizes, a.raw_dir, out)
+    cols = [c for c in df.columns if c not in ("chrom", "bin", "biosample")]
+    print(f"feature store {out}: bins={len(df)} tracks={cols}", flush=True)
+
+
+if __name__ == "__main__":
+    main()

pen_stack/data/ingest_integration.py

@@ -0,0 +1,112 @@
+"""Integration-propensity features.
+
+Builds per-1 kb-bin retroviral integration density from VISDB integration tables (HIV, HTLV, MLV;
+coordinates already lifted to hg38 in VISDB). Integration propensity reflects accessible/active
+chromatin and is a feature for both the safety layer and "where insertions land".
+
+NOTE (scope): VISDB's MLV set is tiny (~32 sites); the large >3.7M MLV-in-K562/HepG2 sets
+referenced in the plan live in specific papers'/GEO supplements and are sourced separately. The
+GENOTOXIC labels (clonal-outcome CIS) come from the clinical gene list - this module
+supplies the integration-DENSITY feature, not the danger label.
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from pen_stack.data.genome import MAIN_CHROMS
+
+BIN_BP = 1000
+
+
+def load_visdb(csv_dir: str) -> pd.DataFrame:
+    frames = []
+    for f in sorted(glob.glob(os.path.join(csv_dir, "*.csv"))):
+        virus = Path(f).stem
+        df = pd.read_csv(f, dtype=str)
+        cols = {c.lower().strip(): c for c in df.columns}
+        chrom_c = cols.get("human chromosome")
+        start_c = cols.get("hg38_start")
+        if not chrom_c or not start_c:
+            continue
+        sub = pd.DataFrame({
+            "chrom": df[chrom_c].astype(str).map(lambda c: c if c.startswith("chr") else f"chr{c}"),
+            "pos": pd.to_numeric(df[start_c], errors="coerce"),
+            "virus": virus,
+        }).dropna(subset=["pos"])
+        frames.append(sub)
+    out = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame(columns=["chrom", "pos", "virus"])
+    out = out[out["chrom"].isin(MAIN_CHROMS)].copy()
+    out["pos"] = out["pos"].astype(int)
+    return out
+
+
+def density_per_bin(integ: pd.DataFrame, bin_grid: str, out_parquet: str) -> pd.DataFrame:
+    grid = pd.read_parquet(bin_grid)[["chrom", "bin"]]
+    integ["bin"] = integ["pos"] // BIN_BP
+    dens = integ.groupby(["chrom", "bin"]).size().rename("integ_density").reset_index()
+    out = grid.merge(dens, on=["chrom", "bin"], how="left")
+    out["integ_density"] = out["integ_density"].fillna(0).astype("int32")
+    out["integ_log_density"] = np.log1p(out["integ_density"]).astype("float32")
+    Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+    out.to_parquet(out_parquet, index=False)
+    return out
+
+
+def lafave_density(bed_gz: str, chain_file: str, bin_grid: str, out_parquet: str) -> pd.DataFrame:
+    """Cell-type-specific MLV integration density from a LaFave et al. 2014 BED (hg19 -> hg38 lift).
+
+    The LaFave K562/HepG2 MLV integration BEDs are on hg19; lift each site to hg38 with the UCSC
+    chain, then bin to 1 kb. This is the plan's >3.7M MLV-in-K562/HepG2 supervision (Bushman/NHGRI).
+    """
+    from pyliftover import LiftOver
+    lo = LiftOver(chain_file)
+    sites = []
+    with __import__("gzip").open(bed_gz, "rt") as fh:
+        for line in fh:
+            if line.startswith("track") or not line.strip():
+                continue
+            f = line.split("\t")
+            chrom, start = f[0], int(f[1])
+            conv = lo.convert_coordinate(chrom, start)
+            if conv:
+                nc, npos = conv[0][0], conv[0][1]
+                if nc in MAIN_CHROMS:
+                    sites.append((nc, npos))
+    integ = pd.DataFrame(sites, columns=["chrom", "pos"])
+    print(f"lifted {len(integ)} / sites to hg38")
+    out = density_per_bin(integ, bin_grid, out_parquet)
+    out = out.rename(columns={"integ_density": "integ_mlv_density",
+                              "integ_log_density": "integ_mlv_log_density"})
+    out.to_parquet(out_parquet, index=False)
+    return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mode", choices=["visdb", "lafave"], default="visdb")
+    ap.add_argument("--visdb-dir", default="/data/external/visdb")
+    ap.add_argument("--lafave-bed", default=None)
+    ap.add_argument("--chain", default="/data/external/hg19ToHg38.over.chain.gz")
+    ap.add_argument("--bin-grid", default="/data/features/bin_grid_1kb.parquet")
+    ap.add_argument("--out", default="/data/features/integration_density.parquet")
+    a = ap.parse_args()
+    if a.mode == "lafave":
+        out = lafave_density(a.lafave_bed, a.chain, a.bin_grid, a.out)
+        nz = int((out["integ_mlv_density"] > 0).sum())
+        print(f"MLV density: bins={len(out)} nonzero={nz} max={int(out['integ_mlv_density'].max())} -> {a.out}")
+        return
+    integ = load_visdb(a.visdb_dir)
+    print(f"loaded {len(integ)} integration sites; by virus: {integ['virus'].value_counts().to_dict()}")
+    out = density_per_bin(integ, a.bin_grid, a.out)
+    nz = int((out["integ_density"] > 0).sum())
+    print(f"integration density: bins={len(out)} nonzero={nz} max={int(out['integ_density'].max())}")
+
+
+if __name__ == "__main__":
+    main()