mims-harvard/TDC 完整教學：Therapeutics Data Commons (TDC; 治療科學資料共享平台)

Repository: mims-harvard/TDC Stars: 1263 · Forks: 219 · Language: Jupyter Notebook · License: MIT 官網：tdcommons.ai · PyPI: PyTDC

目錄

1. 專案概述
2. 核心架構
3. 安裝與設定
4. 基本使用
5. 進階功能與應用場景
6. AIKT 整合分析與策略
7. 效能、限制與替代方案
8. 總結與建議

1. 專案概述 (Project Overview)

1.1 一句話說明

Therapeutics Data Commons (TDC; 治療科學資料共享平台) 是哈佛醫學院 Marinka Zitnik 實驗室（mims-harvard）主導的開源專案，把「藥物發現與開發」這個極度分散、格式混亂的資料世界，整理成一套可直接餵給機器學習模型的標準化資料集、評測基準 (benchmark) 與排行榜 (leaderboard) 系統。它的 PyPI 套件叫 PyTDC，安裝後只要三行程式碼就能拿到一份乾淨、已切分好訓練/驗證/測試集的生醫資料。

1.2 用淺顯比喻理解 TDC 在解決什麼問題

想像你是一位機器學習研究者，想訓練一個模型來預測「這個小分子藥物會不會被人體腸道吸收 (human intestinal absorption; HIA)」。在 TDC 出現之前，你的工作流程大概是這樣：

1. 上網搜尋哪個實驗室發表過 HIA 相關的實驗資料
2. 下載別人論文的 supplementary Excel 檔（欄位命名各不相同、單位不一致、甚至有拼寫錯誤）
3. 自己寫清洗腳本，把 SMILES（分子的文字表示法）字串標準化
4. 自己決定怎麼切訓練/測試集（隨機切？還是要避免相似分子洩漏到測試集？）
5. 自己找一個「業界公認」的評估指標，但往往不同論文用不同指標，無法互相比較
6. 訓練完模型後，沒有客觀的排行榜可以知道自己的模型是不是真的比別人好

這個流程就像每個廚師都要自己種菜、自己磨刀、自己發明度量單位，才能開始做一道菜——沒有標準化的「食材供應鏈」。TDC 做的事情，就是建立這條食材供應鏈：它把 22+ 個治療領域、800+ 個資料集整理成統一格式，附上經過同行驗證的切分方法（例如按分子骨架切分的 scaffold split，避免模型「背答案」）與評估指標，讓研究者可以把 100% 的精力放在「設計更好的模型」，而不是「跟資料格式打架」。

用另一個比喻：TDC 就像是生醫 AI 領域的 ImageNet。ImageNet 讓電腦視覺研究者不用再各自標註圖片，只要載入 ImageNet 就能立刻開始比較演算法優劣；TDC 讓治療科學（drug discovery; 藥物發現）研究者不用再各自整理資料，只要 pip install PyTDC 就能立刻開始比較模型優劣。

1.3 為什麼「治療科學」特別需要這種基礎設施

藥物開發是一個橫跨多個尺度、多種資料型態的問題：

• 分子尺度：小分子藥物的結構（SMILES）、性質預測（ADMET：吸收 Absorption、分布 Distribution、代謝 Metabolism、排除 Excretion、毒性 Toxicity）
• 蛋白質尺度：藥物-靶點交互作用 (drug-target interaction; DTI)、蛋白質-蛋白質交互作用 (protein-protein interaction; PPI)
• 細胞尺度：藥物反應 (drug response)、CRISPR 篩選結果、單細胞轉錄體 (single-cell transcriptomics)
• 患者/臨床尺度：臨床試驗結果預測 (trial outcome prediction)、藥物組合治療 (drug combination therapy)
• 生成任務：從零設計新分子、逆合成路徑規劃 (retrosynthesis)、基於結構的藥物設計 (structure-based drug design; SBDD)

這種跨尺度、跨模態的特性，正是 TDC 命名中 “Multimodal Foundation for Therapeutic Science” 的來源——它不只是一個資料集倉庫，而是嘗試建立一套跨模態的基礎設施，讓不同尺度的資料可以用一致的介面存取、評估與比較。

1.4 學術地位與發表紀錄

TDC 不是一個「隨手做做」的工具，而是有紮實學術背書的基礎設施型專案：

作者名單中的 Marinka Zitnik 是哈佛醫學院生物醫學資訊系 (Biomedical Informatics) 教授，長期研究圖神經網路 (graph neural network; GNN) 在生醫領域的應用；Jure Leskovec（史丹佛）是圖機器學習領域的權威學者之一。這代表 TDC 的資料切分方法、評估框架並非隨意設計，而是建立在圖機器學習與藥物化學交叉領域多年研究基礎上。

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

mims-harvard 這個 GitHub organization 底下有多個彼此關聯的專案，共同構成一套「治療科學 AI 基礎設施」：

• TDC（本專案）：資料集、任務定義、評估框架、排行榜——生態系的「資料與評測底層」
• PrimeKG：一個精準醫學知識圖譜 (precision medicine knowledge graph)，整合了疾病、藥物、蛋白質、表現型等 10 種節點類型——TDC 透過 tdc.resource.PrimeKG 直接把它接進來，作為知識圖譜任務的資料來源
• PINNACLE：情境感知的蛋白質交互作用網路嵌入模型 (context-aware protein interaction network embeddings)——同樣被整合進 tdc.resource
• 其他如 scGPT 整合、Geneformer tokenizer 等單細胞基礎模型 (single-cell foundation model) 相關工具

換句話說，TDC 是這整個生態系的中央樞紐：它不自己發明新演算法，而是把實驗室內外的資料資源、模型資源、知識圖譜資源都串接到一套統一的 Python API 之下，讓下游研究者（包括實驗室自己人）都能用同一套介面存取。

1.6 TDC 在生醫 AI 版圖中的位置（架構圖）

