Decagon 教學：多關係圖卷積網路的藥物交互作用預測

Repository: mims-harvard/decagon · ⭐ 472 · MIT License 論文：Zitnik M, Agrawal M, Leskovec J. Modeling polypharmacy side effects with graph convolutional networks. Bioinformatics. 2018;34(13):i457–i466. DOI: 10.1093/bioinformatics/bty294

目錄

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 一句話說明

Decagon 是一個 graph convolutional network (GCN; 圖卷積網路)，用來在一張「同時包含基因、藥物、副作用」的多模態圖 (multimodal graph; 多模態圖) 上學習節點嵌入 (node embedding; 節點嵌入)，並用這些嵌入去預測「兩種藥物同時服用時會不會產生某種副作用」。這個問題在藥理學上稱為 polypharmacy side effect (多重用藥副作用) 預測。

1.2 用生活化比喻理解問題

想像一個病人因為慢性病同時吃五種藥：降血壓藥、降血糖藥、抗凝血藥、止痛藥、抗憂鬱藥。每一種藥單獨吃的副作用，藥廠都做過臨床試驗、寫在仿單上。但「這五種藥兩兩搭配、甚至三種一起吃」會不會出現新的、單一藥物不會出現的副作用（例如心律不整、肌肉病變），這件事幾乎不可能靠臨床試驗窮舉——藥物組合數是「藥物數的平方甚至立方」量級，而每一種組合又對應數百種可能的副作用，臨床試驗不可能測完全部組合。

Decagon 把這個問題想成一個「超大型的人際關係圖」：

• 藥物 (drug) 好比社群網路裡的「使用者」。
• 蛋白質/基因 (protein/gene) 好比使用者背後的「工作單位」——每個藥物會去「攻擊」或「調節」某些蛋白質（如同員工屬於某些部門）。
• 蛋白質之間的交互作用 (protein-protein interaction, PPI) 好比部門之間本來就有的合作關係。
• 已知的藥物-藥物副作用 (drug-drug side effect) 好比「兩個使用者之間曾經發生過某種特定類型的衝突事件」，而衝突類型有上千種（上千種副作用）。

Decagon 的任務就是：看過這張「使用者-部門-合作關係-已知衝突類型」的圖之後，去預測「兩個目前沒有記錄過某類衝突的使用者，未來是否會出現這類衝突」——也就是預測「這兩種藥物一起吃，會不會出現某個特定副作用」。

這比傳統的「單一關係」link prediction (連結預測) 難得多，因為：

1. 這是多模態圖——節點有兩種類型（藥物、蛋白質），邊也有多種類型（PPI、drug-target、964 種不同的 drug-drug side effect）。
2. 每一種副作用本質上是「一種獨立的邊類型」，Decagon 必須同時對上千種邊類型做 link prediction，而且很多副作用類型的已知樣本非常稀少（class imbalance; 類別不平衡）。

1.3 在生物醫學 AI 領域的重要性與地位

Decagon 發表於 2018 年 ISMB（Intelligent Systems for Molecular Biology）會議並刊登於 Bioinformatics，是生物醫學圖神經網路 (Graph Neural Network, GNN; 圖神經網路) 早期最具影響力的代表作之一。它的重要性體現在幾個層面：

• 首次把 multi-relational GCN 應用到真實臨床規模的藥物安全問題：模型在論文中處理了 645 種藥物、19,085 個蛋白質、715,612 個藥物-蛋白質邊，以及 4,651,131 個藥物-藥物邊（涵蓋 964 種不同副作用類型），這是當時同類研究中規模數一數二大的異質圖 (heterogeneous graph; 異質圖)。
• 奠定了「異質圖 + 關係專屬解碼器 (relation-specific decoder)」的設計範式：後續大量藥物-靶點 (drug-target)、藥物-疾病 (drug-disease)、藥物重定位 (drug repurposing) 的圖神經網路研究，都沿用了 Decagon 提出的「GCN encoder + DEDICOM/DistMult/Bilinear decoder」架構。
• 是 Marinka Zitnik 實驗室（現為 Harvard MIMS Lab）系列研究的起點：後續如 OGB-Biomed、TxGNN（藥物重定位圖神經網路）、GraphXAI（圖神經網路可解釋性）等專案，其問題設定與圖資料結構都可以追溯到 Decagon 的多模態圖框架。
• 被廣泛用作 GNN 課程與教科書的範例：Decagon 常出現在 Stanford CS224W（圖機器學習課程）的教材中，是理解「heterogeneous GNN for link prediction」的入門經典案例。

截至 2026 年，該論文已被引用超過 1,500 次（依 Google Scholar 統計級數估計），GitHub repo 累積 472 顆星、155 次 fork，顯示其作為教學與研究基準 (benchmark; 基準) 的長尾價值持續存在。

1.4 相關論文與引用

主要論文：

 1@article{Zitnik2018,
 2  title     = {Modeling polypharmacy side effects with graph convolutional networks},
 3  author    = {Zitnik, Marinka and Agrawal, Monica and Leskovec, Jure},
 4  journal   = {Bioinformatics},
 5  volume    = {34},
 6  number    = {13},
 7  pages     = {i457--i466},
 8  year      = {2018},
 9  publisher = {Oxford University Press},
10  doi       = {10.1093/bioinformatics/bty294}
11}

延伸閱讀方向（同一研究脈絡）：

• Zitnik lab 後續發展出的 TxGNN：把 Decagon 的異質圖思路延伸到 drug repurposing (藥物重定位)。
• Multiscale Interactome：延伸多層級 PPI + 藥物-疾病圖的研究。
• 原始資料集 SNAP Decagon dataset：至今仍是 polypharmacy side effect prediction 任務的標準 benchmark 資料集之一，被許多後續論文（如 Deac et al. 2019 的 co-attention 模型、Chen et al. 2021 的 hyperbolic embedding 方法）拿來比較。

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

mims-harvard（Marinka Zitnik’s lab, Harvard Medical School — Biomedical Informatics）目前維護數十個 GitHub repo，涵蓋圖神經網路、藥物發現、細胞生物學 AI 等領域。Decagon 是這個生態系中歷史最早、概念最基礎的一個節點——它建立的「異質圖 encoder-decoder」範式，是後續多個專案的技術先祖：

1.6 專案在生醫 AI 版圖中的位置（Mermaid 圖）

