1score(y_perturbed, x, t) = GBT(y_perturbed, x, t) / σ(t)

1L = || GBT(y_perturbed, x, t) - (-z) ||²

 1treeffuser/
 2├── src/treeffuser/
 3│   ├── __init__.py                    # 匯出 Treeffuser, Samples
 4│   ├── treeffuser.py                  # 主類別：參數定義、SDE/Score 工廠
 5│   ├── _base_tabular_diffusion.py     # 基礎類別：fit/sample/predict 流程
 6│   ├── _score_models.py               # LightGBMScoreModel 訓練邏輯
 7│   ├── _scaler.py                     # 混合型特徵標準化
 8│   ├── _warnings.py                   # 收斂警告定義
 9│   ├── samples.py                     # Samples 統計工具類別
10│   └── sde/
11│       ├── base_sde.py                # SDE 抽象基礎類別
12│       ├── base_solver.py             # SDE Solver 抽象類別 + 註冊器
13│       ├── diffusion_sdes.py          # VESDE / VPSDE / SubVPSDE 實作
14│       ├── initialize.py              # 從資料初始化 SDE 超參數
15│       ├── parameter_schedule.py      # 線性/指數排程
16│       └── solvers.py                 # Euler-Maruyama 求解器
17├── examples/                          # 範例 Notebook
18├── testbed/                           # 論文基準測試框架
19└── pyproject.toml                     # Poetry 管理，依賴 LightGBM 4.3.0

1# 建議使用 uv 建立隔離環境
2uv venv treeffuser-env --python 3.11
3source treeffuser-env/bin/activate
4
5# 從 PyPI 安裝
6uv pip install treeffuser
7
8# 或從 GitHub 安裝開發版
9uv pip install git+https://github.com/blei-lab/treeffuser.git@main

 1from treeffuser import Treeffuser, Samples
 2import numpy as np
 3
 4# 快速驗證
 5rng = np.random.default_rng(42)
 6X = rng.normal(size=(100, 3))
 7y = X[:, 0] + rng.normal(scale=0.1, size=100)
 8model = Treeffuser(n_estimators=100, n_repeats=5, seed=42)
 9model.fit(X, y)
10samples = model.sample(X[:5], n_samples=10, seed=42)
11print(f"取樣完成：shape = {samples.shape}")  # (10, 5)

 1import numpy as np
 2import matplotlib.pyplot as plt
 3from treeffuser import Treeffuser, Samples
 4
 5# 模擬藥物劑量-反應資料
 6# 高劑量時反應較一致，低劑量時變異大（heteroscedastic）
 7seed = 42
 8rng = np.random.default_rng(seed)
 9n = 3000
10
11dose = rng.uniform(0.1, 10.0, size=n)          # 劑量 (mg/kg)
12response_mean = 100 * (1 - np.exp(-0.5 * dose))  # Emax 模型
13response_std = 20 / (1 + dose)                   # 低劑量高變異
14response = response_mean + rng.normal(scale=response_std, size=n)
15
16# 訓練 Treeffuser
17model = Treeffuser(
18    n_estimators=2000,       # LightGBM 迭代次數
19    n_repeats=30,            # 每筆資料產生 30 個加噪版本
20    early_stopping_rounds=50,
21    seed=seed,
22)
23model.fit(dose, response)
24
25# 在測試點上取樣條件分佈
26dose_test = np.linspace(0.5, 9.5, 50)
27y_samples = model.sample(dose_test, n_samples=200, seed=seed, verbose=True)
28samples_obj = Samples(y_samples)
29
30# 計算統計量
31y_mean = samples_obj.sample_mean()
32y_q05, y_q95 = samples_obj.sample_quantile(q=[0.05, 0.95])
33
34# 視覺化
35fig, ax = plt.subplots(figsize=(10, 6))
36ax.scatter(dose, response, s=1, alpha=0.3, label="觀測資料")
37ax.plot(dose_test, y_mean, "r-", linewidth=2, label="條件均值 E[y|x]")
38ax.fill_between(dose_test, y_q05, y_q95, alpha=0.3, color="red",
39                label="90% 預測區間")
40ax.set_xlabel("劑量 (mg/kg)")
41ax.set_ylabel("藥物反應")
42ax.set_title("Treeffuser：異質變異性劑量-反應預測")
43ax.legend()
44plt.tight_layout()
45plt.savefig("dose_response_treeffuser.png", dpi=150)

 1import numpy as np
 2from treeffuser import Treeffuser, Samples
 3
 4seed = 42
 5rng = np.random.default_rng(seed)
 6n = 5000
 7
 8# 特徵：年齡、BMI、基因分數
 9age = rng.uniform(30, 70, n)