flowchart TB
    subgraph SG_UPSTREAM["上游：原始資料來源"]
        A1["PubChem / ChEMBL
化合物資料庫"]
        A2["DrugBank / BindingDB
藥物與結合親和力"]
        A3["UniProt / PDB
蛋白質結構與序列"]
        A4["Harvard Dataverse
學術資料托管"]
        A5["各實驗室發表論文
Supplementary Data"]
    end

    subgraph SG_TDC["中游：TDC 標準化層"]
        B1["tdc.single_pred
單實體預測任務"]
        B2["tdc.multi_pred
多實體預測任務"]
        B3["tdc.generation
分子生成任務"]
        B4["tdc.resource
知識圖譜 / 單細胞資源"]
        B5["BenchmarkGroup
排行榜系統"]
    end

    subgraph SG_DOWNSTREAM["下游：應用場景"]
        C1["學術研究
方法論驗證"]
        C2["製藥公司
虛擬篩選 pipeline"]
        C3["AI 模型開發者
基礎模型訓練/微調"]
        C4["監管科學
ADMET 預測輔助決策"]
    end

    A1 --> B1
    A2 --> B2
    A3 --> B2
    A4 --> B1
    A4 --> B2
    A5 --> B3
    B1 --> B5
    B2 --> B5
    B3 --> B5
    B4 --> B2
    B5 --> C1
    B5 --> C3
    B1 --> C4
    B2 --> C2
    B3 --> C2

    style SG_TDC fill:#1E3A5F,color:#FFFFFF
    style SG_UPSTREAM fill:#E0E7FF,color:#0F172A
    style SG_DOWNSTREAM fill:#D1FAE5,color:#0F172A

從這張圖可以看出 TDC 扮演的角色類似「資料轉接器 + 品質保證層」：它把上游雜亂無章的原始資料，轉換成下游可以直接使用的標準格式，同時附上品質保證（一致的切分方法、評估指標）。

1.7 與相鄰工具的定位差異（先建立心理地圖）

在深入細節之前，先用一句話區分 TDC 與幾個常被搞混的相鄰工具：

• TDC vs RDKit：RDKit 是分子的「計算引擎」（算指紋、算相似度、畫結構圖），TDC 是「資料與任務層」，兩者常常一起用——TDC 內部的 chem_utils 模組事實上也依賴 RDKit 做分子處理
• TDC vs DeepPurpose：DeepPurpose 是模型庫（提供現成的 DTI 預測模型架構），TDC 是資料與評測層；README 中的 tutorial 104 展示了兩者結合，用 TDC 的資料訓練 DeepPurpose 的模型
• TDC vs MoleculeNet：MoleculeNet 是較早期（2017）的分子性質預測 benchmark，範圍侷限在小分子；TDC 涵蓋範圍更廣（小分子、抗體、蛋白質、細胞、臨床試驗），且持續維護到 2024 年的 TDC-2 多模態擴展
• TDC vs Hugging Face Datasets：Hugging Face Datasets 是通用資料集托管平台（NLP 為主），TDC 是治療科學領域垂直整合的資料+任務+評測框架，兩者互補而非競爭——TDC 的 model_server 模組甚至反過來整合 Hugging Face 上的模型

1.8 核心價值主張總結

README 中明確列出的四個獨特優勢，值得逐一展開理解：

1. 廣泛的治療領域覆蓋：從靶點發現 (target discovery)、活性篩選 (activity screening)、療效與安全性 (efficacy and safety) 到量產製造 (manufacturing)，涵蓋小分子、抗體、疫苗等多種生醫產品型態
2. 即用型資料集 (ready-to-use datasets)：任何 TDC 資料集都能用三行程式碼取得，且核心依賴極輕量（numpy、pandas、tqdm、scikit-learn、fuzzywuzzy、seaborn）
3. 豐富的資料函式：資料評估器 (data evaluator)、有意義的資料切分方法 (meaningful data split)、資料處理器、分子生成 oracle
4. 排行榜系統：提供公平比較模型的 benchmark，支援系統性的模型開發與評估流程

這四點合起來，構成了 TDC 作為「治療科學 AI 基準測試與評估 (Benchmarks & Evaluation)」類別代表性專案的核心定位——它不追求成為最強的演算法庫，而是追求成為最值得信賴的評測裁判。

1.9 採用度與治理模式

TDC 的社群治理模式值得特別記錄，因為這解釋了它為何能維持長期活躍度而不像許多學術專案在論文發表後就停止維護：

• 開放科學治理：README 明確聲明「TDC is a community-driven and open-science initiative」，並提供正式的 CONTRIBUTE.md 貢獻指南、Slack 工作空間、以及 TDC 專屬的郵件群組 (groups.io/g/tdc)——這種多管道社群基礎設施在學術工具中並不常見
• 持續整合測試：repo 內同時維護 CircleCI 與 GitHub Actions 兩套 CI 管線（conda-tests.yml），確保新增資料集或功能不會破壞既有 API，這對一個資料集數量持續增長的專案而言是重要的品質保障機制
• 定期使用者社群聚會 (User Group Meetup)：README 中列出多次 TDC User Group Meetup 的錄影與投影片，顯示這不只是「發表論文後放著」的專案，而是有持續的使用者回饋循環
• 多篇高影響力論文的持續背書：從 2020 年的研討會投影片、2021 年 NeurIPS 正式論文，到 2022 年 Nature Chemical Biology、2024 年 NeurIPS AIDrugX，形成一條清晰的學術影響力累積軌跡

下表整理 TDC 的關鍵發展里程碑時間軸，幫助快速掌握其成熟度演進：

這條時間軸也回應了本文開頭的比喻——TDC 走的路徑跟 ImageNet 在電腦視覺領域走過的路徑高度相似：先是論文發表確立方法論權威，接著發展成社群共同維護的基礎設施，最終演變為整個領域預設的評測標準。

2. 核心架構 (Core Architecture)

2.1 三層層級結構：TDC 設計哲學的核心

TDC 最重要的設計決策，是把整個「機器學習 for 治療科學」的問題空間，拆解成一個三層階層結構 (three-tiered hierarchical structure)——這是 README 中特別強調「首次系統性嘗試」的部分：

• 第一層：問題 (Problem) —— 根據輸入輸出型態，分成三大類：
  • single_pred：單實體預測（輸入一個生醫實體，預測其性質）
  • multi_pred：多實體預測（輸入多個生醫實體的組合，預測交互結果）
  • generation：生成任務（輸出全新的生醫實體）
• 第二層：學習任務 (Learning Task) —— 每個問題底下有多個具體任務，例如 single_pred 底下有 ADME、Toxicity (Tox)、High-Throughput Screening (HTS) 等
• 第三層：資料集 (Dataset) —— 每個任務底下有多個具體資料集，例如 ADME 任務底下有 HIA_Hou、Caco2_Wang、Pgp_Broccatelli 等

這種設計的巧妙之處在於：API 的呼叫方式在所有層級上都保持一致。不管你要拿哪個問題、哪個任務、哪個資料集，語法永遠是「匯入對應的問題類別 → 傳入任務名稱 → 呼叫方法」。這讓新增資料集或任務時，完全不需要更動既有的 API 介面——這正是「消除特殊情況」的良好架構範例。

flowchart LR
    subgraph L1["第一層：Problem（問題類型）"]
        P1["single_pred
單實體預測"]
        P2["multi_pred
多實體預測"]
        P3["generation
生成任務"]
    end

    subgraph L2["第二層：Learning Task（學習任務）"]
        T1["ADME / Tox / HTS
QM / Epitope / Yields"]
        T2["DTI / DDI / PPI / GDA
DrugCombo / TrialOutcome"]
        T3["MolGen / RetroSyn
Reaction / SBDD"]
    end

    subgraph L3["第三層：Dataset（具體資料集）"]
        D1["HIA_Hou, Caco2_Wang,
Pgp_Broccatelli ..."]
        D2["BindingDB_Kd, DrugBank,
HuRI ..."]
        D3["ZINC, ChEMBL,
USPTO_50k ..."]
    end

    P1 --> T1 --> D1
    P2 --> T2 --> D2
    P3 --> T3 --> D3

    style L1 fill:#1E3A5F,color:#FFFFFF
    style L2 fill:#334155,color:#FFFFFF
    style L3 fill:#475569,color:#FFFFFF

2.2 從程式碼結構看架構落地方式

透過瀏覽 repo 的 tdc/ 目錄，可以確認三層架構在程式碼層級的具體實現：

 1tdc/
 2├── single_pred/          # 第一層：single_pred 問題
 3│   ├── adme.py           # ADME 任務
 4│   ├── tox.py             # 毒性 (Toxicity) 任務
 5│   ├── hts.py             # 高通量篩選任務
 6│   ├── qm.py               # 量子力學性質任務
 7│   ├── epitope.py          # 抗原表位任務
 8│   ├── paratope.py         # 抗體互補決定區任務
 9│   ├── develop.py           # 抗體可開發性任務
10│   ├── crispr_outcome.py    # CRISPR 篩選結果任務
11│   ├── yields.py             # 化學反應產率任務
12│   └── single_pred_dataset.py  # 共用基底類別
13├── multi_pred/            # 第一層：multi_pred 問題
14│   ├── dti.py              # 藥物-靶點交互作用
15│   ├── ddi.py              # 藥物-藥物交互作用
16│   ├── ppi.py               # 蛋白質-蛋白質交互作用
17│   ├── gda.py                # 基因-疾病關聯
18│   ├── drugres.py             # 藥物反應
19│   ├── drugsyn.py              # 藥物協同作用
20│   ├── mti.py                   # miRNA-靶點交互作用
21│   ├── peptidemhc.py             # 胜肽-MHC 結合
22│   ├── tcr_epi.py                 # TCR-表位結合
23│   ├── trialoutcome.py             # 臨床試驗結果
24│   ├── catalyst.py                  # 催化反應
25│   ├── proteinpeptide.py             # 蛋白質-胜肽交互作用
26│   ├── anndata_dataset.py             # 單細胞 AnnData 格式資料集
27│   └── multi_pred_dataset.py           # 共用基底類別
28├── generation/             # 第一層：generation 問題
29│   ├── molgen.py            # 分子生成
30│   ├── retrosyn.py            # 逆合成路徑規劃
31│   ├── reaction.py              # 反應預測
32│   ├── sbdd.py                    # 基於結構的藥物設計
33│   └── ligandmolgen.py              # 配體導向分子生成
34├── benchmark_group/         # 排行榜系統
35│   ├── admet_group.py         # ADMET 綜合基準
36│   ├── dti_dg_group.py          # DTI 領域泛化基準
37│   ├── drugcombo_group.py         # 藥物組合基準
38│   ├── docking_group.py            # 分子對接基準
39│   ├── counterfactual_group.py       # 反事實推論基準
40│   ├── geneperturb_group.py           # 基因擾動基準
41│   ├── scdti_group.py                  # 單細胞 DTI 基準
42│   ├── protein_peptide_group.py         # 蛋白質-胜肽基準
43│   └── tcrepitope_group.py                # TCR 表位基準
44├── chem_utils/               # 化學工具層
45│   ├── evaluator.py             # 分子性質評估器
46│   ├── featurize/                 # SMILES 特徵化（molconvert 等）
47│   └── oracle/                      # 生成任務用的 oracle（docking、filter）
48├── resource/                  # TDC-2 知識資源整合層
49│   ├── primekg.py               # PrimeKG 精準醫學知識圖譜
50│   ├── pinnacle.py                 # PINNACLE 蛋白質網路嵌入
51│   ├── cellxgene_census.py          # 單細胞圖譜 (Cell x Gene Census)
52│   └── dataloader.py                  # 通用資料載入介面
53├── model_server/               # TDC-2 模型中心整合層
54│   ├── tdc_hf.py                  # Hugging Face 模型整合
55│   ├── models/scgpt.py              # scGPT 單細胞基礎模型
56│   ├── models/scvi.py                 # scVI 單細胞變分推論模型
57│   └── tokenizers/geneformer.py         # Geneformer tokenizer
58├── evaluator.py                  # 通用評估指標（ROC-AUC、MAE、Spearman 等）
59├── oracles.py                      # 分子生成 oracle 統一介面
60├── base_dataset.py                   # 所有資料集的共用基底類別
61└── metadata.py                          # 資料集/任務的中央註冊表

這個目錄結構清楚呈現了兩件事：

1. 三層架構在程式碼上是「問題類別 = 目錄，任務 = 檔案，資料集 = 檔案內的字串參數」——這種設計讓新增一個資料集的成本極低（只要在對應任務檔案裡登記名稱與下載連結），而新增一個全新任務只需要新增一個檔案並繼承共用基底類別
2. TDC-2 的擴展是「加法式」而非「重構式」——resource/ 與 model_server/ 是後來為了支援單細胞、知識圖譜、基礎模型而新增的模組，沒有破壞原本 single_pred / multi_pred / generation 的既有介面，這是良好的向後相容性設計範例

2.3 資料流向：從使用者呼叫到取得乾淨資料的完整路徑

sequenceDiagram
    participant U as 使用者程式碼
    participant API as tdc.single_pred.ADME
    participant Meta as tdc.metadata
中央註冊表
    participant Cache as 本地快取
data/
    participant Server as Harvard Dataverse
資料伺服器
    participant Split as get_split()
切分邏輯
    participant Eval as Evaluator
評估器

    U->>API: ADME(name="HIA_Hou")
    API->>Meta: 查詢 HIA_Hou 的下載位址與欄位定義
    Meta-->>API: 回傳 metadata（URL、label 欄位、任務型態）
    API->>Cache: 檢查本地是否已有快取檔
    alt 快取不存在
        API->>Server: 下載原始資料檔（CSV/pkl）
        Server-->>API: 回傳原始資料
        API->>Cache: 寫入本地快取
    else 快取已存在
        Cache-->>API: 直接讀取快取
    end
    API->>API: 資料清洗（去重、標準化 SMILES、處理缺失值）
    U->>API: data.get_split(method="scaffold")
    API->>Split: 依分子骨架分群後切分
    Split-->>U: {"train": df, "valid": df, "test": df}
    U->>Eval: evaluator(y_true, y_pred)
    Eval-->>U: 回傳指標分數（如 ROC-AUC）

這張序列圖揭露了 TDC 架構中兩個容易被忽略、但對可重現性 (reproducibility) 極為關鍵的設計：

• 本地快取機制：資料只會下載一次，之後都從本地讀取，避免重複打 Harvard Dataverse 的頻寬，也避免伺服器維護期間無法重跑實驗
• 中央 metadata 註冊表：所有資料集的下載位址、欄位定義、任務型態都集中在 tdc/metadata.py 管理，這意味著即使某個資料集的托管位址改變，只需要修改 metadata 一處，所有呼叫該資料集的程式碼都不需要更動——這是典型的「單一權威來源 (single source of truth)」設計

2.4 關鍵演算法與方法論舉例

2.4.1 Scaffold Split（分子骨架切分）：為什麼隨機切分是危險的

假設你有 1000 個分子的毒性資料，如果用隨機切分 (random split)，很可能訓練集裡有「苯環-A 藥物 X」，測試集裡有「苯環-A 藥物 Y」——這兩個分子骨架幾乎相同，只是側鏈不同。模型只要記住「苯環-A 有毒」就能在測試集拿高分，但這種高分是假象，因為模型並沒有學到真正的化學規律，遇到全新骨架的分子時會表現很差。

Scaffold split 的做法是：先用演算法（Bemis-Murcko scaffold 演算法）把每個分子拆解出「核心骨架」，確保同一個骨架家族的分子只會出現在訓練集或測試集其中一邊，不會同時出現在兩邊。這模擬了真實藥物開發場景——新藥往往有全新的化學骨架，模型必須具備跨骨架的泛化能力才有實用價值。

用比喻理解：這就像是考試前，老師不會把「同一套題型換個數字」的題目分別放在練習題和正式考題裡——如果這樣做，學生只需要背答案而不用真正理解概念。Scaffold split 就是治療科學 AI 領域的「防止背答案」機制。

2.4.2 Oracle（生成任務評分器）：如何評價「新分子好不好」

在分子生成任務中，模型的輸出是全新的 SMILES 字串，沒有現成的「正確答案」可以比對，因此需要 Oracle（神諭/評分器）機制——一個可以對任意分子計算出分數的函式。TDC 提供 10+ 種現成 oracle，例如：

• GSK3B / JNK3：預測分子對特定蛋白質靶點的抑制活性（用預先訓練好的 QSAR 模型計算）
• QED (Quantitative Estimate of Drug-likeness)：綜合多個藥物化學規則，評估分子「像不像一個藥」
• SA (Synthetic Accessibility)：評估分子在真實世界中容易不容易合成出來
• Docking oracle：透過分子對接模擬，評估分子與蛋白質結合口袋的結合能

這些 oracle 讓「目標導向生成 (goal-oriented generation)」與「分佈學習 (distribution learning)」兩類生成任務都能被量化評估，而不是只靠人眼主觀判斷生成的分子「看起來合理」。

2.4.3 Benchmark Group：多資料集聯合評測的統計嚴謹性

BenchmarkGroup（例如 ADMET_Group）不只是把多個資料集打包，還內建了統計嚴謹性要求：官方規範要求同一個 benchmark 要跑 5 個不同隨機種子 (seed)，回報平均值與標準差，避免研究者「挑選最好看的一次跑分」來灌水結果。這是 TDC 作為評測平台，區別於一般資料集下載站的核心價值——它不只給資料，還規定了「怎麼跑才算公平」。

2.5 內部元件互動全貌

flowchart TB
    subgraph CORE["核心資料存取層"]
        BD["base_dataset.py
共用基底類別"]
        MD["metadata.py
中央註冊表"]
    end

    subgraph PROBLEM["三大問題類別"]
        SP["single_pred.*"]
        MP["multi_pred.*"]
        GEN["generation.*"]
    end

    subgraph FUNC["資料函式層"]
        SPLIT["get_split()
scaffold/random/cold_split"]
        EVAL["Evaluator
ROC_AUC/MAE/Spearman"]
        ORACLE["Oracle
QED/SA/GSK3B/Docking"]
    end

    subgraph BENCH["評測層"]
        BG["BenchmarkGroup
ADMET_Group/DTI_DG_Group..."]
    end

    subgraph TDC2["TDC-2 擴展層"]
        RES["resource.*
PrimeKG/PINNACLE/CellxGene"]
        MS["model_server.*
scGPT/scVI/Geneformer"]
    end

    BD --> SP
    BD --> MP
    BD --> GEN
    MD --> SP
    MD --> MP
    MD --> GEN
    SP --> SPLIT
    MP --> SPLIT
    SP --> EVAL
    MP --> EVAL
    GEN --> ORACLE
    SP --> BG
    MP --> BG
    BG --> EVAL
    MP --> RES
    RES --> MS

    style CORE fill:#1E3A5F,color:#FFFFFF
    style TDC2 fill:#7C2D12,color:#FFFFFF
    style BENCH fill:#166534,color:#FFFFFF

從這張元件互動圖可以看出 TDC 的架構分層策略：核心層（資料存取）與功能層（切分、評估、生成）解耦，任何新任務只要繼承 base_dataset，就自動獲得 get_split()、Evaluator、Oracle 的支援，不需要重新實作。TDC-2 擴展層（resource 與 model_server）則是「插件式」疊加在 multi_pred 之上，特別是單細胞相關任務（anndata_dataset.py）直接依賴 resource.cellxgene_census 取得資料。

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

3.1 前置需求

3.2 依照本專案工具鏈規範的安裝方式（uv 優先）

依照全域規範「Python 用 uv/uvx（禁 pip 當主要安裝）」，建議用 uv 建立隔離環境：

1# 1. 建立專屬虛擬環境（隔離依賴，不污染系統 Python）
2uv venv tdc-env --python 3.10
3source tdc-env/bin/activate
4
5# 2. 用 uv pip 安裝 PyTDC（uv 相容 pip 介面但速度快很多）
6uv pip install PyTDC
7
8# 3. 驗證安裝成功
9python -c "import tdc; print(tdc.__version__)"

3.3 一次性快速試用（不建環境，用 uvx 型態的暫時執行）

如果只是想快速驗證某個資料集長什麼樣子，不想建立永久環境：

1# 用 uv run 在暫時環境中直接執行單次腳本
2uv run --with PyTDC python -c "
3from tdc.single_pred import ADME
4data = ADME(name='HIA_Hou')
5print(data.get_data(format='df').head())
6"

3.4 傳統 pip 安裝方式（官方文件寫法，僅供對照）

官方 README 提供的是最直接的 pip 安裝方式，若專案規範允許或在隔離容器內執行，也可採用：

1pip install PyTDC
2
3# 定期更新（TDC 官方特別強調目前仍是 beta 版本，資料集持續增加）
4pip install PyTDC --upgrade

注意：官方文件明確標註「TDC is in the beta release」，代表資料集清單與 API 都可能持續演進，建議在正式研究專案中 pin 住版本號並記錄在 requirements.txt 或 pyproject.toml 中，避免資料集下載內容因版本更新而悄悄改變，影響結果可重現性。

3.5 用 Docker 容器化安裝（符合本專案「容器優先」規範）

依照全域規範「系統服務預設 Docker/Podman」，若要在可重建、可版本化的環境中使用 TDC：

 1# Dockerfile.tdc
 2FROM python:3.10-slim
 3
 4WORKDIR /workspace
 5
 6# 安裝 RDKit 依賴的系統套件（molconvert 等功能需要）
 7RUN apt-get update && apt-get install -y --no-install-recommends \
 8    libxrender1 libxext6 \
 9    && rm -rf /var/lib/apt/lists/*
10
11RUN pip install --no-cache-dir PyTDC rdkit pandas scikit-learn
12
13ENTRYPOINT ["python"]

1# 建置與執行
2docker build -f Dockerfile.tdc -t tdc-env:latest .
3docker run --rm -v "$(pwd)/data:/workspace/data" tdc-env:latest my_script.py

3.6 Conda 環境設定（官方測試矩陣使用的方式）

由於官方 CI 使用 conda-tests.yml workflow 驗證，若專案本身已有 conda/R+Python 混合環境（如本機的 apotek_r env），也可以整合進去：

1# 建立獨立的 conda 環境
2conda create -n tdc python=3.10 -y
3conda activate tdc
4conda install -c conda-forge rdkit -y
5pip install PyTDC

3.7 環境驗證步驟

安裝完成後，建議跑一次完整的驗證流程，確認資料下載管道與核心功能正常：

 1# verify_tdc.py — 驗證安裝與網路連通性
 2import tdc
 3print(f"TDC 版本: {tdc.__version__}")
 4
 5# 驗證資料下載管道（會建立本地 data/ 資料夾快取）
 6from tdc.single_pred import ADME
 7data = ADME(name="HIA_Hou")
 8df = data.get_data(format="df")
 9assert len(df) > 0, "資料下載失敗或回傳空表"
10print(f"HIA_Hou 資料集載入成功，共 {len(df)} 筆記錄")
11
12# 驗證切分功能
13split = data.get_split(method="scaffold")
14print(f"訓練集: {len(split['train'])} / 驗證集: {len(split['valid'])} / 測試集: {len(split['test'])}")
15
16# 驗證評估器
17from tdc import Evaluator
18evaluator = Evaluator(name="ROC-AUC")
19print("Evaluator 載入成功")
20
21print("✅ TDC 環境驗證通過")

執行 python verify_tdc.py，若看到 ✅ TDC 環境驗證通過，代表環境設定完全正確，可以開始進行後續的研究工作。

3.8 常見安裝陷阱

• RDKit 版本衝突：RDKit 用 conda-forge 安裝比 pip 更穩定，若用 pip 安裝 RDKit 遇到 wheel 編譯失敗，改用 conda 管道
• 首次下載逾時：Harvard Dataverse 有時會維護，若下載卡住，README 中也特別提醒「that happens rarely」，建議稍後重試而非以為是自己環境有問題
• 檔案快取位置：預設會在當前工作目錄建立 data/ 資料夾存放快取，若在不同專案目錄下執行同一個資料集名稱，會重複下載——建議統一設定 path 參數指向共用快取目錄

4. 基本使用 (Basic Usage)

4.1 快速入門：三行程式碼拿到一份乾淨資料

TDC 最核心的賣點就是這三行程式碼的體驗，這也是為什麼它能吸引大量沒有資料工程背景的化學/生物學研究者使用：

 1from tdc.single_pred import ADME
 2
 3# name 參數指定具體資料集；HIA_Hou 是人體腸道吸收 (Human Intestinal Absorption) 資料集
 4data = ADME(name="HIA_Hou")
 5
 6# 取得資料框（DataFrame）格式的完整資料
 7df = data.get_data(format="df")
 8print(df.head())
 9#          Drug_ID                                     Drug  Y
10# 0     Levobunolol  CCCCC(C)NC(C)COc1cccc2c1CCC2=O                   1
11# 1        Metaxalone     CC(NC(=O)c1ccco1)c1cccc(C)c1              1
12# 2       ...

輸出的欄位固定包含 Drug_ID（藥物識別碼）、Drug（SMILES 字串）、Y（標籤，此例為二元分類：1 = 可吸收，0 = 不可吸收）。這種統一欄位命名慣例貫穿所有 single_pred 任務，讓你不需要為每個新資料集重新學習欄位定義。

4.2 場景一：完整的 ADMET 分類任務工作流（新手最常見的第一個練習）

假設一位藥物化學家想要訓練一個模型，預測候選化合物是否具有口服生物利用度 (oral bioavailability)：

 1from tdc.single_pred import ADME
 2from tdc import Evaluator
 3from sklearn.ensemble import RandomForestClassifier
 4from rdkit import Chem
 5from rdkit.Chem import AllChem
 6import numpy as np
 7
 8# 步驟 1：載入資料
 9data = ADME(name="Bioavailability_Ma")
10split = data.get_split(method="scaffold", seed=42)
11
12# 步驟 2：把 SMILES 轉換成 Morgan Fingerprint（分子指紋，機器學習可用的數值向量）
13def smiles_to_fp(smiles_list, n_bits=1024):
14    fps = []
15    for smi in smiles_list:
16        mol = Chem.MolFromSmiles(smi)
17        fp = AllChem.GetMorganFingerprintAsBitVect(mol, radius=2, nBits=n_bits)
18        fps.append(np.array(fp))
19    return np.array(fps)
20
21X_train = smiles_to_fp(split["train"]["Drug"].tolist())
22y_train = split["train"]["Y"].values
23X_test = smiles_to_fp(split["test"]["Drug"].tolist())
24y_test = split["test"]["Y"].values
25
26# 步驟 3：訓練一個基準模型
27clf = RandomForestClassifier(n_estimators=200, random_state=42)
28clf.fit(X_train, y_train)
29y_pred = clf.predict_proba(X_test)[:, 1]
30
31# 步驟 4：用 TDC 官方評估器計算指標（不用自己實作 ROC-AUC 公式）
32evaluator = Evaluator(name="ROC-AUC")
33score = evaluator(y_test, y_pred)
34print(f"口服生物利用度預測 ROC-AUC: {score:.4f}")

這個範例展示了 TDC 與其他工具鏈的協作方式：TDC 負責資料與切分與評估，RDKit 負責分子特徵化，scikit-learn 負責模型訓練——各司其職，沒有相互綁定。

4.3 場景二：藥物-靶點交互作用預測（multi_pred 問題範例）

不同於 ADMET 是「一個分子一個標籤」的單實體預測，藥物-靶點交互作用 (drug-target interaction; DTI) 需要同時輸入兩種實體（藥物 + 蛋白質靶點），屬於 multi_pred 問題：

 1from tdc.multi_pred import DTI
 2
 3# BindingDB_Kd：藥物與蛋白質靶點的結合親和力 (binding affinity) 資料，以 Kd 值為標籤
 4data = DTI(name="BindingDB_Kd")
 5df = data.get_data(format="df")
 6print(df.head())
 7#      Drug_ID   Drug (SMILES)         Target_ID   Target (蛋白質序列)      Y (Kd 值)
 8# 0    CHEMBL...  CC(C)...             P00533       MRPSGTAGAA...           120.5
 9# ...
10
11split = data.get_split(method="cold_split", column_name="Drug")
12print(f"訓練集分子數: {split['train']['Drug'].nunique()}")
13print(f"測試集分子數: {split['test']['Drug'].nunique()}")

這裡用了 cold_split（冷啟動切分），確保測試集中的藥物分子完全沒有出現在訓練集中——模擬「模型從未見過這種藥」的真實場景，這比 scaffold split 更嚴格，是評估模型泛化能力的黃金標準之一。

4.4 場景三：分子生成任務與 Oracle 評分（generation 問題範例）

生成任務展示了 TDC 「輸出沒有固定答案，需要用 Oracle 評分」的獨特設計：

 1from tdc.generation import MolGen
 2from tdc import Oracle
 3
 4# ZINC 資料集：作為分子生成模型的訓練起點（distribution learning 用途）
 5data = MolGen(name="ZINC")
 6df = data.get_data(format="df")
 7print(f"可用於訓練生成模型的分子數: {len(df)}")
 8
 9# 假設你的生成模型輸出了以下候選分子（實際情境中這裡會是模型的 sample() 輸出）
10candidate_smiles = [
11    "CC(C)(C)NCC(O)COc1cccc2ccccc12",   # 類似 propranolol 骨架
12    "c1ccc2c(c1)CCC2=O",
13    "CCOC(=O)c1ccc(N)cc1",
14]
15
16# 用 GSK3B oracle 評估這些分子對 GSK3 beta 蛋白的預測活性
17oracle_gsk3b = Oracle(name="GSK3B")
18scores = oracle_gsk3b(candidate_smiles)
19print("GSK3B 活性預測分數:", scores)
20# [0.03, 0.02, 0.0]  分數範圍 0-1，愈接近 1 代表預測活性愈高
21
22# 同時用 QED（藥物相似性）與 SA（合成可行性）做多目標評估
23oracle_qed = Oracle(name="QED")
24oracle_sa = Oracle(name="SA")
25print("QED 分數:", oracle_qed(candidate_smiles))
26print("SA 分數:", oracle_sa(candidate_smiles))

在真實的目標導向分子生成研究中，這三個 oracle 常常會被組合成一個多目標優化的獎勵函數（例如強化學習中的 reward = 0.5×GSK3B + 0.3×QED − 0.2×SA），這正是 TDC oracle 設計成「可獨立呼叫、回傳單一數值」的用意——方便被組合進任意優化演算法。

4.5 輸入/輸出格式速查表

4.6 支援的 get_data() 輸出格式

除了預設的 format="df"（pandas DataFrame），TDC 還支援其他下游常用格式，讓資料能直接餵給不同框架：

1from tdc.single_pred import ADME
2data = ADME(name="HIA_Hou")
3
4df_format = data.get_data(format="df")        # pandas DataFrame，最通用
5dict_format = data.get_data(format="dict")     # Python dict，適合快速檢視

4.7 探索有哪些資料集可用（避免盲目猜測資料集名稱）

在真正動手做研究之前，最實用的第一步是先查詢某個任務底下到底有哪些資料集可以選：

 1from tdc.utils import retrieve_dataset_names
 2
 3# 查詢 ADME 任務底下所有可用資料集
 4adme_datasets = retrieve_dataset_names("ADME")
 5print(adme_datasets)
 6# ['Caco2_Wang', 'HIA_Hou', 'Pgp_Broccatelli', 'Bioavailability_Ma', 'Lipophilicity_AstraZeneca', ...]
 7
 8# 同樣的方法可以套用在任何任務
 9tox_datasets = retrieve_dataset_names("Tox")
10print(tox_datasets)

這個函式解決了「文件更新速度跟不上資料集新增速度」的常見痛點——不需要頻繁查閱網站，直接在程式碼裡動態查詢當前版本支援哪些資料集。

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

5.1 進階配置：Benchmark Group 完整評測流程

真正要向學術社群或內部團隊證明模型效能時，不能只跑一次訓練/測試，必須依照 TDC 官方要求的多種子 (multi-seed) 評測協定：

 1from tdc import BenchmarkGroup
 2
 3# 載入 ADMET 綜合評測群組（涵蓋 22 個 ADMET 相關子任務）
 4group = BenchmarkGroup(name="ADMET_Group", path="data/")
 5
 6predictions_list = []
 7for seed in [1, 2, 3, 4, 5]:
 8    benchmark = group.get("Caco2_Wang")   # Caco-2 細胞穿透性任務
 9    name = benchmark["name"]
10    train_val, test = benchmark["train_val"], benchmark["test"]
11
12    # 官方規定用 group.get_train_valid_split 而非自行切分，確保跨團隊結果可比較
13    train, valid = group.get_train_valid_split(
14        benchmark=name, split_type="default", seed=seed
15    )
16
17    # -------- 這裡填入你自己的模型訓練與預測邏輯 --------
18    # model = train_my_model(train, valid)
19    # y_pred_test = model.predict(test["Drug"])
20    # ----------------------------------------------------
21
22    predictions = {name: y_pred_test}
23    predictions_list.append(predictions)
24
25# 一次性計算 5 個種子的平均值與標準差
26results = group.evaluate_many(predictions_list)
27print(results)
28# {'caco2_wang': [6.328, 0.101]}   # [平均 MAE, 標準差]

這個流程的價值在於跨團隊可比較性：如果 A 團隊與 B 團隊都遵循同樣的 BenchmarkGroup 協定回報結果，即使他們用完全不同的模型架構，數字仍然是可信、可比較的——這正是排行榜 (leaderboard) 制度存在的意義。

5.2 進階應用案例：整合知識圖譜的藥物重定位研究 (Drug Repurposing)

TDC-2 的 resource 模組讓研究者可以把知識圖譜資訊帶入預測任務，這對藥物重定位 (drug repurposing；找出既有藥物的新適應症) 特別有價值：

 1from tdc.resource import PrimeKG
 2
 3# PrimeKG：整合 20 種生醫資料源的精準醫學知識圖譜
 4# 節點涵蓋疾病、藥物、蛋白質、表現型、通路等 10 種類型
 5primekg = PrimeKG(path="data/")
 6
 7# 取得知識圖譜的邊列表（實體間關係）
 8kg_df = primekg.get_data()
 9print(kg_df.columns)
10# ['relation', 'x_id', 'x_type', 'x_name', 'y_id', 'y_type', 'y_name']
11
12# 篩選出「藥物-疾病」關係，作為藥物重定位候選的知識來源
13drug_disease_edges = kg_df[
14    (kg_df["x_type"] == "drug") & (kg_df["y_type"] == "disease")
15]
16print(f"藥物-疾病關聯邊數: {len(drug_disease_edges)}")

實務上，這類知識圖譜資料常被用來建構圖神經網路 (GNN) 模型的訓練圖譜，讓模型不只看分子結構，還能利用「這個藥物已知會影響哪些蛋白質通路，而這些通路又跟哪些疾病相關」的結構化知識做預測——這正是 Zitnik 實驗室的研究專長領域。

5.3 進階應用案例：單細胞基礎模型整合

TDC-2 的另一個重大擴展是整合單細胞基礎模型 (single-cell foundation model)，讓治療科學研究者能直接呼叫 scGPT、scVI 等預訓練模型，而不需要自己搭建單細胞分析管線：

1from tdc.multi_pred import PerturbOutcome
2
3# 取得基因擾動結果資料集（用於預測 CRISPR 擾動後的細胞轉錄體變化）
4data = PerturbOutcome(name="scperturb_drug_AissaBenevolenskaya2021")
5adata = data.get_data(format="anndata")  # 回傳 AnnData 格式，單細胞分析標準格式
6
7print(f"細胞數: {adata.n_obs}, 基因數: {adata.n_vars}")

這個功能把 TDC 從「治療科學的表格資料平台」延伸成「連接單細胞生物學與藥物開發的橋樑」——這也是 2024 NeurIPS AIDrugX 論文標題 “Signals in the Cells” 想傳達的核心方向：藥物的效果最終要在細胞層級被觀察與驗證，TDC-2 試圖把這個層級也納入統一框架。

5.4 與其他工具/函式庫的整合範例

5.4.1 與 DeepPurpose 整合（官方 tutorial 104 的核心用法）

 1from tdc.single_pred import ADME
 2from DeepPurpose import CompoundPred
 3
 4data = ADME(name="Caco2_Wang")
 5split = data.get_split()
 6
 7# DeepPurpose 提供現成的分子表示學習模型（如 CNN、Transformer、MPNN）
 8config = CompoundPred.generate_config(
 9    drug_encoding="CNN",
10    train_epoch=20,
11    LR=0.001,
12    batch_size=128,
13)
14model = CompoundPred.model_initialize(**config)
15model.train(split["train"], split["valid"], split["test"])

這個組合讓研究者用 15 行程式碼就能訓練出 21 種 ADME 性質的預測模型（README 中明確標註的「15 Lines of Code」承諾），是 TDC 生態系中「資料層 + 模型層」協作最具體的展示。

5.4.2 與 PyTorch Geometric / DGL 整合（圖神經網路場景）

 1from tdc.multi_pred import PPI
 2import torch
 3from torch_geometric.data import Data
 4
 5data = PPI(name="HuRI")
 6df = data.get_data(format="df")
 7
 8# 把蛋白質-蛋白質交互作用資料轉換成圖結構，餵給 PyTorch Geometric
 9protein_ids = list(set(df["Protein1_ID"]).union(set(df["Protein2_ID"])))
10id_to_idx = {pid: i for i, pid in enumerate(protein_ids)}
11
12edge_index = torch.tensor([
13    [id_to_idx[p1] for p1 in df["Protein1_ID"]],
14    [id_to_idx[p2] for p2 in df["Protein2_ID"]],
15], dtype=torch.long)
16
17graph_data = Data(edge_index=edge_index, num_nodes=len(protein_ids))

5.5 效能優化建議

• 本地快取重用：跨專案共用同一個資料快取目錄（統一設定 path 參數），避免重複下載大型資料集（部分蛋白質交互作用資料集可達數 GB）
• 批次特徵化優先於逐筆處理：把 SMILES 轉指紋這類特徵化步驟批次向量化（如用 RDKit 的 Chem.MolFromSmiles 配合 list comprehension 或 multiprocessing.Pool），避免逐行 .apply() 造成效能瓶頸
• 大型 benchmark group 評測用平行化：5 個種子的訓練/評估流程互相獨立，可用 joblib.Parallel 或多程序平行跑，把評測時間壓縮到單一種子的耗時
• Oracle 呼叫批次化：Oracle 內部多為呼叫預訓練好的 QSAR 模型，一次傳入整個候選分子清單（如範例中的 list），比逐個呼叫效能好非常多，因為模型 forward pass 本身支援批次運算

5.6 應用場景總覽圖

flowchart LR
    START(["研究者的問題"]) --> Q1{"任務型態？"}
    Q1 -->|單分子性質預測| ADME_TOX["ADME / Tox
single_pred"]
    Q1 -->|兩實體交互作用| DTI_PPI["DTI / PPI / DDI
multi_pred"]
    Q1 -->|設計新分子| GENTASK["MolGen / SBDD
generation"]
    Q1 -->|跨資料集比較模型| BENCHTASK["BenchmarkGroup"]

    ADME_TOX --> FEAT["特徵化
RDKit / Morgan FP"]
    DTI_PPI --> GRAPH["圖結構化
PyG / DGL"]
    GENTASK --> ORACLE_EVAL["Oracle 評分
QED/SA/GSK3B"]
    BENCHTASK --> MULTISEED["5-seed 評測協定"]

    FEAT --> MODEL1["訓練分類/迴歸模型
RF / DeepPurpose"]
    GRAPH --> MODEL2["訓練 GNN 模型"]
    ORACLE_EVAL --> MODEL3["強化學習 / 生成模型優化"]
    MULTISEED --> LEADERBOARD["提交排行榜"]

    style Q1 fill:#7C2D12,color:#FFFFFF
    style LEADERBOARD fill:#166534,color:#FFFFFF

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

6.1 整合架構圖：TDC 如何連接進 AIKT 27 層

flowchart TB
    subgraph EXT["外部世界"]
        TDCPKG["mims-harvard/TDC
PyTDC 套件"]
        DATAVERSE["Harvard Dataverse
資料伺服器"]
    end

    subgraph AIKT_ACQ["AIKT 知識擷取層 L1-L3"]
        L2["L2 ai-gh-save
已產出本教學文件"]
        L9["L9 paper-search
檢索 TDC 相關論文"]
    end

    subgraph AIKT_ORG["AIKT 知識組織層 L4-L6"]
        L4["L4 graphify
索引 TDC 教學文件"]
    end

    subgraph AIKT_RESEARCH["AIKT 研究管線層 L18-L19"]
        L18["L18 research-pipeline-v2
多輪文獻+資料綜合研究"]
        L19["L19 tu-plan-generator
藥物開發計畫生成"]
    end

    subgraph AIKT_DB["Claude Skills 資料庫查詢"]
        DBLOOKUP["database-lookup skill
PubChem/ChEMBL/DrugBank
BindingDB/ZINC 即時查詢"]
    end

    subgraph AIKT_OUT["AIKT 專業輸出層 L11-L12"]
        L11["L11 kami
研究報告排版"]
        L12["L12 gh-tutorial-qd
本教學文件產出入口"]
    end

    TDCPKG -.->|"提供已切分的 ADMET/DTI 基準資料"| DATAVERSE
    L2 -->|"本次任務已完成"| TDCPKG
    L9 -.->|"檢索 NeurIPS/Nature Chem Bio 論文"| TDCPKG
    L18 -->|"引用 TDC leaderboard 數據作為 SOTA 佐證"| L19
    DBLOOKUP -.->|"互補：即時單一實體查詢"| TDCPKG
    L4 -->|"索引本文件供未來查詢"| L18
    L12 -->|"編譯本教學為 HTML/PDF"| L11

    style AIKT_ACQ fill:#1E3A5F,color:#FFFFFF
    style AIKT_ORG fill:#334155,color:#FFFFFF
    style AIKT_RESEARCH fill:#7C2D12,color:#FFFFFF
    style AIKT_DB fill:#78350F,color:#FFFFFF
    style AIKT_OUT fill:#166534,color:#FFFFFF

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

TDC 與 AIKT 現有能力的重疊程度，其實遠比表面看起來的低——原因是 AIKT 明確定位為「編排知識，不做直接科學計算」，而 TDC 恰好是「直接科學計算」的資料底層。但仍有一個值得深入比較的重疊區域：

6.2.1 重疊點：與 database-lookup skill 的化學/生醫資料庫查詢功能

誰做得更好、為什麼：這兩者其實不是直接競品，而是分工明確的互補關係。若把它們硬拗成「競爭」，可以這樣說——

• 當任務是「我要訓練/評估一個 ADMET 預測模型」，TDC 完勝：它已經幫你切好資料、定義好評估指標、甚至有排行榜可以比較，database-lookup 只能給你原始資料，剩下所有工程都要自己做
• 當任務是「我只是想快速查一下某個 SMILES 對應的 ChEMBL ID 是什麼」，database-lookup 完勝：不需要下載、快取、進入 TDC 的三層 API 心智模型，一行 API 呼叫就搞定

市場定位衝突：目前沒有真正的定位衝突，因為 AIKT 從不試圖成為機器學習基準測試平台（這需要維護資料切分協定、排行榜、Oracle 評分模型等長期基礎設施，成本遠超 AIKT 的「知識工作流編排」定位）。唯一需要留意的灰色地帶是：如果未來有人想在 AIKT 裡新增一個「直接下載 TDC 資料集」的 wrapper skill，那就會與單純呼叫 pip install PyTDC 幾乎零差異——這種重複造輪子的整合不建議做，因為它不創造新價值。

6.2.2 為什麼不算真正紅海：AIKT 的「不做直接科學計算」邊界

AIKT 的核心優勢明確寫著「知識工作流自動化、文件編譯、多源研究綜合、專業輸出生成」，且定位聲明「不做直接科學計算——它編排知識，不是演算法」。TDC 恰恰是「演算法評測基礎設施」，兩者的核心價值主張幾乎垂直不相交。這代表：與 TDC 相關的紅海風險極低，重點應該放在藍海機會的開發。

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

6.3.1 未滿足的需求一：TDC 排行榜數據沒有被自動整合進研究決策文件

TDC 官網維護了數十個公開排行榜（例如 ADMET Group 的 22 個子任務排行榜），但這些數據散落在網頁上，沒有結構化匯出成可被引用的知識庫。研究者若想在自己的計畫書或內部報告中引用「目前 Caco2_Wang 任務的 SOTA MAE 是多少」，必須手動去官網查、手動複製貼上。

AIKT 可以做的藍海切入：讓 tu-plan-generator（L19，藥物開發計畫生成）在生成 ADMET 相關的開發計畫章節時，自動查詢 TDC 排行榜的最新 SOTA 數據，作為「目前業界基準是多少，我們的候選化合物預測值與其比較如何」的量化佐證，而不是只靠文字描述。這填補了「排行榜數據」與「決策文件」之間的斷層。

6.3.2 未滿足的需求二：TDC 論文與教學資源沒有被整合進文獻研究流程

TDC 有豐富的學術發表歷史（NeurIPS、Nature Chemical Biology），但目前的 AIKT paper-search (L9) 若要檢索這些論文，仍需要研究者自己知道要搜什麼關鍵字。

AIKT 可以做的藍海切入：建立一個輕量的「基準測試平台知識庫」映射表，把常見的治療科學 benchmark 平台（TDC、MoleculeNet、GuacaMol 等）與其代表性論文、資料集清單、排行榜網址預先索引進 paper-qa-lite (L10) 的本地知識庫，讓研究者問「TDC 的 DTI 任務有哪些資料集適合用來驗證我的 GNN 模型」時，可以立刻得到有依據的回答，而不需要每次都重新查官網或重新讀 README。

6.3.3 互補的 AIKT 層級盤點

6.3.4 具體差異化策略：「基準測試顧問」而非「基準測試重複實作」

AIKT 若要切入 TDC 所在的領域，絕對不應該重新實作一套資料下載/切分/評估邏輯——這是 TDC 已經做得很好、且有學術背書的核心價值，重做只是浪費工程資源且沒有優勢。正確的差異化策略是站在「更高一層」：

• TDC 回答的問題是：「這個模型在這個任務上的表現數字是多少？」
• AIKT 應該回答的問題是：「基於這個表現數字，我的研究/開發計畫應該怎麼調整？這個數字跟文獻中的其他方法比較起來意味著什麼？」

這種分工方式，正好對應「AIKT 編排知識，不是演算法」的定位聲明——TDC 產生「事實」（benchmark 分數），AIKT 產生「決策支援」（把事實轉化成研究計畫、對外報告、下一步行動建議）。

6.4 推薦整合方案：三階段實施路徑

階段一（低成本、立即可做）：知識索引層整合

1. 把本教學文件（02-TDC.md）與 TDC README、三篇核心論文摘要放入 paper-qa-lite 的本地知識庫
2. 用 graphify 對任何內部使用 TDC 的研究程式碼建立索引，方便未來查詢「我們哪些專案用了 TDC 的哪個資料集」

驗收條件：能透過 pq: TDC 的 scaffold split 跟 cold split 差異是什麼 這類問題得到基於本文件的準確回答。

階段二（中成本、需要少量開發）：排行榜數據橋接

1. 開發一個輕量腳本（非完整 skill），定期（例如每月）從 TDC 官網或 GitHub 上抓取主要 benchmark group 的當前排行榜排名快照，存成結構化 JSON/CSV
2. 讓 tu-plan-generator 在生成 ADMET/Tox 相關章節時，可以讀取這份快照作為引用來源

驗收條件：tu-plan-generator 生成的藥物開發計畫中，ADMET 章節能自動附上「目前 TDC ADMET_Group 排行榜 SOTA 是 XX，模型比較基準」的量化陳述，且來源可追溯。

階段三（長期、需要驗證需求強度後投入）：研究管線深度整合

1. 讓 research-pipeline-v2 在多輪研究流程中，可以呼叫 TDC Python API 本身（不只是靜態快照），針對特定候選化合物即時查詢相似分子在 TDC 資料集中的已知性質，作為初步篩選依據
2. 這一階段涉及讓 AIKT 首次「觸碰」到實際的 Python 資料科學運算（呼叫 TDC 的 get_data() / Evaluator），需要仔細評估是否違反「AIKT 不做直接科學計算」的定位邊界——建議的折衷方案是讓這類運算封裝成獨立的、明確標註「這是資料查詢輔助工具，非模型訓練/評估」的最小化腳本，AIKT 只負責觸發與呈現結果，不負責計算邏輯的正確性驗證

必停必問提示：階段三涉及「是否要讓 AIKT 執行實際的科學計算邏輯」，這觸及 AIKT 定位的核心邊界問題，依專案規範，展開此階段前應先與使用者確認是否要調整 AIKT 的能力邊界定義。

6.5 紅海 vs 藍海機會定位圖

quadrantChart
    title "TDC 相關功能：重疊風險 vs 整合價值"
    x-axis "低整合價值" --> "高整合價值"
    y-axis "低重疊風險" --> "高重疊風險"
    quadrant-1 "優先投入"
    quadrant-2 "謹慎評估"
    quadrant-3 "低優先"
    quadrant-4 "避免重複造輪子"
    "知識索引 paper-qa-lite": [0.75, 0.15]
    "排行榜數據橋接 tu-plan-generator": [0.85, 0.25]
    "database-lookup 互補查詢": [0.45, 0.35]
    "重新實作資料切分邏輯": [0.2, 0.85]
    "重新實作 Oracle 評分": [0.15, 0.8]
    "研究管線深度整合": [0.7, 0.45]
    "codebase 索引 graphify": [0.5, 0.1]

從象限分布可以清楚看出：知識索引與排行榜數據橋接落在「優先投入」象限（高價值、低重疊風險），而任何試圖重新實作 TDC 已有的資料切分或 Oracle 評分邏輯，都落在「避免重複造輪子」象限——這驗證了前述「AIKT 應扮演基準測試顧問而非重複實作者」的策略方向是正確的。

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

7.0 規模數據速覽（幫助評估專案採用成本）

7.1 效能特性

• 資料存取效能：核心資料存取邏輯輕量（僅依賴 pandas/numpy），首次下載後全部走本地快取，重複實驗的資料載入時間可壓縮到秒級
• 評測協定的統計效能：官方要求的 5-seed 評測雖然增加運算時間（5 倍於單次跑分），但這是換取結果可信度的必要成本，不建議為了省時間而只跑 1 個種子後就宣稱結果
• Oracle 評分效能：多數 Oracle（如 QED、SA）是基於規則或輕量 QSAR 模型，單次呼叫延遲低；但 docking oracle 涉及分子對接模擬，運算成本顯著較高，大量候選分子評分時應考慮批次化與平行化

7.2 已知限制

1. Beta 版本的穩定性風險：官方明確標註仍在 beta 階段，API 與資料集清單可能變動，正式研究專案需要 pin 版本號並記錄快取資料的雜湊值以確保長期可重現性
2. 資料集品質受限於原始來源：TDC 是「策展者」而非「資料生產者」，若原始論文的資料本身有標註錯誤或系統性偏差，TDC 無法憑空修正，只能盡力做標準化清洗
3. 對 RDKit 等第三方套件的隱性依賴：雖然核心依賴清單很輕量，但真正要做任何「有意義」的分子層級操作（特徵化、視覺化），幾乎必然需要額外安裝 RDKit，這在文件中不總是被明確強調
4. 中文/多語言支援缺失：這是純英語生態系的工具，所有欄位名稱、文件、社群討論皆為英文，無中文使用者社群
5. 單細胞與知識圖譜功能相對新，成熟度不一：resource 與 model_server 模組是 TDC-2 才加入的功能，相較於歷史悠久的 single_pred/multi_pred，社群使用案例與文件範例都還在累積階段

7.3 與同類工具比較

7.4 何時使用 vs 何時不使用

適合使用 TDC 的情境：

• 需要一個「業界公認」的基準來驗證新模型架構是否真的有效
• 需要跨多個治療領域（ADMET、DTI、生成）做系統性比較
• 需要向審稿人/主管證明結果具有可重現性與統計嚴謹性（多種子評測）
• 教學場景：需要一套現成、乾淨的資料快速上手機器學習 for 藥物發現

不適合使用 TDC 的情境：

• 需要極度即時、單筆查詢的場景（改用 database-lookup 或直接呼叫 API）
• 已有內部專屬資料且該資料的統計特性與 TDC 公開資料差異極大（TDC 上驗證的方法未必能直接遷移到私有資料分布）
• 需要監管級別 (regulatory-grade) 的資料溯源與驗證（TDC 是研究工具，非 GxP 合規資料源，不能直接作為法規送審文件的資料依據）

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

8.1 關鍵要點回顧

1. TDC 的核心貢獻是標準化，不是新演算法——它把治療科學領域最痛苦的「資料格式混亂 + 缺乏公平評測」問題,用三層階層架構（Problem → Learning Task → Dataset）系統性解決
2. 三行程式碼取得乾淨資料 + 統一切分/評估協定，是它能在學術界快速普及（1263 stars、219 forks、頂尖期刊背書）的關鍵原因
3. TDC-2 的多模態擴展（知識圖譜 PrimeKG、單細胞基礎模型、模型中心）代表這個生態系正從「表格資料基準」演化為「跨尺度治療科學基礎設施」
4. 與 AIKT 幾乎沒有紅海衝突，因為 AIKT 明確定位為知識編排而非科學計算，兩者的核心價值主張垂直不相交
5. 最有價值的整合方向是「知識橋接」而非「功能重製」——把 TDC 的排行榜數據、學術文獻、使用案例，橋接進 AIKT 的研究與計畫生成流程，讓 AIKT 使用者不用離開工作流就能取得有依據的量化佐證

8.2 最佳使用場景總結

對於本專案（AIKT）的實際使用者（生技/製藥研究人員）而言，TDC 最實用的三個切入點：

1. 模型驗證的第一站：任何新開發的 ADMET/DTI/毒性預測模型，先用 TDC 對應資料集跑一次基準測試，確認方法論站得住腳，再投入到私有資料上
2. 文獻與計畫佐證來源：撰寫研究計畫或內部報告時，引用 TDC 排行榜的 SOTA 數據作為「業界基準線」，讓論述更有量化說服力
3. 教學與新人上手材料：TDC 官方 tutorial（101-106、TDC-2 的 201-205）是目前最完整的「機器學習 for 治療科學」入門教材之一，適合作為內部訓練資源

8.3 未來發展方向觀察

從 2021 到 2024 的發展軌跡（NeurIPS Datasets Track → Nature Chemical Biology → NeurIPS AIDrugX Workshop），TDC 明顯朝著多模態、跨尺度整合的方向演進——從單純的分子表格資料，擴展到知識圖譜、單細胞轉錄體、以及外部模型中心的整合。可以合理預期，未來版本會持續：

• 加入更多基礎模型 (foundation model) 的即插即用整合（類似目前的 scGPT/scVI/Geneformer）
• 擴大臨床試驗與真實世界證據 (real-world evidence) 相關資料集，呼應精準醫學的發展趨勢
• 持續強化知識圖譜與表格資料的融合，讓預測模型能同時利用結構化知識與原始實驗資料

對於 AIKT 而言，這意味著「知識橋接」策略的長期價值會隨著 TDC 生態系擴張而持續增加——TDC 產出的可信任事實層越豐富，AIKT 能編排進研究決策文件的素材就越多。建議定期（例如每季）重新檢視 TDC 的更新動態，評估是否有新的整合機會出現。

8.4 給後續操作者的具體建議

• 若要開始階段一整合（知識索引），直接使用 paper-qa-lite 將本文件與 TDC README 建立本地知識庫即可，無需額外開發
• 若要推進階段二（排行榜數據橋接），建議先與使用者確認 tu-plan-generator 是否已有既定的資料引用格式規範，避免格式不一致
• 任何涉及讓 AIKT 直接執行 TDC Python API 進行科學計算的提案（階段三），依規範必須先觸發「必停必問」流程，取得使用者對能力邊界調整的明確同意

8.5 延伸閱讀清單

• 官方網站：tdcommons.ai —— 完整資料集清單、即時排行榜
• 官方文件：tdc.readthedocs.io —— API 參考文件
• NeurIPS 2021 論文：《Therapeutics Data Commons: Machine Learning Datasets and Tasks for Drug Discovery and Development》
• Nature Chemical Biology 2022 論文：《Artificial intelligence foundation for therapeutic science》
• NeurIPS 2024 AIDrugX Workshop 論文：《Signals in the Cells: Multimodal and Contextualized Machine Learning Foundations for Therapeutics》
• 官方 Slack 工作空間：join.slack.com/t/pytdc —— 即時社群討論與問題排解
• GitHub Issues：github.com/mims-harvard/TDC/issues —— 官方問題回報與功能請求管道

附錄 A：完整學習任務對照表

為了讓後續操作者不需要每次都重新查官網，這裡整理 TDC 三大問題類別底下的完整學習任務清單，附上中英雙語說明與典型應用場景。

A.1 single_pred（單實體預測）任務清單

A.2 multi_pred（多實體預測）任務清單

A.3 generation（生成任務）任務清單

A.4 常用評估指標速查

附錄 B：常見問題 (FAQ)

Q1：TDC 的資料集會不會過時或連結失效？

A：TDC 官方在 README 中特別提醒，多數資料集托管在 Harvard Dataverse（有正式的 DOI 持久識別碼），維護頻率相對穩定，但仍建議正式研究專案在下載後把資料快取一併納入版本控制或至少記錄雜湊值，避免因為上游資料更新導致實驗結果無法重現。

Q2：一定要裝 RDKit 才能用 TDC 嗎？

A：不一定。純粹取得 get_data() 回傳的 DataFrame（SMILES 字串、標籤）不需要 RDKit。但只要你想對 SMILES 做任何有意義的化學運算（轉指紋、算分子量、畫結構圖、chem_utils 底下的多數功能），幾乎都會間接依賴 RDKit，建議一開始就裝好。

Q3：get_split() 的 method 參數有哪些選項？該怎麼選？

A：主要有 random（隨機切分，最不嚴謹但最快）、scaffold（按分子骨架切分，適合小分子性質預測的標準做法）、cold_split（冷啟動切分，確保測試集實體完全未出現在訓練集，適合藥物或蛋白質的泛化能力測試）。選擇原則：越接近真實部署場景的切分方法越嚴謹，也越應該優先採用，即使模型分數看起來會比隨機切分低。

Q4：TDC 的 Oracle 分數可以信任到什麼程度？

A：Oracle 本身多數是預先訓練好的替代模型 (surrogate model)，不是真實濕實驗室 (wet lab) 測得的結果，應該把 Oracle 分數視為「計算化學層級的初步篩選訊號」，而不是最終療效證據。任何通過 Oracle 高分篩選的候選分子，仍需要後續濕實驗驗證。

Q5：TDC 支援中文或非英語的資料集嗎？

A：目前沒有。所有資料集的欄位、文件、討論皆為英文，這是純國際學術社群工具，使用時建議搭配內部翻譯或雙語文件（如本教學文件）降低語言門檻。

Q6：BenchmarkGroup 跑分結果可以直接拿去投稿論文嗎？

A：只要嚴格遵循官方規定的 5-seed 評測協定、使用官方提供的切分方式，並在方法段落中清楚記錄 TDC 版本號，這類跑分結果具有學術可信度，且已有大量發表論文採用這種方式回報結果。但仍建議額外檢查該任務是否已有已知的資料洩漏 (data leakage) 討論。

Q7：TDC-2 的 resource 與 model_server 模組是否穩定可用於生產環境？

A：這兩個模組相對新（2024 年才隨 TDC-2 論文一起大幅擴充），建議先在研究/原型階段驗證，暫不建議直接用於對外正式產品的生產環境，需持續關注官方更新與 issue 追蹤。