Learning-Assisted Network for Tumor Evidence, Research, and Nomination
LANTERN is a local-first computational cancer research platform for discovering, reproducing, and ranking testable hypotheses from public biomedical datasets (DepMap, NCI GDC/TCGA, PubChem, PubMed/Europe PMC). Its primary research direction:
Identify cancer-specific genetic dependencies and determine whether existing drugs or known compounds may exploit those dependencies.
LANTERN is a hypothesis-generation and computational-research tool. Its strongest possible output is:
"We found a computationally supported candidate that may warrant experimental investigation."
LANTERN is not a clinical tool. It does not diagnose, does not recommend treatments, and does not produce personalized medical advice. It never claims to have "found a treatment", and computational predictions are never described as demonstrated therapeutic effects. The goal is not impressive claims — it is interesting claims that survive attempts to prove them wrong.
Three principles are enforced structurally, not just stylistically
(full philosophy in CLAUDE.md; mechanics in
docs/architecture/overview.md):
- Evidence separation. Every
ProvenanceRecordcarries a mandatorykind(source_dataset/imported_artifact/transformation/analysis/result/hypothesis) with no default — validation fails without it, so nothing enters a provenance chain uncategorized. Reports display which evidence layers are present and absent; LLM output is never presented as experimental evidence. - Provenance. Every dataset import and every pipeline stage appends typed
ProvenanceRecords (source, release, checksums, transformation, parameters, software versions, seeds) to a chain saved with the run. A result without provenance is treated as incomplete (ADR-0004). - Reproduction before discovery. LANTERN must reproduce known published
findings before searching for novel ones (see
docs/research/). Negative and absent evidence is displayed, never hidden; anything unverifiable is labelledUNVERIFIED.
There are no services, queues, or clusters. Every analysis is a CLI invocation
that produces a reproducible run directory (runs/<run-id>/ with a frozen
config.yaml, provenance chain, per-stage intermediates, results, figures,
and a report). External data sources are reached only through dataset adapters
with a common interface; large tables are Parquet, cataloged and queried with
DuckDB; statistics are pure, deterministic functions tested against known
outputs.
lantern/
├── src/lantern/
│ ├── cli/ Typer CLI — thin; no business logic
│ ├── config/ machine settings + secrets (ADR-0006)
│ ├── provenance/ provenance records, chains, ProvenanceKind (ADR-0004)
│ ├── runs/ run IDs, immutable-config run directories (ADR-0005)
│ ├── storage/ Parquet / DuckDB / checksummed artifacts (ADR-0002)
│ ├── datasets/ adapter registry (ADR-0003): synthetic implemented;
│ │ depmap, gdc, pubchem, literature are documented stubs
│ ├── analysis/ statistics (Welch t-test, BH FDR, effect sizes),
│ │ dependency demo pipeline; genomics/validation stubs
│ ├── compounds/, pathways/, literature/, models/, agents/, api/ stubs
│ └── reports/ Markdown report + figure rendering
├── tests/ flat test_<area>.py files; no network, no GPU
├── data/ raw/ processed/ cache/ results/ (never committed)
├── runs/ one directory per analysis execution (never committed)
├── docs/ architecture/, adr/, research/
└── scripts/ bootstrap.sh
- Package boundaries, data flow, and storage layout:
docs/architecture/overview.md - Verified workstation environment:
docs/architecture/environment.md - Decisions:
docs/adr/(ADR-0001 … ADR-0010)
Requires Python 3.12+ and uv. Everything lives
in the project-local .venv/; nothing is installed system-wide.
uv sync --all-groups # create .venv/ from uv.lock (runtime + dev tools)
uv run lantern doctor # verify your environmentOr run both in one step with scripts/bootstrap.sh, or use the Makefile:
make setup, make doctor. Optional machine-specific overrides and API-key
placeholders are documented in .env.example (copy to .env; never commit
it). Research parameters never come from the environment — they live in
version-controlled YAML (ADR-0006).
uv run lantern info # name, version, resolved paths
uv run lantern doctor # environment PASS/WARN/FAIL table
uv run lantern datasets list # registered adapters and their status
uv run lantern reproduce --list # reproduction study contracts under studies/
uv run lantern reproduce studies/wrn-msi-chan2019.yaml
uv run lantern discover --list # Discovery Mode study contracts under studies/
uv run lantern discover studies/msi-high-discovery-001.yaml
uv run lantern demo # end-to-end synthetic demo (see below)
uv run lantern demo --seed 42 --slug my-demo
uv run lantern runs list # recorded runs
uv run lantern runs show <run-id>lantern datasets list shows the adapter registry — real sources are
deliberately still stubs in the foundation phase:
Registered dataset adapters
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Name ┃ Source ┃ Release ┃ Status ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ depmap │ DepMap │ not pinned │ stub (planned) │
│ gdc │ NCI Genomic Data Commons │ not pinned │ stub (planned) │
│ │ (GDC/TCGA) │ │ │
│ literature │ Europe PMC / PubMed │ not pinned │ stub (planned) │
│ pubchem │ PubChem │ not pinned │ stub (planned) │
│ synthetic │ lantern.datasets.synthetic │ v1 │ implemented │
└────────────┴───────────────────────────────────┴────────────┴────────────────┘
lantern doctor checks Python, OS, CPU, RAM, GPU, key imports, and directory
writability, and exits non-zero only on FAIL — it ends with
Environment OK (WARNs are acceptable). on a healthy machine.
SYNTHETIC TEST DATA - NOT BIOLOGICAL EVIDENCE
lantern demo exercises the whole foundation end-to-end on deterministic
synthetic data: a seeded generator produces a small fake gene × cell-line
dependency matrix (SYNGENE01 … SYNGENE25) with an effect planted by
construction in SYNGENE07. The pipeline
- creates a managed run under
runs/<run-id>/with a frozenconfig.yaml, - imports the synthetic tables to Parquet in
intermediate/, - splits mutant vs. wildtype cohorts with DuckDB,
- runs per-gene Welch t-tests with Benjamini–Hochberg FDR and effect sizes,
- writes results (Parquet + JSON), a figure, the full provenance chain
(
source_dataset → imported_artifact → analysis → result), and areport.mdthat opens with the synthetic-data banner.
Recovering the planted gene proves the infrastructure works — run creation,
storage, statistics, provenance, and reporting. It supports no biological
conclusion of any kind; every artifact carries the literal label above.
Inspect a finished run with lantern runs show <run-id>.
uv run pytest # or: make test182 passed in 1.98s
Tests are flat under tests/ and need no network, no GPU, and no downloads —
fixture data is generated on the fly by the seeded synthetic generator.
Statistical functions are tested against known reference outputs. The full
quality gate is make qa (ruff lint + mypy strict + pytest,
ADR-0007) and must pass before any
commit.
Optional, and currently unused. The entire core pipeline is CPU-only.
lantern doctor reports GPU status as informational: a missing GPU is a WARN,
never a FAIL. Future GPU-accelerated components (embeddings, molecular
representations, ranking models under models/) must remain modular extras —
LANTERN stays fully usable with them disabled.
The research pipeline (cancer subtype/mutation → cohort selection → DepMap dependency analysis → candidate genes → pathway/compound mapping → drug sensitivity → literature evidence → cross-dataset validation → ranked hypotheses → research report) is built milestone by milestone:
| Milestone | Scope | Status |
|---|---|---|
| 1 — Foundation | config, logging, CLI, runs, provenance, storage, adapters, tests | complete |
| 2 — DepMap | importer, dependency querying, mutation cohorts, differential-dependency statistics | next |
| 3 — Reproduce known result | end-to-end reproduction of one published dependency finding + report | in progress — WRN/MSI benchmark |
| 4 — Compound mapping | gene → protein/pathway → known drugs and bioactivity | planned |
| 5 — Literature evidence | automated collection, structured evidence cards | planned |
| 6 — Cross validation | tumor genomics, expression, independent datasets, drug response | planned |
| 7 — Discovery mode | systematic searches with transparent evidence scoring | v1 executed — MSI-high discovery study |
Reproduction studies (Milestone 3 onward) are recorded under
docs/research/. No large-scale novelty search
begins until at least one published result has been reproduced.
Milestone 3 in progress. The first benchmark is 0001 — WRN dependency in MSI cancer cell lines, a two-arm (CRISPR + RNAi) reproduction of Chan et al., Nature 568:551–556, 2019. The proposal is a pre-registration: claim, cohort rules, guardrails, controls and verdict criteria are frozen before any statistic runs. Its supporting decisions are ADR-0008 (pinned anchors vs newest-data cross-checks), ADR-0009 (MSI label instrument), and ADR-0010 (MSI-high cancer as the North Star target form).
A second, deliberately weaker stretch benchmark is pre-registered as 0002 — KRAS self-dependency in KRAS-mutant cell lines (Meyers et al., Nat Genet 49:1779–1784, 2017). Its published claim is one qualitative sentence pointing at a figure, so its verdict ceiling is REPRODUCED-DIRECTION and REPRODUCED-MAGNITUDE is structurally unavailable; and because no verified flagship paper specifies a KRAS-mutant cohort filter, the cohort rule is LANTERN's own decision, declared as such and recorded in ADR-0011. It exists to exercise the mutation-cohort code path the MSI study never touches.
CLAUDE.md— the authoritative project specification and philosophydocs/architecture/overview.md— package map, data flow, storage layout, evidence-category enforcementdocs/architecture/environment.md— verified workstation environmentdocs/adr/— architecture decision recordsdocs/research/— reproduction-study recordsdocker/— why containerization is deferred
All studies are pre-registered, run under frozen guardrails, adversarially reviewed with independent recomputation, and committed as full reports:
| # | Study | Outcome |
|---|---|---|
| 0001 | WRN/MSI two-arm reproduction of Chan et al. 2019 | REPRODUCED-DIRECTION (both arms); REPRODUCED-MAGNITUDE (per-line DRIVE concordance, r = 1.0000) |
| 0002 | KRAS self-dependency, direction-only (Meyers et al. 2017) | REPRODUCED-DIRECTION (its pre-declared ceiling) |
| 0004 | WRN robustness on the newest (unpinned) DepMap release | Holds: rank 1, cross-release per-line r = 0.9923 |
| 0005 | First MSI-high discovery scan (lineage-adjusted, 3 data dimensions) | 15 candidates; leads RNPC3 and TRNAU1AP pending literature verdicts |
No research data is committed to this repository. Every dataset is fetched from its public source with checksums verified and recorded (see ADR-0008): DepMap Public 24Q4 (Figshare, CC BY 4.0), DEMETER2 v6 (Figshare, CC BY 4.0), PRISM Repurposing 19Q4 (Figshare, CC BY 4.0), and publication supplements retrieved from PMC for research use with citation (not redistributed). Reports attribute all sources.
LANTERN is developed with heavy AI assistance (Claude) under the integrity
rules in CLAUDE.md: language models never serve as the authority for
biological facts, statistics, or novelty claims; every study is adversarially
reviewed with independent recomputation from raw data before it is committed.
Apache License 2.0 — see LICENSE. Cite via CITATION.cff if you use the platform or its outputs.