CausalBench 完整教學

從 AWS EC2 連線到 causal network inference（因果網路推論）：用淺顯易懂的方式理解如何在真實 Perturb-seq 資料上跑基因調控網路推論。

1. 專案定位 — 這到底是什麼？

用一個比喻來理解

想像你有一座巨大的工廠（cell；細胞），裡面有數千台機器（gene；基因）在運作。你想知道：哪台機器會影響哪台機器？ 例如，當你關掉機器 A 時，機器 B 和 C 是否也會跟著改變？

這就是 **causal network inference（因果網路推論）**的核心問題：從「關掉某基因後，其他基因如何反應」的實驗數據中，推斷基因之間的因果關係。

CausalBench 的角色

CausalBench 不是一個推論工具——它是一個裁判。它提供：

1. 真實的考題（Perturb-seq 資料集）
2. 標準答案（已知的生物學交互作用網路）
3. 評分機制（多種 biological + statistical metrics）
4. 20+ 位選手（內建的推論方法）

你可以用它來比較不同的 causal discovery 方法，找出最適合你的資料的方法。

flowchart TD
    A["你的問題：
哪些基因互相影響？"] --> B["CausalBench 提供"]
    B --> C["考題
200,000+ 單細胞
Perturb-seq 資料"]
    B --> D["選手
20+ 種
causal discovery 方法"]
    B --> E["標準答案
CORUM / STRING /
ChIP-seq 等已知網路"]
    B --> F["評分
Biological + Statistical
evaluation metrics"]
    C --> G["你選一個方法跑"]
    D --> G
    G --> H["CausalBench 評分"]
    E --> H
    F --> H
    H --> I["結果：這個方法好不好？"]

2. 核心概念淺解

2.1 什麼是 Perturb-seq？

Perturb-seq = Perturbation（擾動）+ Sequencing（定序）

flowchart LR
    A["細胞群"] --> B["用 CRISPR 關掉
特定基因"]
    B --> C["測量每個細胞
所有基因的表現量"]
    C --> D["得到一張大表格
行=細胞 列=基因
值=表現量"]

• 每次「關掉一個基因」稱為一次 intervention（介入）
• 觀察其他基因的變化，就能推斷因果關係
• CausalBench 用的是 Weissmann 等人的 Perturb-seq 資料

2.2 兩個資料集

兩個都是 DepMap essential gene（必需基因）的 Perturb-seq。

2.3 三種訓練模式

flowchart TD
    A["Training Regime
訓練模式"] --> B["Observational
觀察性
只給未擾動的資料"]
    A --> C["Partial Interventional
部分介入性
給部分基因的擾動資料"]
    A --> D["Full Interventional
完全介入性
給所有基因的擾動資料"]
    
    B --> E["最難
像只看工廠正常運作
就要猜機器間的關係"]
    C --> F["中等
看了一些機器被關掉的情況"]
    D --> G["最容易
看過所有機器被關掉的情況"]

2.4 內建的 20+ 種推論方法

flowchart TD
    subgraph Traditional ["傳統因果推論"]
        PC["PC Algorithm
條件獨立性測試"]
        GES["GES
Greedy Equivalence Search"]
        GIES["GIES
介入版 GES"]
        GSP["GSP / IGSP
Sparsest Permutation"]
    end
    
    subgraph ML ["機器學習"]
        Lasso["Lasso
L1 正則化特徵選擇"]
        RF["Random Forest
隨機森林特徵選擇"]
        GRN["GRNBoost / GENIE
基因調控網路推論"]
        Sort["Sortnregress
排序 + 回歸"]
    end
    
    subgraph DL ["深度學習"]
        NT["NOTEARS
連續化 DAG 約束"]
        DCDI["DCDI
Differentiable Causal Discovery"]
        DCDFG["DCDFG
Differentiable DAG"]
    end
    
    subgraph Bio ["生物學基線"]
        CORUM["CORUM
蛋白質複合體"]
        STRING["STRING
蛋白質交互作用"]
        ChIP["ChIP-seq
轉錄因子結合"]
        LR["Ligand-Receptor
配體-受體對"]
    end

2.5 評估指標淺解

CausalBench 用多種「標準答案」來評分：

flowchart LR
    A["你的方法
預測的基因網路"] --> B{"與標準答案比對"}
    B --> C["CORUM
蛋白質複合體"]
    B --> D["STRING
蛋白質交互作用"]
    B --> E["ChIP-seq
轉錄因子結合"]
    B --> F["Ligand-Receptor
配體-受體"]
    B --> G["Statistical
Hold-out 預測力"]
    C --> H["每個指標產出
precision / recall / F1
AUROC / AUPRC"]
    D --> H
    E --> H
    F --> H
    G --> H

3. 公司 AWS EC2 連線指南 — apotek-tw Server

3.1 Server 規格

m8a.2xlarge 是目前可執行 CausalBench 的最低規格（約等於 32 GB RAM 筆電）。Ubuntu 先前無法順利安裝 CausalBench，因此目前採用 Amazon Linux 2023。

3.2 連線流程總覽

flowchart TD
    A["收到 AWS Console
登入資訊"] --> B["登入 AWS
Management Console"]
    B --> C["找到 EC2 instance:
apotek-tw"]
    C --> D{"Instance
是否正在執行?"}
    D -->|是| E["可能有其他成員
正在使用
請先確認"]
    D -->|否| F["Start instance"]
    F --> G["取得 Public IPv4
或 Public DNS"]
    G --> H["更新本機
SSH config
的 HostName"]
    H --> I["VS Code
Remote - SSH
連線"]
    I --> J["開啟
~/apotek/causalbench"]
    J --> K["啟動 venv"]
    K --> L["執行
causalbench_run"]
    L --> M["檢查
./output/ 結果"]
    M --> N["deactivate"]
    N --> O["回 AWS Console
停止 instance"]
    
    style E fill:#fff3cd
    style O fill:#d4edda

3.3 Step-by-Step 連線教學

Step 1：安裝 VS Code Extension

在本機 VS Code 安裝 Remote - SSH（Microsoft 官方 extension）。

Step 2：設定 Key File 權限

SSH key file 名稱：apotek-tw.pem

Linux / macOS：

1chmod 400 /path/to/apotek-tw.pem

Windows PowerShell：

1icacls "/path/to/apotek-tw.pem" /inheritance:r
2icacls "/path/to/apotek-tw.pem" /grant:r "${env:USERNAME}:R"

Step 3：設定 VS Code SSH Host

1. VS Code 按 Ctrl+Shift+P（macOS：Cmd+Shift+P）
2. 選 Remote-SSH: Open SSH Configuration File...
3. 選 ~/.ssh/config
4. 加入以下設定：

1Host apotek-tw
2    HostName <EC2_PUBLIC_IP_OR_PUBLIC_DNS>
3    User ec2-user
4    IdentityFile /path/to/apotek-tw.pem

Step 4：VS Code 連線

1. 點左下角綠色 Open a Remote Window 圖示
2. 選 Connect to Host…
3. 選 apotek-tw
4. Platform type 選 Linux
5. Fingerprint 確認選 Continue

Step 5：開啟工作區

1cd ~/apotek/causalbench

Step 6：啟動 Python Virtual Environment

1source ./.venv/bin/activate

完成後退出：

1deactivate

3.4 重要注意事項

flowchart LR
    subgraph Before ["使用前"]
        B1["確認 instance 狀態"]
        B2["Start 後等 1-2 分鐘"]
        B3["更新 HostName
（IP 可能變）"]
    end
    
    subgraph During ["使用中"]
        D1["在 ~/apotek/causalbench
工作"]
        D2["結果存在 ./output/"]
        D3["大型運算注意
32GB RAM 限制"]
    end
    
    subgraph After ["使用後"]
        A1["deactivate venv"]
        A2["回 AWS Console
Stop instance"]
        A3["省成本！
只有跑的時候收費"]
    end

4. 執行 CausalBench — 從零開始

4.1 基本指令結構

flowchart LR
    CMD["causalbench_run"] --> DS["--dataset_name
選資料集"]
    CMD --> OUT["--output_directory
結果存哪"]
    CMD --> DATA["--data_directory
資料快取"]
    CMD --> TR["--training_regime
訓練模式"]
    CMD --> MODEL["--model_name
選方法"]
    CMD --> SEED["--model_seed
隨機種子"]
    CMD --> FILTER["--do_filter
過濾低表現基因"]
    CMD --> PATH["--max_path_length
最大路徑長度"]
    CMD --> OMIT["--omission_estimation_size
估計遺漏率的樣本數"]

4.2 第一次跑的範例

 1causalbench_run \
 2  --dataset_name weissmann_k562 \
 3  --output_directory ./output/ \
 4  --data_directory ./data/storage \
 5  --training_regime observational \
 6  --model_name sortnregress \
 7  --subset_data 1.0 \
 8  --model_seed 0 \
 9  --do_filter \
10  --max_path_length -1 \
11  --omission_estimation_size 500

參數解說：

4.3 輸出結構

flowchart TD
    OUT["./output/"] --> EXP["實驗資料夾
（自動編號）"]
    EXP --> ARG["arguments.json
紀錄你用了什麼參數"]
    EXP --> MET["metrics.json
所有評估指標結果"]
    EXP --> NET["output_network.csv
預測的基因網路邊"]

metrics.json 包含的評估結果：

 1{
 2  "corum_evaluation": { "precision": ..., "recall": ..., "f1": ... },
 3  "ligand_receptor_evaluation": { ... },
 4  "string_network_evaluation": { ... },
 5  "string_physical_evaluation": { ... },
 6  "chipseq_evaluation": { ... },
 7  "quantitative_test_evaluation": { ... },
 8  "pooled_biological_evaluation": { ... },
 9  "run_time": 123.45
10}

4.4 試不同方法

 1# 快速比較多種方法
 2for method in sortnregress pc grnboost lasso random_forest; do
 3  causalbench_run \
 4    --dataset_name weissmann_k562 \
 5    --output_directory ./output/ \
 6    --data_directory ./data/storage \
 7    --training_regime observational \
 8    --model_name $method \
 9    --subset_data 0.5 \
10    --model_seed 0 \
11    --do_filter \
12    --max_path_length -1 \
13    --omission_estimation_size 500
14done

用 --subset_data 0.5 可以跑快一倍（用一半資料），適合初步比較。

5. 自訂模型 — 加入你自己的方法

5.1 介面定義

所有模型只需實作一個 __call__ 方法：

 1from causalscbench.models.abstract_model import AbstractInferenceModel
 2
 3class MyModel(AbstractInferenceModel):
 4    def __init__(self):
 5        super().__init__()
 6
 7    def __call__(
 8        self,
 9        expression_matrix,    # numpy array [cells x genes]
10        interventions,        # list of intervention labels
11        gene_names,           # list of gene names
12        training_regime,      # TrainingRegime enum
13        seed=0,
14    ):
15        # 你的推論邏輯
16        edges = []
17        # 回傳 list of (gene_a, gene_b) tuples
18        return edges

flowchart LR
    Input["輸入"] --> A["expression_matrix
基因表現矩陣
[cells x genes]"]
    Input --> B["interventions
每個細胞被擾動的基因"]
    Input --> C["gene_names
基因名稱列表"]
    Input --> D["training_regime
訓練模式"]
    
    Process["你的模型
推論邏輯"] --> Output["輸出"]
    A --> Process
    B --> Process
    C --> Process
    D --> Process
    
    Output --> E["List of
(gene_a, gene_b)
因果邊"]

5.2 用自訂模型跑 benchmark

把你的模型存成 Python 檔（如 my_model.py），然後：

1causalbench_run \
2  --dataset_name weissmann_k562 \
3  --output_directory ./output/ \
4  --data_directory ./data/storage \
5  --training_regime observational \
6  --model_name custom \
7  --inference_function_file_path ./my_model.py \
8  --model_seed 0

6. 資安掃描報告

掃描範圍

掃描結論

🟢 低風險 — GSK 官方維護的研究工具，Apache-2.0 license。程式碼中無危險函式呼叫，無硬編碼機密。唯一注意事項是首次執行會下載外部資料集，確認在可信任的網路環境下進行。

AWS EC2 安全注意事項

• .pem key file 設定 chmod 400，不要分享或上傳版本控制
• EC2 每次 stop/start 後 IP 可能改變，需更新 SSH config
• 使用完畢務必回 AWS Console 停止 instance（省成本）
• 不要在 EC2 上存放個人機密資料

7. FAQ

Q1：CausalBench 和我做的 lead optimization 有什麼關係？

A： CausalBench 推論的 gene regulatory network（基因調控網路）可以幫你理解：你的藥物 target（標靶）在細胞中影響了哪些 downstream gene（下游基因）。這對 mechanism of action（作用機制）研究、off-target effect（脫靶效應）評估、biomarker（生物標記）發現都有幫助。

Q2：跑一次大概要多久？

A： 在 m8a.2xlarge（32GB RAM）上，用 sortnregress 跑全量 K562 資料約 5-10 分鐘。較複雜的方法（如 NOTEARS-MLP、DCDI）可能需要 30 分鐘到數小時。用 --subset_data 0.5 可以減半時間。

Q3：我能在自己的筆電上跑嗎？

A： 理論上可以（需 16+ GB RAM），但 32 GB RAM 是建議最低規格。建議用公司的 AWS EC2 instance 跑完整資料。筆電可以先用 --subset_data 0.1 做小規模測試。

Q4：結果要怎麼看？最重要的指標是什麼？

A： 看 metrics.json 中的 pooled_biological_evaluation（綜合生物學評估）的 F1 score 是最直觀的。如果你關心特定類型的交互作用，可以看 corum_evaluation（蛋白質複合體）或 chipseq_evaluation（轉錄因子結合）。

Q5：Ubuntu 安裝失敗怎麼辦？

A： CausalBench 在 Ubuntu 上的安裝歷來有問題（依賴衝突），這也是公司 EC2 採用 Amazon Linux 2023 的原因。建議直接用公司 EC2，或在 Docker 中跑。

8. 進階技巧

8.1 使用介入性資料（Interventional）

如果你有 CRISPR 擾動的實驗數據，可以用 interventional 模式得到更好的結果：

 1# Full interventional — 最佳結果
 2causalbench_run \
 3  --training_regime interventional \
 4  --model_name igsp \
 5  ...
 6
 7# Partial interventional — 只有部分基因有擾動資料
 8causalbench_run \
 9  --training_regime partial_interventional \
10  --fraction_partial_intervention 0.5 \
11  --model_name igsp \
12  ...

8.2 比較結果的 Python 腳本

 1import json
 2import os
 3import pandas as pd
 4
 5results = []
 6for exp_dir in os.listdir("./output/"):
 7    args_path = os.path.join("./output/", exp_dir, "arguments.json")
 8    metrics_path = os.path.join("./output/", exp_dir, "metrics.json")
 9    if os.path.exists(args_path) and os.path.exists(metrics_path):
10        with open(args_path) as f:
11            args = json.load(f)
12        with open(metrics_path) as f:
13            metrics = json.load(f)
14        results.append({
15            "method": args["model_name"],
16            "regime": args["training_regime"],
17            "corum_f1": metrics["corum_evaluation"].get("f1", 0),
18            "string_f1": metrics["string_network_evaluation"].get("f1", 0),
19            "pooled_f1": metrics["pooled_biological_evaluation"].get("f1", 0),
20            "runtime": metrics["run_time"],
21        })
22
23df = pd.DataFrame(results).sort_values("pooled_f1", ascending=False)
24print(df.to_string(index=False))

8.3 選方法的建議

flowchart TD
    Q1{"你有介入性
（CRISPR）資料嗎？"} -->|有| Q2{"資料量大嗎？
（>50,000 cells）"}
    Q1 -->|沒有| Q3{"要速度還是精度？"}
    
    Q2 -->|大| A1["IGSP
（介入版 GSP）"]
    Q2 -->|小| A2["GIES
（介入版 GES）"]
    
    Q3 -->|速度| A3["Sortnregress
（最快）"]
    Q3 -->|精度| A4["GRNBoost
（Random Forest based）"]
    Q3 -->|兩者兼顧| A5["PC Algorithm
（經典平衡）"]

9. 整合進其他工作流

與 Lead Optimization 的串接

flowchart TD
    A["Lead Optimization
產出新 analog"] --> B["需要理解
target 的 downstream effect"]
    B --> C["CausalBench 跑
gene regulatory network"]
    C --> D["識別 target 基因
的影響範圍"]
    D --> E["評估 off-target risk"]
    D --> F["找 biomarker
for drug response"]
    D --> G["Retrosynthesis
（用 aizynthfinder）"]

與 Retrosynthesis 工具的搭配

CausalBench 幫你理解「目標基因的因果網路」，retrosynthesis 工具（aizynthfinder 等）幫你合成新分子。兩者串接：

1. CausalBench → 找到最值得 target 的基因
2. AI Lead Optimization → 針對該 target 產出 analog
3. aizynthfinder → 評估 analog 的合成可行性

10. 重點摘要 Checklist

• 理解 CausalBench：是「裁判」不是「選手」— 用來比較不同 causal discovery 方法
• 兩個資料集：K562 / RPE1 Perturb-seq
• 三種模式：observational（最難）→ partial interventional → full interventional
• 20+ 內建方法：從 PC 到 DCDI，一行指令跑
• 評估看什麼：pooled_biological_evaluation 的 F1 score 最直觀
• AWS EC2 連線：Start instance → 更新 IP → VS Code Remote SSH → source venv
• 用完停 instance：省 AWS 成本！
• 自訂模型：實作 AbstractInferenceModel.__call__() 即可
• 快速測試：--subset_data 0.5 + sortnregress 最快
• 結果比較：用 Python 讀 metrics.json 做表格比較

11. 進一步閱讀

論文

• Chevalley et al., “A large-scale benchmark for network inference from single-cell perturbation data”, Communications Biology, 2025. DOI: 10.1038/s42003-025-07764-y

專案資源

• GitHub Repository
• ICLR-23 Challenge 網頁
• PyPI: causalbench

資料來源

• Replogle et al. Perturb-seq (CC-BY-4.0)
• CORUM 蛋白質複合體 (CC-BY-NC)
• STRING-DB (CC-BY-4.0)
• CellTalkDB (GPL-3.0)
• ChIP-Atlas (CC-BY-SA-4.0)

相關工具

• causal-learn — Python causal discovery library
• scanpy — Single-cell analysis
• Perturb-seq 論文集