10bmi = rng.uniform(18, 35, n)
11gene_score = rng.uniform(0, 1, n)
12
13X = np.column_stack([age, bmi, gene_score])
14
15# 雙模態反應：gene_score > 0.5 的族群反應良好
16responder_prob = 1 / (1 + np.exp(-5 * (gene_score - 0.5)))
17is_responder = rng.binomial(1, responder_prob)
18
19# 有反應者：腫瘤縮小 40-60%；無反應者：縮小 0-10%
20tumor_shrinkage = np.where(
21    is_responder,
22    rng.normal(50, 8, n),    # 有反應者
23    rng.normal(5, 5, n),     # 無反應者
24)
25
26# 訓練
27model = Treeffuser(n_estimators=2000, n_repeats=30, seed=seed)
28model.fit(X, tumor_shrinkage)
29
30# 對兩種極端患者取樣
31patient_responder = np.array([[50, 25, 0.9]])    # 高基因分數
32patient_non_resp = np.array([[50, 25, 0.1]])      # 低基因分數
33patient_mixed = np.array([[50, 25, 0.5]])          # 邊界基因分數
34
35n_samples = 500
36samples_r = model.sample(patient_responder, n_samples=n_samples, seed=seed)
37samples_n = model.sample(patient_non_resp, n_samples=n_samples, seed=seed)
38samples_m = model.sample(patient_mixed, n_samples=n_samples, seed=seed)
39
40# 分析：邊界患者的分佈應該是雙峰的
41samples_mixed = Samples(samples_m)
42print(f"邊界患者 - 均值: {samples_mixed.sample_mean()[0]:.1f}%")
43print(f"邊界患者 - 標準差: {samples_mixed.sample_std()[0]:.1f}%")
44q05, q95 = samples_mixed.sample_quantile(q=[0.05, 0.95])
45print(f"邊界患者 - 90% CI: [{q05[0]:.1f}%, {q95[0]:.1f}%]")
46# 使用 KDE 觀察雙峰結構
47kde = samples_mixed.sample_kde()

 1import numpy as np
 2from treeffuser import Treeffuser, Samples
 3
 4seed = 42
 5rng = np.random.default_rng(seed)
 6n = 2000
 7
 8# 特徵：體重、年齡、CYP 酵素活性
 9weight = rng.uniform(50, 100, n)
10age = rng.uniform(20, 80, n)
11cyp_activity = rng.uniform(0.5, 2.0, n)
12X = np.column_stack([weight, age, cyp_activity])
13
14# 目標：同時預測 AUC 和 Cmax（二維目標）
15clearance = 10 * cyp_activity / (weight ** 0.75)
16auc = 500 / clearance + rng.normal(0, 20, n)
17cmax = 50 / clearance + rng.normal(0, 5, n)
18y = np.column_stack([auc, cmax])
19
20# 訓練（多維目標）
21model = Treeffuser(n_estimators=1500, n_repeats=20, seed=seed)
22model.fit(X, y)
23
24# 為新患者預測 PK 參數聯合分佈
25new_patient = np.array([[70, 45, 1.2]])
26pk_samples = model.sample(new_patient, n_samples=1000, seed=seed)
27# pk_samples.shape = (1000, 1, 2) → 1000 個 (AUC, Cmax) 樣本
28
29# 下游決策：劑量調整
30# 若超過 80% 樣本的 Cmax 在安全範圍內，建議該劑量
31cmax_samples = pk_samples[:, 0, 1]
32safe_fraction = np.mean(cmax_samples < 100)  # Cmax < 100 為安全
33print(f"安全範圍內的機率: {safe_fraction:.1%}")
34print(f"AUC 均值: {pk_samples[:, 0, 0].mean():.1f}")
35print(f"Cmax 均值: {cmax_samples.mean():.1f}")
36
37# 利用樣本做 Cost-Sensitive 決策
38# 過高 → 毒性成本 10 倍 vs 過低 → 療效不足成本 1 倍
39cost_overshoot = 10 * np.maximum(0, cmax_samples - 100)
40cost_undershoot = 1 * np.maximum(0, 50 - cmax_samples)
41expected_cost = (cost_overshoot + cost_undershoot).mean()
42print(f"期望成本: {expected_cost:.2f}")

 1# 虛擬碼：驗證合成資料是否保留了 p(y|x) 結構
 2from treeffuser import Treeffuser
 3import numpy as np
 4
 5# 1. 在真實資料上訓練 Treeffuser
 6model_real = Treeffuser(seed=42)
 7model_real.fit(X_real, y_real)
 8
 9# 2. 在合成資料上訓練另一個 Treeffuser
