PrimeKG 完整教學：精準醫療知識圖譜 (Precision Medicine Knowledge Graph)

Repository: mims-harvard/PrimeKG Stars: 791 · Forks: 154 · Language: Jupyter Notebook · License: MIT Lab: Harvard Medical School — Marinka Zitnik Lab (MIMS = Machine Intelligence for Medicine and Science) 論文: Chandak, Huang, Zitnik. “Building a knowledge graph to enable precision medicine.” Nature Scientific Data, 2023.

Note

官方 README 目前在最上方明確標註：PrimeKG 已被 OptimusKG 取代。OptimusKG 包含 PrimeKG 的完整超集 (superset) 資料，並持續更新，官方建議幾乎所有情境都改用 OptimusKG。本教學仍以 PrimeKG 為主體撰寫（因為它是目前生態系中被最多下游工具、論文與教材引用的版本，且 API/資料結構是理解 OptimusKG 的基礎），但在第 7 節會完整說明這個世代交替對使用者的實際意義。

目錄

1. 專案概述 (Project Overview)
2. 核心架構 (Core Architecture)
3. 安裝與設定 (Installation & Setup)
4. 基本使用 (Basic Usage)
5. 進階功能與應用場景 (Advanced Features & Use Cases)
6. AIKT 整合分析與策略 (AIKT Integration & Strategy)
7. 效能、限制與替代方案 (Performance, Limitations & Alternatives)
8. 總結與建議 (Summary & Recommendations)

1. 專案概述 (Project Overview)

1.1 用一個比喻理解 PrimeKG

想像你是一位醫生，桌上同時攤開了 20 本不同專業的百科全書——一本講基因 (gene) 與蛋白質 (protein)、一本講藥物交互作用 (drug interaction; 藥物交互作用)、一本講疾病症狀 (phenotype; 表現型)、一本講人體解剖結構 (anatomy; 解剖結構)、一本講生化路徑 (pathway; 生化路徑)……每本書用自己的術語、自己的編號系統、自己的更新頻率獨立運作。當一個病人同時有罕見疾病 (rare disease; 罕見疾病)、多重用藥、基因突變時，醫生必須自己在腦中把這 20 本書的知識「兜」在一起，才能看出全貌。

PrimeKG 做的事情，就是把這 20 本百科全書拆解成統一格式的「知識卡片」，然後用一張巨大的關聯網把所有卡片連起來，變成一個可以用程式查詢的知識圖譜 (knowledge graph; 知識圖譜)。查詢「阿茲海默症跟哪些基因、藥物、症狀有關」不再需要人工翻 20 本書，而是一行 pandas 查詢就能拿到答案。

更具體地說，PrimeKG 整合了：

• 20 個高品質生醫資料源（DrugBank、Reactome、UMLS、MONDO、Human Phenotype Ontology、Gene Ontology、SIDER、DisGeNET 等）
• 17,080 種疾病節點，涵蓋常見病與大量罕見疾病
• 超過 4,050,249 條關係 (relationships; 關係)，橫跨 10 種主要生物學尺度 (biological scales; 生物學尺度)——從分子（基因、蛋白質）到細胞（通路、GO term）到組織器官（解剖部位）到臨床（疾病、藥物、副作用）
• 超過 100,000 個節點，分布在 10 種節點類型、以 29 種邊 (edge) 類型互相連接
• 疾病與藥物節點額外附有 臨床文字描述 (clinical text descriptions; 臨床文字描述)，來自 Mayo Clinic、Orphanet 等權威醫學來源，讓知識圖譜可以支援多模態分析 (multimodal analysis; 多模態分析)——不只是結構化的圖，還有可以餵給語言模型的自然語言文本。

1.2 為什麼這件事重要——精準醫療的資料整合難題

精準醫療 (precision medicine; 精準醫療) 的核心承諾是「依照病人的分子特徵、基因組成、生活史，量身訂做治療方案」，而不是「一種藥治所有同名疾病的病人」。但要做到這件事，演算法必須同時理解：

• 這個病人的基因變異，對應到哪個蛋白質功能改變？
• 這個蛋白質功能改變，會影響哪些生化通路？
• 這些通路異常，會表現成哪些臨床症狀（phenotype）？
• 現有哪些藥物可以作用在這條通路上？
• 這些藥物有沒有已知副作用或與病人其他用藥的交互作用？

這五個問題橫跨五個完全不同的資料庫，過去的研究者往往只能挑 1-2 個資料源做窄範圍分析，因為手動整合 20 個資料庫的格式、命名、更新版本，是一件極其耗時且容易出錯的苦工。PrimeKG 的貢獻在於：把這件苦工做一次，做得夠好，讓後面幾百個研究團隊可以直接站在巨人的肩膀上，把心力放在演算法設計而非資料清洗。

這也是為什麼 PrimeKG 論文發表在 Nature Scientific Data（資料型期刊，而非演算法期刊）——它的貢獻本質是「基礎設施」，而不是某個特定模型。這正好對應到軟體工程裡「資料層 vs 應用層」分離的思路：先把資料結構做對，後面的機器學習模型才有意義。

1.3 學術地位與引用

• 原始論文：Chandak P, Huang K, Zitnik M. “Building a knowledge graph to enable precision medicine.” Nature Scientific Data 10, 67 (2023). DOI: 10.1038/s41597-023-01960-3
• 前身：2022 年 4 月先在 bioRxiv 發表 preprint，同時資料集上架 Harvard Dataverse
• 下載量：截至 2022 年 6 月已突破 5,000 次下載（Harvard Dataverse 統計），目前累積下載量遠高於此
• 社群整合：已被主流藥物開發資料工具鏈收錄為標準資料集，包括：
  • Therapeutics Data Commons (TDC) — from tdc.resource import PrimeKG 一行載入
  • PyKEEN — 知識圖譜嵌入 (knowledge graph embedding; 知識圖譜嵌入) 訓練框架的內建資料集
• 後續延伸：2023 年 12 月新增完整 OMIM (Online Mendelian Inheritance in Man; 人類孟德爾遺傳線上資料庫) 資料，強化罕見疾病與基因型-表現型對應覆蓋率

1.4 在 mims-harvard 實驗室生態系中的角色

mims-harvard（Zitnik Lab）的研究主軸是「用機器學習理解生物與醫學系統的複雜性」，PrimeKG 在其中扮演的角色是共用資料底座：

