PDR Pipeline Plan — Navigation Kernel

Status: Operational state has moved to the database. This file is navigation only. ~80 lines, intentionally short.

Last consolidated: 2026-05-16

Why this file is short: the 1,176-line predecessor (now at docs/_archive/2026-05-16_pre_consolidation/PDR_PIPELINE_PLAN.md) tried to be checklist + run journal + decision log + roadmap all at once and became unreadable. Operational facts now live in DB; this file is the map.

---

What lives where

You want…	Look at…
What should I work on next?	GitHub issues labelled critical-path (always paired with p0). The current run’s order, decisions and acceptance checks are in its tracking issue (smoke run #1: #439) and docs/mods_smoke_run_1_playbook.md. (Deprecated 2026-09-28: the Research dashboard Pipeline tab and the pdr_status task list. Their pdr_pipeline_task rows were last touched 2026-05-21, and the stale critical ones were demoted to future.)
Training-run history & metrics	mods_research_run + mods_run_metric tables — Training Runs tab, or GET /api/mods/research/runs
Decisions and learnings (narrative)	docs/PDR_NOTES.md (human-readable), backed by MemoryItem (kind=‘decision’ / ‘insight’) — search via pdr_note_search MCP tool
Run-specific notes	pdr_note_search('run name') or MemoryItem rows linked via MemoryLink to mods_research_run
Patient-eval results	GET /api/mods/research/runs/{id}/patient-eval, or the mods_research_run_patient_eval_v view
Per-phase publishable writeups	docs/pdr_phase*_writeup.md (one per closed phase)
Variant-aware KG planning (Phase 8.5)	docs/pdr_phase8.5_variant_kg_planning.md
Temporal patient modeling planning (Phase 13)	docs/temporal_patient_modeling_planning.md
Patient-as-Node thinking doc (Phase 12)	docs/paan_planning.md
Original sprawling plan	docs/_archive/2026-05-16_pre_consolidation/PDR_PIPELINE_PLAN.md (do not edit; grep only)

---

Paper taxonomy — orientation

Three distinct papers share the same GP-KG + CompGCN+ConvE foundation but report different metrics on different tasks. Don’t conflate them. Canonical reference: docs/KG_CATALOG.md.

Key	Paper	Year	Role	Headline numbers
KG-Predict	Gao / Srivastava, JBI	2022	Introduced GP-KG and the foundational CompGCN+ConvE model.	CV link prediction: AUROC 0.981, AUPR 0.409, MRR 0.261. AD case study: AUROC 0.868, AUPR 0.364.
PDR1	Oğuztüzün et al., JBI	2025	Individualized the KG-Predict foundational model per-patient with UK Biobank PRS/biomarker scalars.	Table 3 foundational: MR 1390.6, MRR 0.19231, Hits@10 0.31331, AUC 0.866 (5-fold CV).
PDR2 / PDR-II	Oğuztüzün et al., JBI	2026	Re-architecture on PyTorch Geometric with ULTRA + KGIA.	Code at docs/References/PDR2/. Numbers not yet audited.

Comparator map (which measurement compares to which published number):

Our measurement	Right comparator
compute_metrics.py AUROC/AUPR on AD drug ranking vs 60 NCT positives	KG-Predict AD-CS: AUROC 0.868, AUPR 0.364
Val/test MRR without -skip_head (Run 4)	KG-Predict CV: AUROC 0.981, MRR 0.261
Val MRR with -skip_head (Runs 1–3)	No fair comparator — tail-only eval inflates MRR
Per-patient drug ranking	PDR1 Table 3 — not attempted (we have no UK Biobank data)

---

KG choice — current production decision

• PrimeKG is the production graph. 7,957 drugs, 30 relation types, rich drug-disease evidence. All Phase 9+ personalization targets PrimeKG.
• GP-KG is paper-comparator only. 1,430 drugs, 9 relations. Sufficient to reproduce KG-Predict, insufficient for CRC personalization (only 1 of 5 RGCC high-sensitivity drugs is in GP-KG).
• PrimeKG canonical checkpoint: Run B (primekg_corr_1l_400d_v1). Phase 7.5 Tier 1 ρ = +0.351, p = 0.00018 (n=109) — ⚠ superseded pending restatement, GH #324: the label was the mean of her two RGCC draws, which flattened the 12 drugs that inverted by class. Do not use as a baseline until re-run per timepoint.

See docs/PDR_NOTES.md for the full decision history and rationale.

---

Reproducibility & ent2id discipline (the gotchas you will hit)

• Train + infer in the same Colab session. ent2id map is built from train.txt traversal order; reloading a checkpoint in a new session scrambles predictions.
• GP-KG drug IDs: add 100M offset before PubChem lookup. IDs ≤0 after subtraction are non-drug entities (e.g. CIDEA gene).
• PrimeKG drug-disease relations: three types — indication, off-label use, contraindication. Enumerate all three at inference time. (GP-KG uses treat.)
• test.py flags: always pass -gcn_layer and -opn matching the checkpoint. Silent prediction scrambling otherwise.

---

Working conventions

• New tasks: open a GitHub issue (CLAUDE.md, “Issue tracking”). If it blocks the current end-to-end run, label it critical-path + p0. (Deprecated 2026-09-28: adding to pdr_pipeline_task via the Pipeline tab or POST /api/mods/research/pipeline/tasks.)
• New decisions: pdr_note_save(scope='global', kind='decision', pinned=true, ...).
• New run findings: pdr_note_save(scope='run', scope_id='<uuid>', kind='insight', ...).
• Run naming: {kg}_{opn}_{gcn_layer}l_{gcn_dim}d_v{n} (e.g., gpkg_corr_2l_200d_v1). The Tag taxonomy at mods_research_run.tags uses kg:<name>, opn:<name>, layers:N, dim:N, phase:<phase>, plus free-form labels (canonical, historical, etc.).