10model_synth = Treeffuser(seed=42)
11model_synth.fit(X_synth, y_synth)
12
13# 3. 在測試點上比較兩者的條件分佈
14X_test = X_real[:100]
15samples_real = model_real.sample(X_test, n_samples=500, seed=42)
16samples_synth = model_synth.sample(X_test, n_samples=500, seed=42)
17
18# 比較統計量
19from scipy.stats import ks_2samp
20ks_stats = [
21    ks_2samp(samples_real[:, i], samples_synth[:, i]).statistic
22    for i in range(len(X_test))
23]
24print(f"平均 KS 距離: {np.mean(ks_stats):.4f}")

1# SDMetrics: 邊際/成對評估
2from sdmetrics.reports.single_table import QualityReport
3report = QualityReport()
4report.generate(real_data, synth_data, metadata)
5
6# Treeffuser: 條件分佈評估（SDMetrics 不做這個）
7# → 檢查 p_synth(y|x) 是否 ≈ p_real(y|x)

 1是否需要預測 p(y|x) 的完整分佈？
 2├── 否 → 不需要 Treeffuser
 3│   ├── 需要生成合成表格 → SDV / synthcity / ForestDiffusion
 4│   └── 需要點預測 → LightGBM / XGBoost / sklearn
 5└── 是
 6    ├── 資料是表格型嗎？
 7    │   ├── 否 → 用 Neural Network-based Diffusion
 8    │   └── 是
 9    │       ├── 不需 GPU？ → Treeffuser (首選)
10    │       ├── y 維度間相關很重要？ → 考慮 TabDDPM / 其他
11    │       └── 需要 DP 隱私？ → dp_cgans 或自行加層
12    └── Treeffuser 適用

 1from treeffuser import Treeffuser, Samples
 2
 3# 初始化（常用參數）
 4model = Treeffuser(
 5    n_repeats=30,              # 擴增倍率
 6    n_estimators=3000,         # LightGBM 樹數量
 7    early_stopping_rounds=50,  # 早停輪次
 8    sde_name="vesde",          # SDE 類型
 9    seed=42,
10)
11
12# 訓練
13model.fit(X, y)                # X: (n, d), y: (n,) 或 (n, k)
14
15# 取樣
16y_samples = model.sample(
17    X_new,                     # (m, d)
18    n_samples=100,             # 每個 x 取幾個樣本
19    seed=42,
20    verbose=True,
21)  # 回傳 (100, m) 或 (100, m, k)
22
23# 統計分析
24s = Samples(y_samples)
25s.sample_mean()                # 條件均值
26s.sample_std()                 # 條件標準差
27s.sample_quantile(q=[0.05, 0.95])  # 分位數
28s.sample_confidence_interval(confidence=0.95)
29s.sample_kde()                 # 核密度估計
30s.sample_apply(custom_fn)      # 自訂統計量

1@article{beltranvelez2024treeffuser,
2  title={Treeffuser: Probabilistic Predictions via Conditional Diffusions
3         with Gradient-Boosted Trees},
4  author={Nicolas Beltran-Velez and Alessandro Antonio Grande and
5          Achille Nazaret and Alp Kucukelbir and David Blei},
6  year={2024},
7  journal={NeurIPS 2024},
8  url={https://arxiv.org/abs/2406.07658},
9}