flowchart TB
    subgraph SG1["生醫資料層"]
        A1["蛋白質交互作用
PPI 資料庫"]
        A2["藥物-靶點資料
DrugBank/STITCH"]
        A3["FDA 不良事件報告
polypharmacy side effects"]
    end

    subgraph SG2["圖神經網路方法層"]
        B1["Decagon
異質圖 GCN"]
        B2["TxGNN
藥物重定位"]
        B3["同儕方法
KGE/HAN/HGT 等"]
    end

    subgraph SG3["下游應用層"]
        C1["藥物安全性預測
drug-drug interaction"]
        C2["藥物重定位
drug repurposing"]
        C3["精準用藥決策支持"]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> C1
    B1 -.啟發架構.-> B2
    B1 -.同類方法比較.-> B3
    B2 --> C2
    B1 --> C3

    style B1 fill:#FDE68A,color:#0F172A
    style A3 fill:#BFDBFE,color:#0F172A

1.7 核心貢獻總結

1. 問題定義：首次系統性地把「藥物組合副作用預測」定式化為「異質多關係圖上的 link prediction」問題。
2. 模型設計：提出可擴展到上千種邊類型的 GCN encoder，搭配四種可切換的關係解碼器（innerproduct、distmult、bilinear、dedicom）。
3. 資料集貢獻：整理並公開了目前仍被廣泛引用的 polypharmacy side effect 資料集。
4. 實證結果：在真實資料上，Decagon 對高頻副作用類型的 AUROC 可達 0.87 以上（依原始論文報告，數字隨副作用類型與版本而異），顯著優於當時只用單一藥物特徵、不建模蛋白質網路的基準方法。

1.8 研究脈絡年表：Decagon 從哪裡來、往哪裡去

理解一個經典模型的位置，不能只看它自己，還要看它站在哪個時間點、承接了什麼、又啟發了什麼。以下用時間軸梳理 polypharmacy GNN 這個研究方向的演進：

這個年表傳達的關鍵訊息：Decagon 不是一個孤立的模型，而是「異質圖 GNN 應用於生醫問題」這條研究路線上的一個重要里程碑節點——它證明了這個方法路線可行且有效，但它本身留下的限制（可解釋性、inductive 泛化），正是後續八年研究持續在填補的空缺。理解這一點，也是本文件第 6 節分析 AIKT 整合策略時的重要前提：AIKT 若要做「知識脈絡串接」，串接的不只是 Decagon 這一個 repo，而是這整條研究路線的完整脈絡。

1.9 誰在用這個 repo：使用者輪廓

依 GitHub 統計數據（472 stars、155 forks）與常見引用場景推斷，Decagon 的實際使用者大致分為三類：

1. 學術研究者：把 Decagon 當作 baseline 方法，在自己提出的新方法論文中做效能比較（這也是為什麼 fork 數相對星數比例不低——155 forks 對 472 stars，代表相當高比例的關注者確實動手修改過程式碼做實驗，而不只是「加星收藏」）。
2. 研究方法課程的教學者與學生：如前述提及的 Stanford CS224W，把 Decagon 當作異質圖神經網路的教學範例，這也解釋了為什麼即使原始程式碼已經數年沒有更新，repo 依然持續有新的關注與流量。
3. 生技/製藥產業的探索性評估團隊：在評估「是否該投資 GNN 方法來做藥物安全性篩查」時，Decagon 常是第一個被拿來做概念驗證 (proof of concept) 的候選模型，因為它是這個問題領域中最知名、文件相對完整、且有已發表論文佐證效能的選項。

2. 核心架構 (Core Architecture)

2.1 整體資料結構：異質多重圖

Decagon 建模的圖包含兩種節點類型（object type）：

• type 0 = 基因/蛋白質 (gene/protein)
• type 1 = 藥物 (drug)

以及依「節點類型配對 (i, j)」分組的多種邊類型：

這種「同一對節點類型下可以有 K 種不同語義邊」的設計，正是 Decagon 論文標題中「multirelational」的核心：模型不是做「有沒有邊」的二元判斷，而是做「這條邊屬於哪一種副作用類型」的多重判斷。

2.2 系統架構圖（Mermaid Flowchart）

flowchart LR
    subgraph SG_INPUT["輸入層"]
        I1["基因特徵矩陣
gene_feat (identity matrix)"]
        I2["藥物特徵矩陣
drug_feat (identity matrix)"]
        I3["鄰接矩陣集合
adj_mats[i,j][k]"]
    end

    subgraph SG_ENC["Encoder: 兩層 Graph Convolution"]
        E1["GraphConvolutionSparseMulti
第一層：input → hidden1 (64維)"]
        E2["ReLU + 跨關係加總
tf.add_n"]
        E3["GraphConvolutionMulti
第二層：hidden1 → hidden2 (32維)"]
        E4["跨關係加總
得到最終節點嵌入"]
    end

    subgraph SG_EMB["節點嵌入"]
        M1["基因嵌入
embeddings[0]"]
        M2["藥物嵌入
embeddings[1]"]
    end

    subgraph SG_DEC["Decoder: 關係專屬解碼器"]
        D1["InnerProduct"]
        D2["DistMult"]
        D3["Bilinear"]
        D4["DEDICOM"]
    end

    subgraph SG_OUT["輸出層"]
        O1["邊分數 (logit)
經 sigmoid → 機率"]
        O2["Loss: 交叉熵 / Hinge loss"]
    end

    I1 --> E1
    I2 --> E1
    I3 --> E1
    E1 --> E2 --> E3 --> E4
    E4 --> M1
    E4 --> M2
    M1 --> D1
    M2 --> D1
    M1 --> D2
    M2 --> D2
    M1 --> D3
    M2 --> D3
    M1 --> D4
    M2 --> D4
    D1 --> O1
    D2 --> O1
    D3 --> O1
    D4 --> O1
    O1 --> O2

    style E1 fill:#FDE68A,color:#0F172A
    style E3 fill:#FDE68A,color:#0F172A
    style D4 fill:#BFDBFE,color:#0F172A

架構的關鍵洞察：注意圖中「跨關係加總 (tf.add_n)」這個動作——它是整個架構能夠處理「多關係」的核心技巧。對於基因節點 (type 0)，它同時透過「PPI 邊」與「drug→gene 邊」（也就是 (0,0) 和 (0,1) 兩種配對）接收訊息，並把兩種訊息相加成一個統一的隱藏表徵，再送進下一層。這等同於「一個人同時透過同事關係與客戶關係收到資訊，並把這些資訊整合成對這個人的綜合理解」。

2.3 資料流向圖（Mermaid Sequence Diagram）

sequenceDiagram
    participant Main as main.py
    participant MB as EdgeMinibatchIterator
    participant Model as DecagonModel
    participant Opt as DecagonOptimizer
    participant TF as TensorFlow Session

    Main->>Main: 構建 adj_mats_orig（PPI, drug-target, drug-drug）
    Main->>Main: 構建 gene_feat / drug_feat（identity matrix）
    Main->>MB: 建立 minibatch iterator (batch_size=512)
    Main->>Model: 建立 DecagonModel(placeholders, edge_types, decoders)
    Model->>Model: _build() 兩層 GCN forward pass
    Main->>Opt: 建立 DecagonOptimizer(embeddings, degrees, margin)
    Opt->>Opt: 定義 hinge loss / cross-entropy loss

    loop 每個 epoch
        MB->>MB: shuffle edges, 依邊類型抽 minibatch
        loop 每個 minibatch
            MB->>TF: feed_dict (batch, edge_type, adj_mats, dropout)
            TF->>Model: forward pass 計算 embeddings
            Model->>Opt: 傳入 latent_inters / latent_varies
            Opt->>TF: 計算 loss + 梯度
            TF->>TF: Adam optimizer 更新權重
        end
        Main->>Main: 每 150 iteration 印出 val AUROC/AUPRC
    end

    Main->>Main: 在測試集上計算 get_accuracy_scores()
    Main->>Main: 輸出 ROC-AUC / AUPRC / apk@50

2.4 關鍵演算法與方法論：具體範例逐步拆解

以下用一個「五個節點的迷你藥理網路」具體示範 Decagon 的核心運算。

情境設定：3 個藥物（阿斯匹靈 A、華法林 W、布洛芬 I），2 個蛋白質（COX-1、CYP2C9）。已知：

• A 與 I 都調節 COX-1（drug→gene 邊）
• W 由 CYP2C9 代謝（drug→gene 邊）
• COX-1 與 CYP2C9 有已知的蛋白質交互作用（PPI 邊）
• A + W 已知會有「出血風險增加」的副作用記錄（drug-drug 邊，副作用類型 0）
• 我們想預測：I + W 是否也可能有「出血風險增加」的副作用？

Step 1 — 特徵初始化（featureless 節點）：

因為原始論文中蛋白質與藥物往往沒有現成的數值特徵，Decagon 對「無特徵」節點使用 identity matrix（單位矩陣）作為輸入特徵——這等同於把每個節點當成一個 one-hot 編碼的 ID，讓模型完全從圖結構（誰跟誰有連接）去學習表徵，而不依賴外部特徵。這對應到程式碼：

1# main.py 中的 featureless 節點處理
2gene_feat = sp.identity(n_genes)
3gene_nonzero_feat, gene_num_feat = gene_feat.shape
4gene_feat = preprocessing.sparse_to_tuple(gene_feat.tocoo())

Step 2 — 第一層圖卷積（訊息傳遞）：

COX-1 的新表徵，是「COX-1 自己的特徵」經過線性轉換後，再加總「鄰居（A、I、CYP2C9）透過各自邊類型傳來的訊息」。用比喻來說：COX-1 這個蛋白質的「身份」，一部分來自它調節的兩種藥物（A、I）告訴它的訊息，一部分來自跟它有 PPI 的 CYP2C9 告訴它的訊息——三種聲音疊加起來，就是 COX-1 在這一層的新表徵。

Step 3 — 第二層圖卷積（進一步抽象）：

同樣的訊息傳遞機制再做一次，把 hidden1 的 64 維表徵壓縮抽象成 hidden2 的 32 維嵌入。兩層的堆疊讓資訊可以傳遞「兩步之遠」——也就是說，布洛芬 I 的嵌入，不只包含它直接調節 COX-1 的資訊，還間接包含「COX-1 與 CYP2C9 有交互作用、CYP2C9 又代謝華法林 W」這種兩步之外的資訊。這正是為什麼 Decagon 能發現「表面上沒有直接關係，但透過蛋白質網路間接相關」的藥物組合風險。

Step 4 — DEDICOM 解碼器算分數（判斷藥物-藥物邊的存在機率）：

對於藥物-藥物副作用預測（(1,1) 這一組配對），Decagon 使用 DEDICOM (DEcomposition into DIrectional COMponents) 解碼器。DEDICOM 的核心公式是：

1score(u, v, r) = z_u^T · D_r · R · D_r · z_v

其中 z_u, z_v 是藥物 I 與 W 的嵌入向量，R 是所有副作用類型共享的全域交互矩陣 (global interaction matrix)，D_r 是副作用類型 r 專屬的對角矩陣 (relation-specific diagonal matrix)。

這個設計的巧妙之處：它讓「964 種副作用」不需要各自學一個完全獨立的巨大矩陣（那樣參數量會爆炸、也無法共享知識），而是共用一個「基礎交互模式 R」，再用一個很小的對角矩陣 D_r 去「微調」出每種副作用類型特有的變化。用比喻來說：R 好比「兩種藥物一般會如何交互作用的通用規則」，而 D_r 好比「出血風險」「心律不整」「肌肉病變」各自對這個通用規則的「特殊放大鏡」。這讓模型能在副作用樣本稀少時（例如某種罕見副作用只有幾十個已知案例），依然透過「共享的 R」借用其他副作用類型學到的通用交互模式，達到參數效率高、泛化能力強的效果。

Step 5 — 算出 I+W 出血風險的預測分數：

1score(I, W, "出血風險") = sigmoid(z_I^T · D_出血風險 · R · D_出血風險 · z_W)

如果這個分數高於某個門檻（或相對排序在測試集前面），模型就預測「布洛芬 + 華法林」可能有出血風險——這與臨床藥理學已知的「NSAIDs 與抗凝血劑併用會增加出血風險」的真實知識吻合，展示了 Decagon 從圖結構「學出」臨床已知交互作用模式的能力。

2.5 內部元件互動方式

程式碼組織上，Decagon 的元件分工非常清晰：

 1decagon/
 2├── deep/
 3│   ├── layers.py       # GraphConvolutionMulti, GraphConvolutionSparseMulti,
 4│   │                    # DistMultDecoder, InnerProductDecoder,
 5│   │                    # DEDICOMDecoder, BilinearDecoder
 6│   ├── model.py         # DecagonModel — 組裝 encoder + decoder
 7│   ├── minibatch.py      # EdgeMinibatchIterator — 依邊類型抽樣、切 train/val/test
 8│   ├── optimizer.py      # DecagonOptimizer — 定義 loss（hinge / cross-entropy）
 9│   └── inits.py          # 權重初始化（Xavier/Glorot 等）
10└── utility/
11    ├── preprocessing.py  # 稀疏矩陣 ↔ tuple 格式互轉、mask/normalize adjacency
12    └── rank_metrics.py    # apk (average precision at k) 等排序指標

元件互動的關鍵設計：DecagonModel.__init__ 接收的 edge_types 是一個 {(i,j): 邊類型數量} 的字典，decoders 是一個 {(i,j): 解碼器名稱} 的字典——這種「用 dict 描述異質結構」的設計讓整個框架具備高度擴展性：如果你想加入第三種節點類型（例如「疾病」節點），只需要在 adj_mats_orig、edge_type2decoder、num_feat 這幾個字典中新增對應的 key，DecagonModel._build() 的迴圈邏輯（for i, j in self.edge_types）會自動處理新的節點/邊類型，不需要修改核心模型程式碼。這是一種「用資料結構消除特殊情況」的優秀設計範例——不管有 2 種還是 5 種節點類型，2 種還是 964 種邊類型，跑的都是同一套迴圈。

2.6 負採樣與資料切分：EdgeMinibatchIterator 的角色

Link prediction 問題天生面臨一個資料結構上的挑戰：資料集裡通常只記錄「確實存在的邊」（例如「已知阿斯匹靈+華法林有出血風險」），卻不會有人記錄「不存在的邊」（沒有人會特地寫「阿斯匹靈+維生素C沒有已知交互作用」）。如果模型只看到正樣本，它永遠學不會「區分」，因為它從沒見過負面案例長什麼樣子。

EdgeMinibatchIterator（decagon/deep/minibatch.py）解決這個問題的方式是負採樣 (negative sampling)：對每一個真實存在的邊 (u, v)，隨機抽取一個「不存在」的配對 (u, v') 作為負樣本，前提是這個負樣本配對在原始鄰接矩陣中確實標記為 0（也就是「目前沒有記錄」）。這個機制對應到現實世界的比喻：如果我們要訓練一個「這兩個人是不是朋友」的分類器，只給模型看真實的朋友對是不夠的，還需要故意配對一些「應該不是朋友」的隨機組合，讓模型學會「什麼樣的特徵組合看起來不像朋友」。

此外，EdgeMinibatchIterator 也負責把每一種邊類型各自的邊集合切成訓練/驗證/測試三份（依 val_test_size 參數，範例中設為 0.05，即 5% 作為驗證、5% 作為測試）。這個切分是「依邊類型分別進行」，而不是把所有邊混在一起切——這個細節很重要：因為不同副作用類型的樣本量天差地遠（前述範例中 143 vs 52），如果混著切，可能導致某些稀有副作用類型在測試集裡一個樣本都沒有，或者反過來訓練集裡樣本太少而學不到任何模式。依類型分別切分，確保每種副作用類型在訓練/驗證/測試集中都保持合理的比例，這是處理極度不平衡多關係資料時的標準作法。

2.7 訓練穩定性技巧：為什麼要動態調整 batch 抽樣的邊類型

觀察 main.py 訓練迴圈的邏輯（minibatch.shuffle() 及 minibatch.next_minibatch_feed_dict()），可以發現 Decagon 不是每個 minibatch 都固定用同一種邊類型訓練，而是在每個 epoch 開始時打亂所有邊類型的訓練順序，讓模型在一個 epoch 內輪流看過所有邊類型的樣本。這個設計的用意，是避免模型在訓練過程中「過度擬合到最近看到的那種邊類型」而忘記之前學到的其他關係模式——這是多任務學習 (multi-task learning) 中常見的「災難性遺忘 (catastrophic forgetting)」風險的一種緩解手段。用比喻來說，如果一個學生準備考試時，先把物理題目做完才做化學題目，很容易「做化學題目時已經忘了物理公式」；反過來，如果每一輪練習都輪流穿插不同科目的題目，反而更容易讓大腦同時保持多個知識領域的活躍記憶。

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

3.1 前置需求

Decagon 是一個 2018 年發表、以 TensorFlow 1.x (static graph API) 撰寫的專案，官方 requirements.txt 鎖定的版本相當舊：

1tensorflow==1.8.0
2scikit-learn==0.19.1
3networkx==2.0
4numpy==1.14.5
5scipy==1.1.0

這代表不能直接用現代 Python 3.11+ / TensorFlow 2.x 環境跑，需要額外處理相容性問題。以下提供三種安裝路徑，依可控性與維護成本排序。

3.2 方法一：Docker 容器化安裝（最推薦，符合可重建原則）

這是最乾淨的方式，因為它把「舊版 TensorFlow 1.8 + Python 2/3」的相容性問題完全封裝在容器內，不污染本機環境。

 1# Dockerfile
 2FROM tensorflow/tensorflow:1.8.0-py3
 3
 4WORKDIR /workspace
 5RUN git clone https://github.com/mims-harvard/decagon.git .
 6RUN pip install --no-cache-dir \
 7    scikit-learn==0.19.1 \
 8    networkx==2.0 \
 9    scipy==1.1.0 \
10    numpy==1.14.5
11
12CMD ["python", "main.py"]

1# 建置與執行
2docker build -t decagon:legacy .
3docker run --rm -it decagon:legacy

若使用 Podman（依全域規範優先選項之一）：

1podman build -t decagon:legacy .
2podman run --rm -it decagon:legacy

3.3 方法二：uv 建立隔離虛擬環境（次推薦）

若不想用容器，依全域工具鏈規範，Python 專案應優先用 uv 建虛擬環境而非裸 pip：

 1# 建立指定 Python 版本的虛擬環境（TF 1.8 相容性最好用 Python 3.6）
 2uv venv --python 3.6 decagon-env
 3source decagon-env/bin/activate
 4
 5# 用 uv pip 安裝（比 pip 快，且仍受 uv 環境管理）
 6uv pip install tensorflow==1.8.0 scikit-learn==0.19.1 networkx==2.0 scipy==1.1.0 numpy==1.14.5
 7
 8git clone https://github.com/mims-harvard/decagon.git
 9cd decagon
10python main.py

注意：Python 3.6 已於 2021 年停止官方支援，若本機已無法取得對應版本，建議直接採用方法一（Docker）或方法三（現代化改寫）。

3.4 方法三：升級到 TensorFlow 2.x 相容模式（適合長期維護）

若計畫長期使用或整合進新專案，建議用 TF2 的 tf.compat.v1 相容層執行，只需在程式碼最前面加入：

1# 在 main.py 開頭加入，讓 TF2 環境模擬 TF1 static graph 行為
2import tensorflow.compat.v1 as tf
3tf.disable_v2_behavior()

搭配現代環境：

1uv venv --python 3.10 decagon-env
2source decagon-env/bin/activate
3uv pip install "tensorflow<2.11" scikit-learn networkx scipy numpy

限制：tf.compat.v1 相容層無法保證所有 API（例如 tf.app.flags）行為完全一致，flags.DEFINE_integer 等舊式參數解析在 TF2.11+ 之後的相容層可能出現警告或需要手動改寫成 argparse。建議先在 Docker 隔離環境測試通過後才考慮升級改寫。

3.5 環境設定：下載完整資料集

main.py 內建的是合成玩具資料（用 networkx.planted_partition_graph 隨機生成），僅用於展示程式碼如何運作。若要重現論文結果，須到官方資料頁下載真實資料：

 1# 建立資料目錄
 2mkdir -p data/decagon
 3cd data/decagon
 4
 5# 從 SNAP 官網下載（需手動至 http://snap.stanford.edu/decagon 取得下載連結）
 6# 主要檔案包含：
 7#   bio-decagon-combo.csv       # 藥物-藥物副作用 (polypharmacy)
 8#   bio-decagon-mono.csv        # 單一藥物副作用
 9#   bio-decagon-ppi.csv         # 蛋白質-蛋白質交互作用
10#   bio-decagon-targets.csv     # 藥物-靶點交互作用
11#   bio-decagon-targets-all.csv # 擴充版藥物-靶點交互作用

下載後需自行撰寫資料載入程式碼，把 CSV 轉換成 main.py 中 adj_mats_orig 所需的 scipy.sparse 矩陣格式（範例見第 4 節）。

3.6 驗證安裝

 1# 驗證 TensorFlow 版本與基本運作
 2python -c "import tensorflow as tf; print(tf.__version__); print(tf.constant('Decagon OK'))"
 3
 4# 驗證核心套件版本
 5python -c "import networkx, scipy, sklearn; \
 6  print('networkx:', networkx.__version__); \
 7  print('scipy:', scipy.__version__); \
 8  print('sklearn:', sklearn.__version__)"
 9
10# 跑最小的合成資料範例，確認整條 pipeline 沒有壞
11cd decagon
12python main.py

預期輸出應類似：

1Edge types: 8
2Defining placeholders
3Create minibatch iterator
4Create model
5Create optimizer
6Initialize session
7...
8Epoch: 0001 Iter: 0000 Edge: (0, 0) train_loss= 0.693 ...

若能看到 Edge: 開頭的訓練 log 逐步印出、loss 數值逐漸下降，即代表環境設定成功。

4. 基本使用 (Basic Usage)

4.1 快速入門：跑通內建的合成範例

最快驗證環境是否正常的方式，就是直接跑官方內建範例：

1python main.py

這會用 nx.planted_partition_graph(50, 10, 0.2, 0.05, seed=42) 生成一個 500 節點的基因網路，隨機生成 400 個藥物節點，以及 3 種合成的藥物-藥物副作用邊類型，然後訓練 50 個 epoch。因為資料是完全隨機生成，不具備真實生物意義，這一步的目的只是驗證程式碼能跑、環境沒問題，不是產生有意義的科學結論。

4.2 範例一：理解輸入資料格式

Decagon 期待的核心資料結構是「以節點類型配對 (i, j) 為 key 的鄰接矩陣字典」。以下範例示範如何從零手動建構一個最小的異質圖輸入：

 1import numpy as np
 2import scipy.sparse as sp
 3import networkx as nx
 4
 5# ---- 步驟 1：定義節點數量 ----
 6n_genes = 500   # 基因/蛋白質節點數
 7n_drugs = 400   # 藥物節點數
 8n_drugdrug_rel_types = 3  # 副作用類型數（教學範例用 3 種）
 9
10# ---- 步驟 2：建立蛋白質-蛋白質交互作用網路 (PPI) ----
11gene_net = nx.planted_partition_graph(50, 10, 0.2, 0.05, seed=42)
12gene_adj = nx.adjacency_matrix(gene_net)          # scipy sparse matrix
13gene_degrees = np.array(gene_adj.sum(axis=0)).squeeze()
14
15# ---- 步驟 3：建立藥物-蛋白質靶點關係 (drug-target) ----
16# 這裡用隨機二元矩陣模擬「藥物是否調節某蛋白質」
17gene_drug_adj = sp.csr_matrix(
18    (10 * np.random.randn(n_genes, n_drugs) > 15).astype(int)
19)
20drug_gene_adj = gene_drug_adj.transpose(copy=True)  # 反向邊
21
22# ---- 步驟 4：組裝成 Decagon 所需的字典結構 ----
23adj_mats_orig = {
24    (0, 0): [gene_adj, gene_adj.transpose(copy=True)],  # 蛋白質-蛋白質（含反向）
25    (0, 1): [gene_drug_adj],                             # 蛋白質被藥物調節
26    (1, 0): [drug_gene_adj],                             # 藥物調節蛋白質
27    (1, 1): [],  # drug-drug 邊類型稍後填入（見範例二）
28}
29
30print("節點類型 0（基因）數量:", n_genes)
31print("節點類型 1（藥物）數量:", n_drugs)
32print("(0,1) 邊數量:", gene_drug_adj.nnz)

輸出範例：

1節點類型 0（基因）數量: 500
2節點類型 1（藥物）數量: 400
3(0,1) 邊數量: 812

4.3 範例二：建構藥物-藥物副作用邊（多種邊類型）

這是 Decagon 最核心的部分——把「多種副作用」表示成「多種邊類型」：

 1from itertools import combinations
 2
 3# ---- 用蛋白質共同靶點模擬藥物-藥物潛在關係強度 ----
 4tmp = np.dot(drug_gene_adj, gene_drug_adj)  # (n_drugs x n_drugs)，值越大表示共享越多靶點蛋白質
 5
 6drug_drug_adj_list = []
 7for rel_type_idx in range(n_drugdrug_rel_types):
 8    mat = np.zeros((n_drugs, n_drugs))
 9    for d1, d2 in combinations(range(n_drugs), 2):
10        # 用共享靶點數量的不同區間，模擬不同的副作用類型
11        if tmp[d1, d2] == rel_type_idx + 4:
12            mat[d1, d2] = mat[d2, d1] = 1.0
13    drug_drug_adj_list.append(sp.csr_matrix(mat))
14    print(f"副作用類型 {rel_type_idx}: {int(mat.sum() / 2)} 組藥物配對")
15
16# 補上反向邊，並整合進 adj_mats_orig
17adj_mats_orig[(1, 1)] = drug_drug_adj_list + [
18    x.transpose(copy=True) for x in drug_drug_adj_list
19]
20
21drug_degrees_list = [
22    np.array(drug_adj.sum(axis=0)).squeeze() for drug_adj in drug_drug_adj_list
23]

輸出範例：

1副作用類型 0: 143 組藥物配對
2副作用類型 1: 87 組藥物配對
3副作用類型 2: 52 組藥物配對

這個輸出清楚展現了 polypharmacy 資料的典型特徵：不同副作用類型的樣本數天差地遠（143 vs 52），這正是為什麼 Decagon 的 DEDICOM 解碼器要設計成「共享全域矩陣 R + 各自微調 D_r」——讓樣本稀少的副作用類型也能借助樣本豐富的類型學到的通用模式。

4.4 範例三：訓練模型並解讀輸出指標

 1# main.py 完整流程節錄：設定超參數、建立模型、訓練
 2
 3flags = tf.app.flags
 4FLAGS = flags.FLAGS
 5flags.DEFINE_integer('epochs', 50, 'Number of epochs to train.')
 6flags.DEFINE_integer('hidden1', 64, 'Number of units in hidden layer 1.')
 7flags.DEFINE_integer('hidden2', 32, 'Number of units in hidden layer 2.')
 8flags.DEFINE_float('learning_rate', 0.001, 'Initial learning rate.')
 9flags.DEFINE_float('dropout', 0.1, 'Dropout rate.')
10flags.DEFINE_integer('batch_size', 512, 'minibatch size.')
11
12# 訓練迴圈核心邏輯（節錄自 main.py）
13for epoch in range(FLAGS.epochs):
14    minibatch.shuffle()
15    itr = 0
16    while not minibatch.end():
17        feed_dict = minibatch.next_minibatch_feed_dict(placeholders=placeholders)
18        feed_dict = minibatch.update_feed_dict(
19            feed_dict=feed_dict, dropout=FLAGS.dropout, placeholders=placeholders
20        )
21        outs = sess.run(
22            [opt.opt_op, opt.cost, opt.batch_edge_type_idx],
23            feed_dict=feed_dict
24        )
25        train_cost = outs[1]
26
27        if itr % PRINT_PROGRESS_EVERY == 0:
28            val_auc, val_auprc, val_apk = get_accuracy_scores(
29                minibatch.val_edges, minibatch.val_edges_false,
30                minibatch.idx2edge_type[minibatch.current_edge_type_idx]
31            )
32            print(f"Epoch: {epoch+1:04d} Iter: {itr:04d} "
33                  f"train_loss={train_cost:.5f} val_roc={val_auc:.5f} "
34                  f"val_auprc={val_auprc:.5f}")
35        itr += 1

如何解讀輸出：

• train_loss：越低表示模型在訓練集上越能區分「真實邊」與「隨機負樣本邊」。
• val_roc（ROC-AUC）：0.5 代表隨機猜測，1.0 代表完美區分；論文報告在真實資料上，高頻副作用類型可達 0.87+。
• val_auprc（AUPRC）：在極度類別不平衡（真實副作用邊遠少於「沒有副作用」的配對）情境下，比 ROC-AUC 更能反映實際預測品質。
• apk@50（average precision at k=50）：模擬「藥師實務上只會看排名前 50 的候選副作用警示」情境下的精確度，是貼近臨床應用場景的排序指標。

4.5 生物醫學場景範例：解讀一次真實預測

假設訓練完成後，我們想查詢「藥物 A（心臟病用藥）與藥物 B（抗生素）是否有心律不整風險」：

 1def query_drug_pair_risk(model_output, drug_a_idx, drug_b_idx, side_effect_idx, sess, feed_dict):
 2    """查詢特定藥物配對在特定副作用類型下的風險分數。"""
 3    feed_dict.update({placeholders['batch_edge_type_idx']: side_effect_idx})
 4    rec = sess.run(opt.predictions, feed_dict=feed_dict)
 5
 6    def sigmoid(x):
 7        return 1.0 / (1 + np.exp(-x))
 8
 9    score = sigmoid(rec[drug_a_idx, drug_b_idx])
10    risk_level = "高風險" if score > 0.7 else ("中風險" if score > 0.4 else "低風險")
11    print(f"藥物 A(idx={drug_a_idx}) + 藥物 B(idx={drug_b_idx}) "
12          f"→ 副作用類型 {side_effect_idx} 預測分數: {score:.3f} ({risk_level})")
13    return score

這種輸出格式可以進一步整合進臨床決策支援系統：藥師輸入病人正在服用的多種藥物，系統跑一輪所有兩兩組合 × 所有副作用類型的預測，排序後回報「前 N 個最高風險的藥物-副作用組合」供人工複核——這正是論文中設想的實際應用場景。

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

5.1 進階配置選項：切換解碼器

Decagon 支援四種解碼器，適用於不同的邊類型語義，可以針對每一組節點配對 (i, j) 分別指定：

1edge_type2decoder = {
2    (0, 0): 'bilinear',   # PPI：對稱關係，bilinear 足夠表達
3    (0, 1): 'bilinear',   # drug→target：非對稱但關係單一
4    (1, 0): 'bilinear',   # target→drug（反向）
5    (1, 1): 'dedicom',    # drug-drug：多種副作用類型，需要 DEDICOM 的共享+微調機制
6}

選擇解碼器的判斷準則：

解碼器選擇決策流程（Mermaid Flowchart）：

flowchart TD
    Start["這組節點配對 (i,j)
有多少種邊類型？"]
    Q1{"邊類型數量
≤ 3 種？"}
    Q2{"關係是否
對稱？"}
    Q3{"是否需要
跨類型共享參數？"}

    Start --> Q1
    Q1 -->|是| Q2
    Q1 -->|否，數十種以上| Q3
    Q2 -->|對稱| R1["選 DistMult"]
    Q2 -->|非對稱| R2["選 Bilinear"]
    Q3 -->|需要| R3["選 DEDICOM
（如 964 種副作用）"]
    Q3 -->|不需要，各自獨立即可| R4["選 Bilinear
（每類型各自一個矩陣）"]

    style R3 fill:#FDE68A,color:#0F172A
    style Start fill:#BFDBFE,color:#0F172A

這張決策圖把「解碼器選型」從抽象的數學表達力比較，轉譯成一個可以直接套用的判斷流程：先問「這種邊有多少種語義變化」，再問「是否需要在這些變化之間共享知識」。對 Decagon 的核心應用場景（964 種副作用）而言，答案幾乎總是落在 DEDICOM 這一支——這也是論文選擇它作為 drug-drug 邊預設解碼器的根本原因。

5.2 進階配置：損失函數切換

DecagonOptimizer 支援 hinge loss 與 cross-entropy 兩種損失，可依資料特性選擇：

 1# Cross-entropy：適合大多數標準 link prediction 情境
 2flags.DEFINE_float('max_margin', 0.1, 'Max margin parameter in hinge loss')
 3
 4# main.py 中透過條件切換使用哪種 loss（見 optimizer.py 內部實作）
 5opt = DecagonOptimizer(
 6    embeddings=model.embeddings,
 7    latent_inters=model.latent_inters,
 8    latent_varies=model.latent_varies,
 9    degrees=degrees,
10    edge_types=edge_types,
11    edge_type2dim=edge_type2dim,
12    placeholders=placeholders,
13    batch_size=FLAGS.batch_size,
14    margin=FLAGS.max_margin  # hinge loss 使用的 margin 參數
15)

建議：若副作用類型間的正負樣本比例極度不平衡（例如某副作用只有 20 個已知案例，卻有數千個可能的負樣本配對），hinge loss 搭配適當的 margin 通常比 cross-entropy 更穩健，因為 hinge loss 只在「分數差距不足 margin」時才產生梯度，能避免模型被大量容易分類的負樣本主導訓練訊號。

5.3 實際應用案例一：整合真實 SNAP 資料集

以下示範如何把官方 CSV 資料轉換成 Decagon 所需的稀疏矩陣格式：

 1import pandas as pd
 2import scipy.sparse as sp
 3import numpy as np
 4
 5def load_real_decagon_data(data_dir="data/decagon"):
 6    """把 SNAP 官方 CSV 轉換為 Decagon 輸入格式。"""
 7    # 讀取藥物-藥物副作用資料（drug1, drug2, side_effect_id, side_effect_name）
 8    combo_df = pd.read_csv(f"{data_dir}/bio-decagon-combo.csv")
 9
10    # 建立藥物 ID → 矩陣索引的映射
11    all_drugs = sorted(set(combo_df['STITCH 1']) | set(combo_df['STITCH 2']))
12    drug2idx = {d: i for i, d in enumerate(all_drugs)}
13    n_drugs = len(all_drugs)
14
15    # 依副作用類型分組，各自建一個稀疏鄰接矩陣
16    side_effects = combo_df['Polypharmacy Side Effect'].unique()
17    drug_drug_adj_list = []
18    for se in side_effects[:50]:  # 範例僅取前 50 種最常見副作用（真實資料有 964 種）
19        se_df = combo_df[combo_df['Polypharmacy Side Effect'] == se]
20        rows = se_df['STITCH 1'].map(drug2idx).values
21        cols = se_df['STITCH 2'].map(drug2idx).values
22        mat = sp.csr_matrix(
23            (np.ones(len(rows)), (rows, cols)),
24            shape=(n_drugs, n_drugs)
25        )
26        drug_drug_adj_list.append(mat + mat.transpose())  # 確保對稱
27
28    print(f"載入 {n_drugs} 個藥物節點，{len(drug_drug_adj_list)} 種副作用類型")
29    return drug_drug_adj_list, drug2idx
30
31drug_drug_adj_list, drug2idx = load_real_decagon_data()

5.4 實際應用案例二：批次風險排序（臨床應用情境）

 1def rank_all_side_effects_for_pair(drug_a, drug_b, drug2idx, all_side_effects,
 2                                     sess, opt, placeholders, feed_dict_template):
 3    """對一組藥物配對，跑過所有副作用類型並依風險排序。"""
 4    results = []
 5    idx_a, idx_b = drug2idx[drug_a], drug2idx[drug_b]
 6
 7    for se_idx, se_name in enumerate(all_side_effects):
 8        feed_dict = dict(feed_dict_template)
 9        feed_dict.update({placeholders['batch_edge_type_idx']: se_idx})
10        rec = sess.run(opt.predictions, feed_dict=feed_dict)
11        score = 1.0 / (1 + np.exp(-rec[idx_a, idx_b]))
12        results.append((se_name, score))
13
14    results.sort(key=lambda x: x[1], reverse=True)
15    print(f"\n{drug_a} + {drug_b} 的前 10 大風險副作用：")
16    for se_name, score in results[:10]:
17        print(f"  {se_name:30s} 風險分數: {score:.3f}")
18    return results

這個模式正是把 Decagon 從「研究用模型」轉化為「決策支援工具」的關鍵一步：不再是單次查詢單個副作用，而是一次算出「這個藥物配對在所有已知副作用類型中的完整風險剖面」，供臨床藥師快速掃視。

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

與 NetworkX 整合：Decagon 原生就使用 networkx 生成合成圖，真實使用時也可以用 NetworkX 做圖分析（例如計算 degree centrality 找出「交互作用最複雜」的藥物或蛋白質，或用社群發現演算法找出功能相關的蛋白質群）：

1import networkx as nx
2
3# 從稀疏矩陣還原成 NetworkX 圖以做進一步分析
4G = nx.from_scipy_sparse_array(gene_adj)
5top_hub_genes = sorted(nx.degree_centrality(G).items(), key=lambda x: -x[1])[:10]
6print("交互作用網路中最中心的 10 個蛋白質:", top_hub_genes)

與現代 GNN 框架整合的可能性：雖然 Decagon 原生用 TensorFlow 1.x 手寫 GCN 層，但其核心概念（異質圖 + 關係專屬解碼器）完全可以用 PyTorch Geometric (PyG) 的 HeteroConv 或 DGL (Deep Graph Library) 的 HeteroGraphConv 重新實作，這也是許多後續研究論文採取的做法——用現代框架重現 Decagon 的實驗設計，同時獲得 GPU 加速、自動微分等現代深度學習框架的便利性。

與資料視覺化工具整合：訓練完成後的節點嵌入 (embedding) 可以用 scikit-learn 的 t-SNE 或 UMAP 降到 2 維後視覺化，觀察藥物是否依照藥理分類 (ATC code) 自然分群，是驗證模型學到「有意義的生物學結構」的常見診斷方式：

1from sklearn.manifold import TSNE
2import matplotlib.pyplot as plt
3
4drug_embeddings = sess.run(model.embeddings[1])  # 取出藥物節點的嵌入
5tsne_result = TSNE(n_components=2, random_state=42).fit_transform(drug_embeddings)
6
7plt.scatter(tsne_result[:, 0], tsne_result[:, 1], alpha=0.6)
8plt.title("藥物嵌入的 t-SNE 視覺化")
9plt.savefig("drug_embeddings_tsne.png")

5.6 效能優化建議

1. 善用 minibatch 而非全圖訓練：Decagon 已內建 EdgeMinibatchIterator，對真實規模（19,085 個蛋白質、645 個藥物、964 種副作用）而言，全圖一次性計算 loss 會超出記憶體，務必使用 minibatch。
2. 降低 hidden 維度做快速實驗迴圈：開發階段可先用 hidden1=32, hidden2=16 快速驗證程式碼邏輯是否正確，再升級到論文預設的 64/32 做正式訓練。
3. GPU 加速需注意記憶體：官方程式碼預設 os.environ['CUDA_VISIBLE_DEVICES'] = "" 強制用 CPU，原因是完整資料集的稀疏矩陣運算在當年（2018）的 GPU 記憶體上容易 OOM；若要用 GPU，建議先用小型子圖測試記憶體用量再逐步放大。
4. 善用稀疏矩陣運算：所有鄰接矩陣都以 scipy.sparse 格式儲存與傳遞（透過 preprocessing.sparse_to_tuple 轉換成 TensorFlow 的 sparse_placeholder 格式），避免把大型鄰接矩陣還原成稠密矩陣，這是處理數萬節點規模圖的必要作法。
5. 提高 PRINT_PROGRESS_EVERY：驗證集評估（get_accuracy_scores）需要對整個驗證集做一次前向傳播，計算量不小，官方建議「不要每個 iteration 都算」，訓練大型資料集時可考慮把 PRINT_PROGRESS_EVERY 從 150 調高到 500 甚至更高，節省訓練時間。

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

6.1 整合架構圖

flowchart TB
    subgraph SG_SRC["外部知識來源"]
        R1["mims-harvard/decagon
GitHub Repo"]
        R2["原始論文
Bioinformatics 2018"]
        R3["SNAP 資料集
polypharmacy CSV"]
    end

    subgraph SG_L1["L1-L3 知識擷取層"]
        L2["gh-save
repo → 教學 md"]
        L9["paper-search
找到原始論文全文"]
        L3["autofetch
持續追蹤後續引用研究"]
    end

    subgraph SG_L4["L4-L6 知識組織層"]
        L4["graphify
建立本 repo 知識圖譜索引"]
        L6["GitNexus
decagon 程式碼符號圖"]
        L5["NotebookLM
Decagon+後續論文知識庫"]
    end

    subgraph SG_L7["L7-L12 文件與輸出層"]
        L7["quarkdown
md→教學 HTML/PDF"]
        L11["kami
品牌化投影片"]
        L12["gh-tutorial-qd
本次任務執行入口"]
    end

    subgraph SG_L18["L18-L19 研究應用層"]
        L18["research-pipeline-v2
polypharmacy 風險研究管線"]
        L19["tu-plan-generator
藥物開發計畫參考"]
    end

    R1 --> L2
    R2 --> L9
    R1 --> L3
    L2 --> L4
    L2 --> L6
    L9 --> L5
    L4 --> L7
    L6 --> L7
    L7 --> L11
    L2 -.本次任務.-> L12
    L12 --> L7
    L5 --> L18
    L18 --> L19

    style L12 fill:#FDE68A,color:#0F172A
    style R1 fill:#BFDBFE,color:#0F172A

6.2 紅海分析 (Red Ocean Analysis)：功能重疊領域

Decagon 本身是一個演算法/模型 repo，而 AIKT 是知識管理與研究自動化系統，兩者的核心產出物本質不同——Decagon 產出「訓練好的圖神經網路模型與預測分數」，AIKT 產出「結構化的知識文件、教學材料、研究報告」。因此表面上「直接功能重疊」的範圍其實不大，但仍存在幾個需要誠實比較的交界地帶：

市場定位衝突判斷：幾乎沒有真正衝突。Decagon 是一個特定領域（polypharmacy GNN）的科學計算工具，AIKT 明確定位為「不做直接科學計算——它編排知識，不是演算法」。兩者是互補而非競爭關係。唯一容易混淆的是「knowledge graph」這個詞在兩邊語意不同——需要在對外溝通時明確區分「AIKT 的知識圖譜」（管理文件/程式碼關係）與「Decagon 建構的生醫知識圖」（管理藥物/蛋白質/副作用的科學關係），避免使用者誤以為 AIKT 能取代 Decagon 做真正的藥物交互作用預測計算。

紅海風險的具體檢核：即便判斷為「幾乎沒有真正衝突」，仍需誠實列出兩個潛在風險點，避免過度樂觀：

1. 使用者期望錨定錯誤的風險：如果 AIKT 產出的教學文件（如本文件）寫得過於詳盡、過於像一份「完整的科學分析報告」，使用者可能誤以為 AIKT 本身具備跑 GNN 模型、算出真實預測分數的能力。緩解方式：本文件已在多處明確標註「AIKT 不做直接科學計算」，並在第 7.4 節明確劃分「何時使用 Decagon 本身 vs 何時該用其他工具」的界線。
2. 資源排擠風險：若團隊把撰寫「深度教學文件」的精力，錯置成「應該花在改進 Decagon 模型本身」的精力，會產生本末倒置的資源分配問題。緩解方式：本節（6.4）明確規劃的三階段方案，把「AIKT 做知識工作」與「若要做模型改進研究則交給 research-pipeline-v2 管理的獨立研究週期」清楚分開,不混為一談。

6.3 藍海策略 (Blue Ocean Strategy)：AIKT 獨特切入機會

因為 Decagon 與 AIKT 定位互補而非競爭，藍海機會的核心思路是：AIKT 不去重做 Decagon 的科學計算，而是包裝、擴充、串聯 Decagon 產出的知識，讓它對生技/製藥研究人員產生超越原始 repo 的價值。

6.3.1 此 repo 未滿足的需求

1. 缺乏「如何在真實藥物安全審查場景下使用」的完整教學：官方 README 只說明程式碼結構，完全沒有從「藥師/臨床藥理學家的實際問題」出發的使用指引（本教學文件第 4-5 節正是填補這個空缺）。
2. 缺乏與現代生醫資料庫的自動連結：Decagon 的資料集是 2018 年靜態下載的 CSV，沒有任何機制去對接 DrugBank、ChEMBL、FDA FAERS（不良事件報告系統）等持續更新的即時資料源。
3. 缺乏與後續研究（TxGNN 等）的橫向串接：使用者若想理解「Decagon 之後這個研究方向如何演進」，必須自己去搜尋，官方 repo 沒有提供任何「後續閱讀地圖」。
4. 模型的可解釋性缺失：Decagon 只輸出一個風險分數，沒有告訴使用者「為什麼」模型認為兩種藥物有交互作用風險（例如是透過哪個共同蛋白質靶點）——這對臨床決策場景是致命缺陷，因為藥師需要「理由」才能信任並採用一個風險警示。

6.3.2 創造新價值的整合機會

• 建立「Decagon 知識脈絡地圖」：用 graphify 建立本 repo 的知識圖譜索引後，串接 paper-search 找出所有引用 Decagon 論文的後續研究，用 NotebookLM 建立一個「polypharmacy GNN 研究脈絡」的可查詢知識庫,讓使用者一次搞懂這整個研究方向 8 年來的演進。
• 打造「可解釋性補丁」教學層：搭配 GraphXAI（同一實驗室後續作品）的教學材料,產出「如何為 Decagon 的預測結果做事後解釋」的補充教學,填補原始 repo 的可解釋性缺口——這正好是 AIKT 能做、但 Decagon 本身不做的知識橋接工作。
• 持續追蹤層：用 autofetch 建立一個每日/每週 cron，追蹤 arXiv/PubMed 上引用 Decagon 或研究 polypharmacy side effect prediction 的新論文，自動生成 inbox 摘要——讓 Decagon 這個 2018 年的經典模型，透過 AIKT 的持續知識更新機制「保持新鮮」。

6.3.3 互補的 AIKT 層級

6.3.4 具體差異化策略

AIKT 不應該（也不可能）去「重新實作一個更好的 Decagon」——這違背 AIKT「編排知識，不做演算法」的核心定位。正確的差異化策略是三層次：

1. 教學層差異化：像本文件一樣，提供官方 README 完全沒有的「生活化比喻 + 具體數值範例 + 逐步拆解演算法」的教學深度，這是 Decagon 官方永遠不會做（也不需要做）的事,但正是研究人員/新手最需要的入口。
2. 知識連結層差異化：把 Decagon 放進更大的知識脈絡（前身研究、後續發展、同儕比較），單一 repo 的 README 天生做不到這件事，但這正是 AIKT 多層系統（paper-search + autofetch + graphify）的組合優勢。
3. 場景轉譯層差異化：把「訓練一個 GNN」轉譯成「藥師可以怎麼用這個工具支援臨床決策」的場景化說明（見第 4.5、5.4 節），這是純技術 repo 與應用導向知識管理系統之間最大的價值落差。

6.4 推薦整合方案

Phase 1（已完成，即本任務）： 用 gh-tutorial-qd 產出這份完整教學文件，涵蓋架構、安裝、使用範例、AIKT 整合分析。輸出至 projects/260710 mims-harvard/tutorials/09-decagon.md。

Phase 2（建議下一步）：

1. 執行 graphify init 對本篇教學文件與其他 mims-harvard 系列教學建立知識圖譜索引，讓使用者可以查詢「polypharmacy 相關的所有教學文件」。
2. 用 paper-search 搜尋 Decagon 論文的後續引用文獻（特別是 2020 年後的圖神經網路可解釋性、hyperbolic embedding 應用於藥物交互作用的論文），補充成第二份延伸教學。
3. 若有具體研究需求（例如公司內部想評估是否採用 GNN 做藥物安全性篩查），用 research-pipeline-v2 啟動一個多輪研究管線，系統性比較 Decagon 與其後續變體（TxGNN 等）在特定應用場景下的適用性。

Phase 3（長期，視需求觸發）： 建立 autofetch 每週 cron，持續追蹤 polypharmacy side effect prediction 領域的新論文與新 repo，自動更新 inbox，確保這份知識資產不會像原始 GitHub repo 一樣「停在 2018 年」。

6.5 具體場景示範：一位生資分析師的一週工作流

為了讓上述抽象的「整合方案」更具體，以下模擬一位生資分析師（bioinformatics analyst; 生物資訊分析師）在公司內部想評估「是否該用 GNN 做藥物安全性篩查」時，如何實際串接 AIKT 各層與 Decagon：

flowchart LR
    D1["Day 1
gh-save 抓 decagon repo"] --> D2["Day 1
gh-tutorial-qd
產出本篇教學"]
    D2 --> D3["Day 2
paper-search 找
後續 8 年引用文獻"]
    D3 --> D4["Day 2-3
NotebookLM 建立
polypharmacy 知識庫"]
    D4 --> D5["Day 3-4
graphify 建索引
串接公司內部既有研究"]
    D5 --> D6["Day 4
向主管簡報
kami 產出品牌化投影片"]
    D6 --> D7{"主管決策：
是否投入實作？"}
    D7 -->|是| D8["research-pipeline-v2
啟動多輪實驗管線"]
    D7 -->|否，先觀察| D9["autofetch 週期追蹤
領域新進展"]

    style D2 fill:#FDE68A,color:#0F172A
    style D7 fill:#BFDBFE,color:#0F172A

這個流程示範了 AIKT 真正的價值主張：從「知道有這個 repo 存在」到「能向主管提出有依據的投資建議」，中間有大量的知識工作（讀論文、理解架構、串接公司既有研究、產出簡報材料）——這些工作如果沒有系統化的知識管理工具支援，往往要花上數週且容易遺漏脈絡（例如忘了查後續研究、或簡報時講不清楚模型限制）。AIKT 的角色，就是把這整條知識工作流程從「零散、依賴個人記憶」變成「系統化、可重複、可交接給下一位分析師」的標準流程。

6.6 整合方案的風險與投資回報評估

總結判斷：三階段方案的風險都屬於「知識管理層級」的低風險（最壞情況只是花了時間卻沒找到有價值的新資訊），完全不涉及需要嚴格科學驗證的模型訓練或臨床決策風險——這正符合 AIKT「編排知識、不做科學計算」的安全定位。

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

7.1 效能數據（依原始論文報告）

• 在真實 polypharmacy 資料集（645 藥物、19,085 蛋白質、964 種副作用類型）上，Decagon 對高頻副作用類型（已知案例數較多者）的平均 ROC-AUC 可達 0.87 以上，顯著優於不使用蛋白質網路資訊、只用藥物本身特徵的基準方法（論文報告較基準方法提升約 12-15 個百分點的 AUROC，具體數值依副作用類型不同而有差異）。
• 模型對「低頻副作用」（已知案例數少於 500 的類型）效果明顯下降，這是 GNN link prediction 在 class imbalance 情境下的常見限制，也是 DEDICOM 解碼器透過「共享全域矩陣」試圖緩解、但無法完全解決的問題。
• 訓練時間：依原始論文所述，在完整資料集規模上，於單張 GPU（2018 年當時硬體）訓練需數小時級別；教學用合成範例（500 基因+400 藥物）在現代筆電 CPU 上可於數分鐘內完成 50 epoch。

7.2 已知限制

1. 框架老舊：基於 TensorFlow 1.x 靜態圖 API，2026 年的現代開發環境需要額外相容性處理（見第 3 節），且官方已無主動維護（最後一次程式碼更新距今已數年）。
2. 無法即時處理連續更新的資料：模型訓練後，若有新藥物或新副作用記錄，必須重新訓練整個模型（沒有 incremental learning 或 inductive 能力去泛化到訓練時沒見過的全新節點）。
3. 可解釋性不足：只輸出一個機率分數,沒有內建機制解釋「為什麼」預測某個藥物配對有風險（例如是透過哪個蛋白質路徑），這對需要向醫師/藥師解釋預測依據的臨床應用場景是明顯短板。
4. 資料偏差問題：訓練資料來自「已知」的副作用報告，本質上帶有「報告偏差」（rare but severe 的副作用可能因為臨床試驗規模不足而未被記錄），模型無法預測「訓練資料中完全沒出現過模式」的全新副作用類型。
5. 雙節點類型的侵入性假設：目前架構假設固定的節點類型集合（基因、藥物），若要擴充第三種節點類型（如疾病、副作用本身作為節點）需要對程式碼做一定程度的改寫，不是純粹的 config 調整。

7.3 與同類工具比較

7.4 何時使用 vs 何時不使用

適合使用 Decagon（或其設計思路）的情境：

• 需要在「已知蛋白質網路 + 藥物靶點資訊完整」的情境下，預測大量（數百種以上）不同類型的藥物交互作用風險。
• 教學/研究用途，理解異質圖 GNN 在生醫問題上的經典應用範式。
• 作為 baseline，與更新的方法（TxGNN、hyperbolic embedding 方法等）做效能比較。

不適合使用 Decagon 的情境：

• 若只需要查詢「已知、已記錄」的藥物交互作用（例如臨床例行工作中查詢兩種藥物是否已知有交互作用），應直接使用 DrugBank、Micromedex、Lexicomp 等經過臨床驗證的專業資料庫，不需要動用機器學習模型的預測結果（模型預測有不確定性，不能取代已驗證的臨床知識庫）。
• 若需要處理訓練時完全沒見過的全新藥物（inductive 場景），應考慮 TxGNN 或其他具備 zero-shot/few-shot 能力的後續方法。
• 若需要生產環境級別的即時 API 服務，Decagon 原始程式碼（研究用 script，非服務化架構）需要大量額外工程才能達到生產標準，不建議直接部署原始 repo。

7.5 方法定位象限圖（Mermaid Quadrant Chart）

為了更直觀地理解 Decagon 在整個方法譜系中的相對位置，以下用「可解釋性」與「規模擴展性（能處理的關係類型數量）」兩個維度做定位：

quadrantChart
    title "藥物交互作用預測方法定位"
    x-axis "低規模擴展性" --> "高規模擴展性"
    y-axis "低可解釋性" --> "高可解釋性"
    quadrant-1 "理想區：兼具規模與解釋力"
    quadrant-2 "解釋力優先"
    quadrant-3 "兩者皆弱"
    quadrant-4 "規模優先（Decagon 所在）"
    "Decagon": [0.8, 0.25]
    "DrugBank 規則庫": [0.3, 0.85]
    "TxGNN": [0.75, 0.4]
    "GraphXAI 補丁後的 Decagon": [0.75, 0.65]
    "Deac 等 co-attention 模型": [0.45, 0.5]

如何解讀這張圖：Decagon 落在右下角（規模擴展性高、可解釋性低）——它能同時處理近千種副作用類型，這是它最大的優勢，但單純看預測分數完全不知道「為什麼」。而傳統規則庫（DrugBank 等）落在左上角——每一條交互作用記錄背後都有明確的臨床證據，可解釋性極高，但完全無法「預測」訓練資料中沒有的新組合，規模擴展性受限於人工整理速度。理想的長期發展方向，是把 Decagon 這類方法往右上角推進——這正是本文件第 6.3 節建議的「可解釋性補丁」整合方向所要達成的目標。

7.6 常見問題 (FAQ)

Q1：Decagon 可以直接用在中文病歷或台灣的藥物資料庫上嗎？

不能直接套用。Decagon 的核心模型架構（GCN + DEDICOM）與語言無關，但它依賴的輸入資料（蛋白質-蛋白質交互作用、藥物-靶點關係、已知副作用記錄）必須先整理成標準化的圖結構。若要套用在台灣的藥物資料上，需要先把本地藥物資料庫（如衛福部藥品許可證資料、健保資料庫的用藥記錄）對應到國際通用的藥物識別碼（如 STITCH ID、DrugBank ID），才能重複利用 Decagon 依賴的 PPI 與 drug-target 公開資料庫。

Q2：合成範例（main.py 內建的隨機圖）跑出來的 AUROC 有意義嗎？

沒有科學意義。合成資料是用 networkx.planted_partition_graph 隨機生成的，不具備任何真實生物學結構，AUROC 數值高低只反映「模型程式碼邏輯是否正確」，不代表模型的預測能力。若要得到有意義的效能數據，必須下載官方真實資料集（見第 3.5 節）。

Q3：為什麼 Decagon 對基因/蛋白質節點使用 identity matrix（單位矩陣）作為特徵，而不是用真實的生物特徵（如基因表現量、蛋白質結構特徵）？

這是一種常見的「featureless」設計選擇，讓模型完全依賴圖結構（拓樸資訊）學習表徵，而不依賴額外的特徵工程。這樣做的好處是簡化實驗、避免特徵品質不一致造成的干擾；壞處是放棄了可能有價值的先驗生物知識（例如已知的蛋白質功能分類、基因表現模式）。若要改良，可以把 identity matrix 換成真實特徵矩陣（如 Gene Ontology 註解的 one-hot 編碼、ESM 蛋白質語言模型的嵌入向量），這是常見的後續改進方向。

Q4：DEDICOM 解碼器的「全域交互矩陣 R」在訓練過程中會不會被某幾種樣本量特大的副作用類型主導，反而讓稀有副作用學不好？

這是一個合理的擔憂，也是文獻中持續被討論的問題。DEDICOM 的設計理論上讓稀有類型可以「借用」共享矩陣 R 學到的通用模式，但如果訓練時 minibatch 抽樣沒有針對稀有副作用類型做加權處理，樣本量大的副作用類型仍會在梯度更新中占主導地位。實務上建議搭配分層抽樣（stratified sampling）或對稀有類型的正樣本給予更高的損失權重，來緩解這個問題。

Q5：可以用 GPU 加速訓練嗎？官方程式碼為什麼預設關閉 GPU？

可以用 GPU，只需把 main.py 開頭的 os.environ['CUDA_VISIBLE_DEVICES'] = "" 改回程式碼中已註解的 GPU 設定即可。官方預設關閉 GPU 的原因，如程式碼註解所述，是「記憶體限制」——完整規模資料集的稀疏鄰接矩陣運算，在 2018 年當時常見的 GPU 記憶體（如 8-12GB）上容易發生 OOM。若使用現代 GPU（24GB+ 記憶體），啟用 GPU 通常可以順利運作並顯著加速訓練。

Q6：Decagon 的預測結果能不能直接寫進臨床用藥警示系統？

不建議直接使用。模型輸出的是一個統計上的風險分數，不是經過臨床驗證的診斷結論。合理的使用方式是把 Decagon（或其後續改良方法）的高風險預測，當作「值得優先人工複核」的候選清單，而不是自動觸發警示或替代藥師/醫師的臨床判斷。任何要導入實際醫療決策流程的模型，都必須經過嚴謹的前瞻性驗證與法規審核。

Q7：Decagon 支援的最大圖規模是多少？如果我的資料比論文原本的規模更大該怎麼辦？

官方程式碼本身沒有硬編碼的規模上限，理論上規模受限於記憶體（稀疏矩陣運算）與訓練時間。若資料規模明顯超過論文原始規模（例如節點數成長 10 倍以上），建議先評估是否需要：(1) 改用分散式訓練框架重新實作核心邏輯；(2) 對圖做子圖抽樣（subgraph sampling），只在每個 minibatch 抽取局部鄰域訓練（類似 GraphSAGE 的做法），而不是像 Decagon 原生設計那樣仰賴完整鄰接矩陣;(3) 評估是否有必要,或是否某些節點/邊類型可以先做預篩選降維，減少不必要的計算量。

Q8：我該從哪個檔案開始讀 Decagon 的原始碼，才能最快理解整個系統？

建議依此順序閱讀：(1) 先讀 main.py 建立整體流程的直覺（資料怎麼準備、模型怎麼建立、怎麼訓練）；(2) 再讀 decagon/deep/model.py 理解 encoder 的 forward pass 邏輯（對照本文件第 2.4 節的具體範例）；(3) 接著讀 decagon/deep/layers.py 理解四種解碼器的具體數學實作；(4) 最後讀 decagon/deep/minibatch.py 與 optimizer.py 理解訓練時的資料抽樣與損失計算細節。這個順序符合「先建立整體心智模型，再深入細節」的一般程式碼閱讀原則，避免一開始就陷入單一檔案的實作細節而失去對全局架構的掌握。

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

8.1 關鍵要點回顧

1. Decagon 把「藥物組合副作用預測」重新定式化為「異質多關係圖上的 link prediction」問題，是這個問題設定的開創性工作。
2. 核心技術創新是兩層圖卷積 encoder（跨關係類型加總訊息）搭配DEDICOM decoder（共享全域交互矩陣 + 各關係類型專屬微調），讓模型能有效處理上千種副作用類型、且對稀有副作用類型仍具備一定泛化能力。
3. 程式碼架構具備良好的可擴展性——用字典 (edge_types, decoders) 描述異質結構，理論上可以擴充到更多節點/邊類型，但需一定程度的程式碼修改。
4. 環境相容性是實務使用上最大的第一道門檻，需依第 3 節的方法（Docker 優先）處理 TensorFlow 1.x 的過時依賴問題。
5. 在 AIKT 生態系中，Decagon 與 AIKT 是互補而非競爭關係——AIKT 的價值在於「包裝、連結、場景轉譯」Decagon 這類科學計算 repo 的知識，而非重做其演算法。

8.2 最佳使用場景

• 教學情境：作為理解「異質圖 GNN」「多關係 link prediction」概念的入門經典案例，特別適合搭配本教學文件的具體數值範例學習。
• 研究基準比較：作為新方法（如 TxGNN 之後的更新方法）的效能對照基準,理解特定改進（可解釋性、inductive learning、zero-shot 泛化）相對於 2018 年基準方法的具體提升幅度。
• 概念驗證原型：若團隊想快速驗證「異質圖 + 蛋白質網路資訊是否對藥物安全預測有幫助」這個假設，Decagon 提供了一個現成、已驗證有效的架構起點,不需要從零設計異質 GNN。

8.3 未來發展方向

1. 可解釋性整合：搭配 GraphXAI 等事後解釋工具，補上「為什麼模型認為這兩種藥物有風險」的解釋層，是讓 Decagon 類方法真正進入臨床決策支援系統的必要條件。
2. 現代化框架重寫：用 PyTorch Geometric 或 DGL 重新實作核心架構，脫離 TensorFlow 1.x 的維護困境，同時獲得更好的 GPU 支援與生態系整合。
3. 持續學習能力：加入 inductive/zero-shot 機制（參考 TxGNN 的做法），讓模型能處理新藥物上市後的即時風險評估，而不需要每次都重新訓練整個模型。
4. 與即時資料源整合：對接 FDA FAERS、EudraVigilance 等持續更新的藥物不良事件報告系統，讓模型的知識庫不再停留在單次靜態下載的資料集,而是能隨真實世界證據持續更新。
5. 在 AIKT 內的長期定位：作為「生醫圖神經網路知識脈絡」的錨點案例，透過持續的 autofetch 追蹤與 paper-search 檢索，讓這份教學文件本身也隨著領域演進持續補充更新，而不是一次性產出後就過時。

8.4 給不同角色讀者的行動建議

• 若你是初學圖神經網路的研究生/新人分析師：從第 2.4 節的具體數值範例開始讀，動手跑通第 4 節的合成資料範例，再逐步嘗試第 5.3 節的真實資料載入程式碼。不需要一開始就理解所有數學細節，先建立「輸入是什麼、輸出是什麼、中間發生什麼」的直覺。
• 若你是評估是否導入 GNN 方法的技術主管：重點閱讀第 7 節（效能、限制與替代方案）與第 6 節（AIKT 整合分析），特別是第 7.4 節「何時使用 vs 何時不使用」的判斷準則，避免在不合適的場景（如需要生產級即時 API、或需要 inductive 泛化）誤用 Decagon 這類 2018 年的靜態圖模型。
• 若你是負責 AIKT 系統維護與擴充的工程角色：重點閱讀第 6.4-6.6 節的具體整合方案與風險評估，這是可以直接轉化為後續 Layer 任務（graphify、paper-search、autofetch 串接）的可執行計畫。

術語對照表 (Glossary)

為方便不同背景的讀者快速查閱，以下整理本文件出現的主要雙語技術名詞：

附錄：延伸資源連結

• 官方 repo：https://github.com/mims-harvard/decagon
• 官方資料集下載頁：http://snap.stanford.edu/decagon
• 論文全文（Bioinformatics）：https://doi.org/10.1093/bioinformatics/bty294
• 作者投影片（ISMB 2018）：http://stanford.edu/~marinka/slides/decagon-ismb18.pdf
• 同一實驗室後續作品 TxGNN：https://github.com/mims-harvard/TxGNN

文件維護紀錄

後續更新建議：依第 6.4 節 Phase 3 規劃，若 autofetch 追蹤到 polypharmacy side effect prediction 領域有重大新進展（如新的 SOTA 方法、Decagon 官方 repo 有結構性更新），應回頭更新本文件對應章節（特別是第 1.8 節研究脈絡年表與第 7.3 節同類工具比較表），並在此紀錄新增版本項目，避免文件內容與領域現況產生落差。