• TDC (Therapeutics Data Commons) — 藥物開發任務的標準化 benchmark 平台，PrimeKG 是其中的核心圖資料集之一
• TxGNN — 建立在 PrimeKG 之上的零樣本藥物重定位 (zero-shot drug repurposing; 零樣本藥物重定位) 模型，直接使用 PrimeKG 的疾病-藥物-基因關係做預測
• 下游論文：大量 Zitnik Lab 及外部團隊的圖神經網路 (Graph Neural Network, GNN; 圖神經網路) 藥物發現論文都以 PrimeKG 作為訓練/評測資料
• OptimusKG（PrimeKG 的官方後繼者）— 延續同一套資料整合哲學，但補齊了更新頻率與資料源覆蓋的短板

換句話說，PrimeKG 不是一個孤立的專案，而是這個實驗室「精準醫療 AI 三部曲」（資料整合 → 圖表示學習 → 臨床任務應用）的第一部。

1.5 專案定位圖

flowchart TB
    subgraph SG_RAW["原始生醫資料源（20 個）"]
        R1["DrugBank
藥物資料庫"]
        R2["Reactome
生化通路"]
        R3["UMLS / MONDO
疾病本體論"]
        R4["Gene Ontology
基因功能"]
        R5["Human Phenotype
Ontology (HPO)"]
        R6["SIDER / DisGeNET
副作用/基因疾病關聯"]
        R7["...(其他 14 個資料源)"]
    end

    subgraph SG_PRIMEKG["PrimeKG（本教學主體）"]
        PK["統一知識圖譜
17080 疾病節點
4050249 關係
10 種生物學尺度"]
    end

    subgraph SG_DOWNSTREAM["下游應用生態系"]
        TDC["Therapeutics Data Commons
標準化 benchmark"]
        PYKEEN["PyKEEN
知識圖譜嵌入訓練"]
        TXGNN["TxGNN
零樣本藥物重定位"]
        GNN["各類 GNN 藥物發現論文"]
    end

    subgraph SG_NEXTGEN["下一代（官方繼任者）"]
        OKG["OptimusKG
PrimeKG 超集+持續更新"]
    end

    R1 --> PK
    R2 --> PK
    R3 --> PK
    R4 --> PK
    R5 --> PK
    R6 --> PK
    R7 --> PK

    PK --> TDC
    PK --> PYKEEN
    PK --> TXGNN
    PK --> GNN
    PK -.演進.-> OKG

    style PK fill:#FDE68A,color:#0F172A
    style OKG fill:#BBF7D0,color:#0F172A

1.6 十種生物學尺度一覽

PrimeKG 之所以特別，在於它不是單一尺度的圖（例如只有「蛋白質-蛋白質交互作用」），而是橫跨十種尺度的異質圖 (heterogeneous graph; 異質圖)：

這種「一張圖橫跨十種尺度」的設計，正是它能支援「基因突變 → 通路異常 → 臨床症狀 → 候選藥物」這類跨尺度推理鏈的關鍵。

2. 核心架構 (Core Architecture)

2.1 系統架構總覽

PrimeKG 的架構可以拆成三個階段：資料處理 (processing) → 圖建構 (graph construction) → 特徵工程 (feature engineering)。每個階段都對應到 repo 裡實際存在的目錄結構。

flowchart LR
    subgraph SG_STAGE1["階段一：資料處理層"]
        direction TB
        D1["datasets/primary_data_resources.sh
下載 20 個原始資料源"]
        D2["datasets/processing_scripts/
*.py / *.ipynb
逐個資料源清洗+標準化"]
        D3["每個腳本輸出
標準化 CSV
(例: drug_drug.csv,
anatomy_gene.csv)"]
        D1 --> D2 --> D3
    end

    subgraph SG_STAGE2["階段二：圖建構層"]
        direction TB
        G1["knowledge_graph/build_graph.ipynb
讀取所有標準化 CSV"]
        G2["節點對齊 + ID 映射
(跨資料源實體消歧)"]
        G3["產出三版本圖:
kg_raw.csv
kg_giant.csv
kg.csv (完整版)"]
        G1 --> G2 --> G3
    end

    subgraph SG_STAGE3["階段三：特徵工程層"]
        direction TB
        F1["knowledge_graph/engineer_features.ipynb"]
        F2["knowledge_graph/mapping_mayo.ipynb"]
        F3["疾病/藥物節點
附加臨床文字描述"]
        F1 --> F3
        F2 --> F3
    end

    D3 --> G1
    G3 --> F1
    F3 --> OUT["最終產出：
kg.csv（Harvard Dataverse）
+ 臨床文本特徵"]

    style OUT fill:#93C5FD,color:#0F172A

用工廠生產線比喻：primary_data_resources.sh 是進料（20 種原料進廠）；processing_scripts/ 是各條獨立的初加工線（每種原料有自己的加工方式，因為原始格式天差地遠）；build_graph.ipynb 是總裝配線（把所有半成品組裝成一個產品，同時要處理「同一個零件在不同供應商叫法不同」的對齊問題）；engineer_features.ipynb 是最後的品管貼標（幫關鍵零件加上易讀的說明文字）。

2.2 資料流向圖：從原始資料源到可查詢的圖

sequenceDiagram
    participant Src as 20 個原始資料源
    participant Script as processing_scripts/
    participant Build as build_graph.ipynb
    participant Feat as engineer_features.ipynb
    participant Dataverse as Harvard Dataverse
    participant User as 研究者/工具

    Src->>Script: 下載原始檔（TSV/XML/OBO/API）
    Script->>Script: 解析 + 欄位標準化
(x_id, x_type, relation, y_id, y_type)
    Script->>Build: 輸出標準化 CSV
(例：disease_phenotype_pos.csv)
    Build->>Build: 實體對齊（跨資料源同義詞合併）
    Build->>Build: 去重 + 邊類型標準化（29 種 relation）
    Build->>Feat: 產出 kg_raw.csv / kg_giant.csv / kg.csv
    Feat->>Feat: 附加 Mayo Clinic / Orphanet 臨床文字
    Feat->>Dataverse: 發布最終版本（含 DOI）
    User->>Dataverse: wget 下載 kg.csv
    User->>User: pandas.read_csv() 查詢分析

2.3 關鍵資料結構：邊列表 (Edge List) 格式

PrimeKG 最終產出的核心檔案 kg.csv，本質上是一張邊列表 (edge list)——知識圖譜最常見、最容易上手的儲存格式。每一行代表圖中的一條邊，包含起點節點、終點節點與關係類型：

為什麼選邊列表而不是圖資料庫（如 Neo4j）？ 這是 PrimeKG 一個非常務實的設計決策：邊列表是最通用的格式，任何語言、任何工具都能讀（pandas、R、Neo4j import、NetworkX、PyTorch Geometric），不綁死使用者必須裝特定資料庫軟體。代價是查詢效能不如專用圖資料庫，但對「下載一次、離線分析」的研究情境而言，這個代價完全可以接受——這正是「複雜度要跟問題匹配」的體現。

2.4 關鍵方法論：跨資料源實體對齊 (Entity Alignment)

PrimeKG 遇到的最大技術挑戰，不是「怎麼存圖」，而是**「同一個生物實體，在 20 個資料源裡有 20 種不同的 ID 與名稱，怎麼知道它們是同一個東西？」**

具體例子：「第二型糖尿病」這個疾病，在不同資料源裡可能是：

• MONDO: MONDO:0005148
• UMLS: C0011860
• OMIM: 125853（部分亞型）
• 純文字：“Type 2 diabetes mellitus”、“T2DM”、“NIDDM”（非胰島素依賴型糖尿病，舊稱）

build_graph.ipynb 的核心工作之一，就是用 MONDO 本體論作為「中央對照表」（因為 MONDO 本身就是設計來統一疾病命名的本體論），把 UMLS、OMIM 等其他資料源的疾病 ID 都映射到同一個 MONDO ID 上，才能保證「糖尿病相關的基因」和「糖尿病相關的藥物」指向的是同一個節點，而不是被誤判成兩個不相關的疾病。

flowchart TD
    subgraph SG_ALIGN["實體對齊範例：第二型糖尿病"]
        A1["UMLS: C0011860
'Type 2 diabetes mellitus'"]
        A2["OMIM: 125853
(亞型)"]
        A3["MONDO: MONDO_0005148
(中央對照本體論)"]
        A4["HPO 症狀節點
(經 disease_phenotype_pos.csv)"]
        A5["DrugBank 藥物節點
(經 drugcentral drug_disease.csv)"]

        A1 -->|umls_mondo.csv 映射| A3
        A2 -->|mim_disease 映射| A3
        A3 --- A4
        A3 --- A5
    end

    style A3 fill:#FCA5A5,color:#0F172A

若沒有這個對齊步驟，圖裡會出現大量「應該連起來卻斷開」的孤島節點，嚴重削弱下游圖神經網路能學到的訊號——這也是為什麼 PrimeKG 的貢獻被歸類在 Nature Scientific Data 而非普通資料集發布：對齊品質本身就是一項研究成果。

2.5 三種圖版本的設計意圖

build_graph.ipynb 會產出三個不同「純度」的版本，這對應到「原始資料 vs 可用資料」的取捨：

• kg_raw.csv：所有處理過的邊，未經任何過濾——包含品質較低、孤立、稀疏連接的節點。適合想自己重新篩選的研究者。
• kg_giant.csv：僅保留最大連通元件 (largest connected component; 最大連通分量)——確保圖中任兩節點理論上都能透過某條路徑互相到達，適合圖神經網路訓練（斷裂的圖對訊息傳遞 (message passing; 訊息傳遞) 演算法是災難）。
• kg.csv：官方建議的完整可用版本，是 kg_giant.csv 的基礎上，再補回一些有科學價值但連接度稍低的節點（如部分罕見疾病）。這是 Harvard Dataverse 上實際發布、多數下游工具（TDC、PyKEEN）預設載入的版本。

2.6 內部元件互動關係

flowchart TB
    subgraph SG_CORE["核心元件互動"]
        UTIL["scripts/utils.py
共用工具函式"]
        P1["各 processing_scripts/*.py"]
        OBO["*_obo_parser.py
(mondo/hpo 本體論解析器)"]
        NB1["build_graph.ipynb"]
        NB2["engineer_features.ipynb"]
        NB3["mapping_mayo.ipynb"]
        NB4["append_omim.ipynb"]

        UTIL --> P1
        OBO --> P1
        P1 --> NB1
        NB1 --> NB2
        NB1 --> NB3
        NB4 -->|增量更新| NB1
    end

    style NB1 fill:#DDD6FE,color:#0F172A

scripts/utils.py 是被多個處理腳本共用的工具層（例如統一的 ID 格式化函式），*_obo_parser.py 專門處理本體論檔案格式（OBO 是 Open Biomedical Ontologies 的標準格式，MONDO 與 HPO 都用這種格式發布），這兩者都是為了消除「29 個獨立腳本各自重新發明輪子」的重複勞動——這正好呼應「消除特殊情況、簡化資料流」的工程原則。

3. 安裝與設定 (Installation & Setup)

3.1 使用情境判斷：你需要的是資料，還是建構腳本？

在動手安裝前，先問自己一個關鍵問題：「我只是要用現成的圖做分析，還是要重新建構/更新這個知識圖譜？」 這決定了完全不同的安裝路徑：

• 只要用資料 → 只需要 wget + pandas，不需要 clone 整個 repo，5 分鐘可以開始分析（見 3.4）
• 要重新建構圖 → 需要完整的環境設定（本體論解析器、R 環境跑 .Rmd、多個資料源 API 金鑰），這是重量級任務，通常只有想要客製化/更新資料源的研究者才需要

多數使用者（包括做藥物發現、GNN 研究的人）屬於前者。本節分別說明兩種路徑。

3.2 前置需求

Important

依照 AIKT 全域規範，Python 套件管理應優先使用 uv，避免將 pip 當主要安裝方式。以下指令沿用 PrimeKG 官方 README 的 pip/conda 寫法供對照，但實務操作建議改用 uv venv + uv pip install 取代裸 pip install。

3.3 方法一：僅使用資料（推薦多數使用者）

這是最快、最不容易出錯的路徑，完全不需要 clone repo：

 1# 步驟 1：建立隔離的 Python 環境（用 uv，符合工具鏈鐵律）
 2uv venv primekg-env
 3source primekg-env/bin/activate
 4
 5# 步驟 2：安裝最小依賴
 6uv pip install pandas numpy
 7
 8# 步驟 3：直接從 Harvard Dataverse 下載完整版知識圖譜
 9wget -O kg.csv https://dataverse.harvard.edu/api/access/datafile/6180620
10
11# 步驟 4：驗證下載成功
12python3 -c "import pandas as pd; df = pd.read_csv('kg.csv', low_memory=False); print(df.shape); print(df['relation'].value_counts().head())"

預期輸出應該顯示約 400 萬列、每列包含 x_id, x_type, y_id, y_type, relation, display_relation 等欄位，relation 分佈中會看到 protein_protein、drug_drug、disease_disease 等常見類型。

3.4 方法二：透過 Therapeutics Data Commons (TDC) 載入（更推薦）

TDC 是 mims-harvard 自家的下游工具，把下載、快取、格式轉換都包好了，是官方目前最推薦的「一般分析用途」進入點：

1uv venv primekg-env
2source primekg-env/bin/activate
3uv pip install PyTDC

1
2# 首次執行會自動下載並快取到 ./data
3data = PrimeKG(path='./data')
4
5# 驗證安裝成功
6drug_feature = data.get_features(feature_type='drug')
7print(f"取得藥物特徵表，共 {len(drug_feature)} 筆")

3.5 方法三：完整開發環境（若要重新建構或更新圖）

只有想要客製化資料源、增量更新（如新增 2024 年後的 OMIM 資料）、或深入研究建構流程的使用者才需要這條路徑：

 1# Clone 完整 repository
 2git clone https://github.com/mims-harvard/PrimeKG.git
 3cd PrimeKG
 4
 5# 方法 A：pip 安裝（官方寫法）
 6pip install -r updated_requirements.txt
 7
 8# 方法 B：conda 環境（官方另一種寫法）
 9conda env create --name PrimeKG --file=environment.yml
10conda activate PrimeKG
11
12# 若使用 Jupyter 開發（建構腳本以 notebook 為主）
13bash setup_jupyter.sh

若使用容器化方式（符合 AIKT 「系統服務預設 Docker/Podman」原則），可以用最小 Dockerfile 包裝：

1FROM python:3.10-slim
2WORKDIR /workspace
3COPY updated_requirements.txt .
4RUN pip install --no-cache-dir -r updated_requirements.txt
5COPY . .
6CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--no-browser", "--allow-root"]

3.6 驗證步驟

無論走哪條路徑，安裝完成後建議做以下三項驗證：

 1
 2# 驗證 1：檔案完整性——列數應接近 4,050,249（官方公告的邊數量級）
 3kg = pd.read_csv('kg.csv', low_memory=False)
 4assert len(kg) > 3_000_000, "資料列數異常，請重新下載"
 5
 6# 驗證 2：節點類型應覆蓋 10 種生物學尺度
 7expected_types = {'disease', 'drug', 'gene/protein', 'effect/phenotype',
 8                   'anatomy', 'pathway', 'biological_process',
 9                   'molecular_function', 'cellular_component', 'exposure'}
10actual_types = set(kg['x_type'].unique()) | set(kg['y_type'].unique())
11assert expected_types.issubset(actual_types), f"缺少節點類型：{expected_types - actual_types}"
12
13# 驗證 3：關係類型應接近官方公告的 29 種
14n_relations = kg['relation'].nunique()
15print(f"共有 {n_relations} 種關係類型（官方公告約 29 種）")

若驗證 1、2 失敗，最常見原因是下載中斷（Harvard Dataverse 檔案較大，建議用 wget -c 支援續傳）或誤下載了舊版本連結。

4. 基本使用 (Basic Usage)

4.1 快速入門：找出一個疾病的完整知識網路

假設我們是研究人員，想了解「肌萎縮性側索硬化症 (Amyotrophic Lateral Sclerosis, ALS; 漸凍症)」在 PrimeKG 中的完整關聯——這是 PrimeKG 最典型的使用場景：以一個疾病為中心，展開它跨尺度的所有已知關係。

 1
 2# 載入知識圖譜
 3kg = pd.read_csv('kg.csv', low_memory=False)
 4
 5# 步驟 1：找出 ALS 的節點 ID（透過名稱模糊搜尋，因為疾病名稱可能有多種寫法）
 6als_nodes = kg[
 7    kg['x_name'].str.contains('amyotrophic lateral sclerosis', case=False, na=False) |
 8    kg['y_name'].str.contains('amyotrophic lateral sclerosis', case=False, na=False)
 9]
10print(f"與 ALS 相關的邊共有 {len(als_nodes)} 條")
11
12# 步驟 2：找出 ALS 的節點 ID 後，展開所有與它直接相連的邊
13als_id = als_nodes.iloc[0]['x_id'] if als_nodes.iloc[0]['x_type'] == 'disease' else als_nodes.iloc[0]['y_id']
14als_edges = kg[(kg['x_id'] == als_id) | (kg['y_id'] == als_id)]
15
16# 步驟 3：依關係類型分組，看看 ALS 跟哪些尺度的知識相連
17print(als_edges['relation'].value_counts())

典型輸出會顯示 ALS 連接到：disease_phenotype_positive（已知症狀，如肌肉萎縮、吞嚥困難）、gene_disease（已知致病基因，如 SOD1、C9orf72）、indication（適應症藥物，如 Riluzole/利魯唑）、disease_disease（相關/共病疾病）。這一行程式碼在傳統做法下，等同於同時查関 OMIM、DrugBank、HPO 三個資料庫並手動比對疾病編號。

4.2 從零開始的完整工作流：建構藥物重定位候選清單

這是一個更貼近真實研究場景的完整範例：給定一個目標疾病，找出目前尚未被核准用於此疾病、但作用在相關基因/通路上的候選藥物——這正是藥物重定位 (drug repurposing; 藥物重定位) 的基本邏輯。

 1
 2kg = pd.read_csv('kg.csv', low_memory=False)
 3
 4    """
 5    給定疾病名稱，回傳「透過基因中介、可能有潛力但尚未核准」的候選藥物清單。
 6
 7    邏輯鏈：
 8    disease --(gene_disease)--> gene --(drug_protein)--> drug
 9    再排除已經有 indication 關係的藥物（代表已核准，非「新」候選）
10    """
11    # 找疾病節點
12    disease_rows = kg[
13        (kg['x_type'] == 'disease') & kg['x_name'].str.contains(disease_name, case=False, na=False)
14    ]
15    if disease_rows.empty:
16        raise ValueError(f"找不到疾病：{disease_name}")
17    disease_id = disease_rows.iloc[0]['x_id']
18
19    # 疾病 -> 基因（透過 gene_disease 關係）
20    disease_genes = kg[
21        (kg['x_id'] == disease_id) & (kg['relation'] == 'disease_protein')
22    ]['y_id'].unique()
23
24    # 基因 -> 藥物（透過 drug_protein 關係，反向查詢）
25    candidate_drugs = kg[
26        (kg['y_id'].isin(disease_genes)) & (kg['relation'] == 'drug_protein')
27    ][['x_id', 'x_name', 'y_id']].drop_duplicates()
28
29    # 排除已核准適應症的藥物
30    approved_drug_ids = kg[
31        (kg['x_id'] == disease_id) & (kg['relation'] == 'indication')
32    ]['y_id'].unique()
33
34    candidates = candidate_drugs[~candidate_drugs['x_id'].isin(approved_drug_ids)]
35    return candidates
36
37# 實際執行：尋找阿茲海默症的候選重定位藥物
38candidates = find_repurposing_candidates('alzheimer', kg)
39print(f"找到 {len(candidates)} 個候選藥物（尚未核准但透過基因中介有潛在連結）")
40print(candidates.head(10))

Note

這個範例是教學用簡化邏輯，真實的藥物重定位研究（如 mims-harvard 自家的 TxGNN）會用圖神經網路學習節點嵌入向量後再做相似度排序，而不是單純的一步圖遍歷。但這個簡化版本足以說明 PrimeKG 資料結構如何支撐這類推理鏈。

4.3 輸入/輸出格式範例

輸入：kg.csv 邊列表格式，實際欄位範例：

1relation,display_relation,x_index,x_id,x_type,x_name,x_source,y_index,y_id,y_type,y_name,y_source
2indication,indication,1234,DB00945,drug,Aspirin,DrugBank,5678,MONDO:0005404,disease,fever,MONDO
3protein_protein,ppi,891,7157,gene/protein,TP53,NCBI,892,672,gene/protein,BRCA1,NCBI
4disease_phenotype_positive,phenotype present,201,MONDO:0007739,disease,Huntington disease,MONDO,301,HP:0002067,effect/phenotype,Bradykinesia,HPO

輸出（分析結果範例）：使用 data.to_nx()（TDC dataloader 提供）轉成 NetworkX 圖後，可以直接套用任何圖演算法：

 1
 2data = PrimeKG(path='./data')
 3G = data.to_nx()  # 轉換成 NetworkX Graph 物件
 4
 5print(f"節點數: {G.number_of_nodes()}")
 6print(f"邊數: {G.number_of_edges()}")
 7
 8# 計算某疾病節點的度數中心性（degree centrality；連接數越高代表在圖中越「樞紐」）
 9disease_nodes = data.get_node_list(type='disease')
10centrality = nx.degree_centrality(G)
11top_diseases = sorted(
12    [(node, centrality[node]) for node in disease_nodes if node in centrality],
13    key=lambda x: x[1], reverse=True
14)[:5]
15print("連接度最高的 5 個疾病節點：", top_diseases)

4.4 實際生醫場景範例：罕見疾病的表現型比對

PrimeKG 對罕見疾病 (rare disease; 罕見疾病) 研究特別有價值，因為單一罕見疾病的病例數太少，難以用傳統統計方法找出規律，但透過知識圖譜可以借助「表現型相似的其他疾病」類推：

 1    """
 2    找出與目標疾病共享最多表現型 (phenotype) 的其他疾病。
 3    這對罕見疾病診斷特別有用：當一個病人表現出一組罕見症狀組合，
 4    可以反查「還有哪些疾病曾記錄過類似的症狀組合」，輔助臨床鑑別診斷。
 5    """
 6    # 取得目標疾病的所有表現型
 7    target_phenotypes = set(kg[
 8        (kg['x_id'] == target_disease_id) & (kg['relation'] == 'disease_phenotype_positive')
 9    ]['y_id'])
10
11    if not target_phenotypes:
12        return pd.DataFrame()
13
14    # 找出所有跟這些表現型有關的其他疾病
15    phenotype_disease_edges = kg[
16        (kg['y_id'].isin(target_phenotypes)) & (kg['relation'] == 'disease_phenotype_positive')
17    ]
18
19    # 計算每個其他疾病與目標疾病的表現型重疊數
20    overlap_counts = phenotype_disease_edges.groupby('x_id').size().sort_values(ascending=False)
21    overlap_counts = overlap_counts.drop(target_disease_id, errors='ignore')
22
23    return overlap_counts.head(top_n)
24
25# 範例：以某個 MONDO 罕見疾病 ID 為例（此處為示意 ID）
26similar = find_phenotypically_similar_diseases('MONDO:0007739', kg)  # Huntington disease 示意
27print(similar)

這個模式在臨床上稱為 phenotype matching（表現型比對），是遺傳疾病診所常用的鑑別診斷輔助手法，而 PrimeKG 把這件事從「醫生憑經驗記憶」變成「可程式化查詢」。

5. 進階功能與應用場景 (Advanced Features & Use Cases)

5.1 進階配置：使用 PyKEEN 訓練知識圖譜嵌入模型

PrimeKG 最強大的應用場景，是作為知識圖譜嵌入 (Knowledge Graph Embedding, KGE; 知識圖譜嵌入) 模型的訓練資料——把每個節點（基因、疾病、藥物）都學成一個向量，讓「向量距離」代表「生物學上的相關程度」：

 1
 2# PyKEEN 已內建 PrimeKG dataset，自動處理 train/valid/test split
 3result = pipeline(
 4    dataset='PrimeKG',
 5    model='TransE',          # 也可選 RotatE, ComplEx, DistMult 等
 6    training_kwargs=dict(num_epochs=50),
 7    random_seed=42,
 8)
 9
10# 訓練完成後，取得任一節點的嵌入向量
11model = result.model
12print(f"模型訓練完成，最終 loss: {result.losses[-1]:.4f}")
13
14# 儲存模型供後續下游任務使用（如藥物-疾病連結預測）
15result.save_to_directory('./primekg_transe_model')

應用情境：訓練好的嵌入向量可以直接餵進連結預測 (link prediction; 連結預測) 任務——「這個藥物節點的向量跟這個疾病節點的向量夠不夠接近，接近到值得提出作為候選適應症？」這正是 TxGNN 等下游模型的核心思路，只是它們用更複雜的異質圖神經網路架構取代簡單的 TransE。

5.2 進階應用案例：建構疾病共病網路 (Comorbidity Network)

利用 PrimeKG 的 disease_disease 關係與表現型重疊資訊，可以建構一個「共病網路」，找出臨床上容易同時發生的疾病群聚，這對照護路徑設計、多重用藥風險評估很有價值：

 1
 2    """
 3    建構疾病共病網路：兩疾病之間若共享超過 min_shared_phenotypes 個表現型，
 4    則視為潛在共病關係，建立一條邊。
 5    """
 6    phenotype_edges = kg[kg['relation'] == 'disease_phenotype_positive'][['x_id', 'y_id']]
 7
 8    # 每個表現型對應到哪些疾病
 9    phenotype_to_diseases = phenotype_edges.groupby('y_id')['x_id'].apply(set)
10
11    G = nx.Graph()
12    from itertools import combinations
13    from collections import defaultdict
14
15    pair_overlap = defaultdict(int)
16    for diseases in phenotype_to_diseases:
17        if len(diseases) < 2:
18            continue
19        for d1, d2 in combinations(sorted(diseases), 2):
20            pair_overlap[(d1, d2)] += 1
21
22    for (d1, d2), count in pair_overlap.items():
23        if count >= min_shared_phenotypes:
24            G.add_edge(d1, d2, weight=count)
25
26    return G
27
28comorbidity_net = build_comorbidity_network(kg, min_shared_phenotypes=5)
29print(f"共病網路：{comorbidity_net.number_of_nodes()} 個疾病節點，"
30      f"{comorbidity_net.number_of_edges()} 條共病關係")
31
32# 找出網路中最核心的「共病樞紐」疾病（degree 最高）
33degree_sorted = sorted(comorbidity_net.degree, key=lambda x: x[1], reverse=True)[:5]
34print("共病關係最多的疾病：", degree_sorted)

5.3 與其他工具/函式庫的整合

PrimeKG 的邊列表格式讓它幾乎能無縫整合進任何圖分析生態系：

範例：轉換到 PyTorch Geometric 供自訂 GNN 訓練：

 1
 2    """將 PrimeKG 邊列表轉換為 PyTorch Geometric 的異質圖資料結構"""
 3    data = HeteroData()
 4
 5    # 為每種節點類型建立獨立的 ID 映射（PyG 要求每種類型從 0 開始編號）
 6    node_maps = {}
 7    for node_type in pd.concat([kg[['x_id', 'x_type']].rename(columns={'x_id': 'id', 'x_type': 'type'}),
 8                                  kg[['y_id', 'y_type']].rename(columns={'y_id': 'id', 'y_type': 'type'})]) \
 9                      .drop_duplicates().groupby('type'):
10        pass  # 實務上建議用 sklearn LabelEncoder 逐類型處理，此處省略細節以聚焦架構
11
12    # 依 relation 分組建立各邊類型的 edge_index
13    for relation, group in kg.groupby('relation'):
14        src_type = group['x_type'].iloc[0]
15        dst_type = group['y_type'].iloc[0]
16        # edge_index 建構省略（需先完成上方 node_maps 映射）
17        pass
18
19    return data

完整實作需要處理節點 ID 重新編碼（因為 PyG 要求每種節點類型各自從 0 開始連續編號），實務上建議用 sklearn.preprocessing.LabelEncoder 對每種 x_type/y_type 分別 fit，這裡為了聚焦架構說明而簡化。

5.4 效能優化建議

在實際操作 400 萬列的 kg.csv 時，以下幾個優化手法能明顯改善體驗：

1. 載入時指定 dtype：pd.read_csv 預設會嘗試推斷型別，對含混合型別的欄位（如某些 ID 欄位混了數字與字串）會很慢且產生警告。明確指定：

   1dtype_spec = {'x_id': str, 'y_id': str, 'x_type': 'category', 'y_type': 'category', 'relation': 'category'}
   2kg = pd.read_csv('kg.csv', dtype=dtype_spec, low_memory=False)
   

   把 relation、x_type、y_type 設為 category 型別能大幅降低記憶體用量（這幾欄的重複值極高，category 型別本質是用整數編碼取代重複字串）。

2. 建立索引加速重複查詢：若要對同一個疾病 ID 反覆查詢，先用 set_index 或建立字典索引，避免每次都線性掃描 400 萬列：

   1# 較慢：每次都全表掃描
   2result = kg[kg['x_id'] == target_id]
   3
   4# 較快：預先按 x_id 分組，之後查詢是 O(1) 字典查找
   5grouped = {k: v for k, v in kg.groupby('x_id')}
   6result = grouped.get(target_id, pd.DataFrame())
   

3. 只載入需要的欄位：若分析只關心疾病-藥物關係，用 usecols 減少 I/O：

   1kg_subset = pd.read_csv('kg.csv', usecols=['x_id', 'x_type', 'relation', 'y_id', 'y_type'], low_memory=False)
   

4. 大規模圖演算法改用 GPU 加速：若要在完整 400 萬邊的圖上跑中心性、社群偵測等演算法，NetworkX 純 CPU 實作會很慢，可考慮 optimize-for-gpu 技能中提到的 cuGraph（RAPIDS 生態系）大幅加速。

6. AIKT 整合分析與策略 (AIKT Integration & Strategy)

6.1 整合架構圖：PrimeKG 在 AIKT 27 層中的位置

flowchart TB
    subgraph SG_ENTRY["知識擷取層 (L1-L3)"]
        L2["L2 gh-save
抓取 PrimeKG repo→教學 md
（本文件的產出方式）"]
        L3["L3 autofetch
可監測 mims-harvard 新論文"]
    end

    subgraph SG_ORG["知識組織層 (L4-L6)"]
        L4["L4 graphify
索引『AIKT 文件庫』本身的知識圖譜"]
        L5["L5 NotebookLM
可上傳 PrimeKG 論文做雲端問答"]
    end

    subgraph SG_DOC["文件處理層 (L7-L8)"]
        L7["L7 quarkdown
把本教學編譯成 HTML/PDF"]
        L8["L8 docling
解析 PrimeKG 論文 PDF"]
    end

    subgraph SG_LIT["文獻搜尋層 (L9-L10)"]
        L9["L9 paper-search
找 PrimeKG 相關引用論文"]
        L10["L10 paper-qa-lite
對 PrimeKG 論文本地問答"]
    end

    subgraph SG_RESEARCH["研究管線層 (L18-L19)"]
        L18["L18 research-pipeline-v2
可整合 PrimeKG 查詢結果
進多輪研究報告"]
        L19["L19 tu-plan-generator
藥物開發計畫可引用
PrimeKG 的藥物-基因-疾病證據"]
    end

    subgraph SG_PRIMEKG_CORE["PrimeKG 本身（外部知識圖譜資料）"]
        PK["kg.csv 邊列表
400 萬生醫關係"]
    end

    L2 -.抓取教學.-> PK
    PK -.提供領域證據.-> L18
    PK -.提供領域證據.-> L19
    L9 -.找相關論文.-> PK
    L10 -.本地問答.-> PK
    L8 -.解析論文.-> PK

    style PK fill:#FDE68A,color:#0F172A
    style L18 fill:#BBF7D0,color:#0F172A
    style L19 fill:#BBF7D0,color:#0F172A

關鍵觀察：PrimeKG 本身不是一個可以被 AIKT「執行」的工具（它沒有 CLI、沒有伺服器、沒有互動介面）——它是一份靜態知識圖譜資料集。因此它進入 AIKT 的方式，不是像 kami、quarkdown 那樣被「呼叫」，而是作為被引用、被摘要、被整合進研究產出的領域知識來源。這個定位差異，直接決定了下面紅海/藍海分析的走向。

6.2 紅海分析 (Red Ocean Analysis)

先誠實地看：PrimeKG 與 AIKT 在哪些功能上「表面上」有重疊，會讓人誤以為競爭？

重疊功能逐項比較

結論：真正意義上的「紅海」（直接功能競爭）幾乎不存在。PrimeKG 是資料層（生醫領域知識庫），AIKT 是流程層（知識工作流編排系統）。硬要說重疊，只有「兩者都在處理『知識』」這種抽象層次的重疊，但處理的知識種類、粒度、目的完全不同。這正呼應「AIKT 不做直接科學計算——它編排知識，不是演算法」的定位：PrimeKG 是可以被編排的科學資料，不是編排系統的競爭者。

市場定位衝突評估

沒有衝突。PrimeKG 服務的是「已經知道自己要做圖神經網路藥物發現研究」的生資/計算生物學家，價值在資料品質與覆蓋率；AIKT 服務的是「需要把研究過程中產生的大量異質資訊，自動化組織成可交付文件」的知識工作者，價值在流程自動化。兩者的使用者畫像高度重疊（都可能是同一個生技公司的研究人員），但需求場景不同——這其實是絕佳的互補訊號，而非競爭訊號。

6.3 藍海策略 (Blue Ocean Strategy)

此 repo 未滿足的需求

PrimeKG 作為一個 2022-2023 年發表、目前官方承認「已被 OptimusKG 取代」的資料集，存在幾個明確的未滿足需求缺口：

1. 沒有自然語言查詢介面：使用者必須自己寫 pandas/Cypher 查詢，不能直接問「阿茲海默症有哪些候選重定位藥物？」
2. 沒有與研究者既有筆記/文獻整合：PrimeKG 的知識完全獨立於使用者自己收集的論文、會議筆記、company-intel 情報
3. 沒有版本追蹤與新知比對：使用者無法輕易得知「這個月生醫資料庫更新了什麼，跟我半年前查的結果有沒有差異」
4. 沒有跨資料集比對（PrimeKG vs 其他知識圖譜如 Hetionet、DRKG）的自動化能力
5. 建構流程文件分散在 20+ notebook，新手要重現或客製化建構流程的學習曲線很高

創造新價值的整合機會

AIKT 的 27 層架構恰好可以填補上述缺口中「流程自動化」那一半，而不需要（也不應該）去重做 PrimeKG 本身的資料整合工作：

具體差異化策略

AIKT 不該試圖「重做一個 PrimeKG」（那是資料工程的苦工，也不是 AIKT 的定位），而應該做**「PrimeKG 的智慧介面層」**：

1. 建立 PrimeKG 查詢技能（新 Layer 提案）：一個輕量 script，包裝 pandas 查詢邏輯，讓使用者可以用自然語言指令（如 kg-query: 阿茲海默症的候選重定位藥物）觸發第 4.2 節那類查詢，並自動用 quarkdown 排版成報告
2. 與 paper-qa-lite 串接：當研究者在 paper-qa-lite 問答中提到某個疾病/藥物，自動附加 PrimeKG 的結構化關聯作為補充證據，形成「文獻證據 + 結構化圖證據」雙軌佐證
3. 納入 company-intel / tu-plan-generator 的證據來源清單：盡調或開發計畫報告中引用「某藥物的已知副作用/交互作用」時，優先查 PrimeKG（結構化、有來源）而非讓 LLM 憑記憶回答（容易幻覺過時或錯誤資訊）
4. 持續關注 OptimusKG 遷移：由於官方明確標示 PrimeKG 已被取代，AIKT 若要建立長期整合，應該直接對接 OptimusKG 的 Python client（pip install optimuskg），避免建立在即將被淘汰的資料版本上

6.4 推薦整合方案

分階段實施路徑：

第一階段（低成本、立即可行）：不新增 Layer，而是在現有 L10 paper-qa-lite 與 L19 tu-plan-generator 的 prompt/skill 文件中，加入一段「若問題涉及基因-疾病-藥物-副作用關係，建議交叉查詢 PrimeKG/OptimusKG 結構化資料，而非僅依賴 LLM 訓練記憶」的指引，這是文件層級的輕量整合，零開發成本。

第二階段（中等投入）：建立一個獨立的輕量 Python 工具（可放在 scripts/kg-query.py 或類似位置），封裝第 4 節示範的幾種常見查詢模式（疾病關聯展開、藥物重定位候選、共病網路），輸出標準化 JSON，供其他 Layer（尤其 L18/L19）呼叫。不需要建成完整 Layer，先以「共用工具函式」形式存在，觀察使用頻率後再決定是否升級為正式 Layer（依 L26 layer-creator 的判準）。

明確不建議：不要嘗試在 AIKT 內重建 PrimeKG 的資料整合/圖建構邏輯（build_graph.ipynb 那一整套），這是完全不同性質、需要生資領域深度知識與長期維護資源的工作，超出 AIKT「知識工作流編排」的定位範圍。

7. 效能、限制與替代方案 (Performance, Limitations & Alternatives)

7.1 效能數據

• 資料規模：17,080 疾病節點、100,000+ 總節點、4,050,249 條邊、29 種關係類型
• 檔案大小：kg.csv 完整版約數百 MB（依 pandas 載入記憶體用量會放大 3-5 倍，建議至少 8GB RAM 的機器操作）
• 載入時間：一般筆電上 pd.read_csv 載入完整版約需 30 秒至 2 分鐘（視磁碟速度與是否指定 dtype）
• 知識圖譜嵌入訓練基準：官方論文與後續 TxGNN 論文中，在完整 PrimeKG 上訓練 GNN 模型（如 R-GCN、TransE）通常需要 GPU 環境，訓練時間依模型架構從數小時到 1-2 天不等

7.2 已知限制

1. 官方已宣告淘汰：README 明確標示已被 OptimusKG 取代，這意味著 PrimeKG 本身不會再有主動的資料更新（除非社群 PR），2023 年 12 月的 OMIM 補丁是最後一次重大更新
2. 實體對齊非完美：跨 20 個資料源的自動對齊，即便有 MONDO 作中央對照，仍難免有部分同義詞未被合併或誤合併的邊界案例，使用時建議對關鍵結論做人工抽樣驗證
3. 時效性落後：多數原始資料源（DrugBank、UMLS 等）持續更新，但 PrimeKG 的資料是特定時間點的快照（最新到 2023 年 7 月的資料源版本），不適合需要「當下最新」藥物核准狀態的場景
4. 缺乏因果推理保證：知識圖譜中的邊代表「已知關聯」（association），不代表因果關係（causation）——例如 gene_disease 邊可能只是統計關聯，不代表該基因真的致病，使用者必須自行查證原始文獻
5. 罕見疾病仍有覆蓋缺口：儘管特別強調罕見疾病覆蓋，但受限於原始資料源本身的偏誤（醫學研究天生偏重常見病），極罕見疾病的關聯仍然相對稀疏
6. 建構流程學習曲線高：若要重新建構或客製化圖（而非只用現成 kg.csv），需要理解 20+ 個獨立處理腳本、R 環境、多個外部 API 金鑰（如 OMIM API），對非原作者而言重現難度不低

7.3 與同類工具比較

7.4 何時使用 vs 何時不使用

適合使用 PrimeKG 的情境：

• 教學、方法學驗證、快速 prototype（因為社群工具鏈最成熟，TDC/PyKEEN 都有現成整合）
• 需要跟既有大量引用 PrimeKG 的論文做結果比對（reproducibility；再現性考量）
• 資源有限，想要一個「已經整合好、不需要自己跑 20 個資料源」的現成起點

不建議使用 PrimeKG 的情境：

• 需要當下最新資料的正式研究專案／臨床決策支援系統 → 應改用 OptimusKG 或直接查詢原始資料源
• 需要因果推理保證的場景（如安全性訊號偵測）→ 需搭配額外的因果推斷方法，不能只靠圖上的關聯邊
• 需要即時更新（如即時藥物核准狀態）→ 任何靜態快照型知識圖譜都不適合，應直接查 FDA/DrugBank 即時 API

8. 總結與建議 (Summary & Recommendations)

8.1 關鍵要點回顧

1. PrimeKG 的核心貢獻是「資料整合工程」，不是演算法創新——把 20 個異質生醫資料庫，透過本體論對齊（尤其倚賴 MONDO 作為疾病命名的中央對照），統一成一張橫跨 10 種生物學尺度、400 萬條關係的知識圖譜，發表在資料型期刊 Nature Scientific Data 而非演算法期刊，精準反映了這個定位。

2. 架構設計務實而非炫技：選擇邊列表 CSV 格式而非強制綁定圖資料庫，讓幾乎任何下游工具（pandas、NetworkX、PyTorch Geometric、PyKEEN、Neo4j）都能直接使用，這是「複雜度要跟問題匹配」的良好示範。

3. 與生態系高度整合：透過 TDC 與 PyKEEN 兩個下游工具，PrimeKG 已經成為 mims-harvard 實驗室及外部研究社群做 GNN 藥物發現研究的標準 benchmark 之一，這種「一次整合、多方受益」的模式正是它 791 顆星、154 次 fork 的價值來源。

4. 與 AIKT 是互補關係而非競爭關係：PrimeKG 是靜態的生醫領域知識資料，AIKT 是動態的知識工作流編排系統；PrimeKG 沒有「產出報告」的能力，AIKT 沒有（也不該嘗試建立）生醫實體對齊的能力。兩者最佳的結合點是「把 PrimeKG 的結構化證據，作為 AIKT 研究產出流程中可信賴的佐證來源」。

5. 官方已宣告世代交替：README 明確指向 OptimusKG 為後繼者，任何長期整合規劃都應該把這個遷移路徑納入考量，避免建立在即將停止維護的資料版本上。

8.2 最佳使用場景總結

• 學術教學與方法學驗證：因社群工具鏈成熟度最高，是理解「異質圖神經網路在精準醫療的應用」最好的入門資料集
• 快速假設探索：研究者對某個疾病/藥物有初步假設時，可以在幾分鐘內用 pandas 查詢驗證「知識圖譜裡有沒有支持這個假設的間接證據」
• 作為結構化事實查核層：在任何涉及生醫知識的 LLM 應用（包括 AIKT 各層）中，PrimeKG（或其後繼 OptimusKG）都可以扮演「防止 LLM 幻覺」的結構化事實來源

8.3 未來發展方向

1. 短期：對於任何新專案，建議直接評估遷移至 OptimusKG，僅在需要與既有 PrimeKG 論文結果比對再現性時才使用原始 PrimeKG
2. 中期（對 AIKT 而言）：依 6.4 節推薦的分階段方案，先在現有 Layer 文件中加入 PrimeKG/OptimusKG 交叉查詢指引（零成本），再視實際使用頻率評估是否需要獨立查詢工具
3. 長期（對整個領域而言）：知識圖譜與大型語言模型的融合（如 Graph-RAG、GNN 輔助的檢索增強生成）是明確的技術趨勢，PrimeKG/OptimusKG 這類結構化生醫知識底座，未來可能不再是「獨立分析工具」，而是逐漸內化成 LLM 推理管線中的一個檢索元件——這也正是 AIKT 「編排知識而非演算法」定位下，最自然的長期整合方向