1Plugin (基底類別)
2  ├── name()        → 插件名稱
3  ├── type()        → 插件類型 (generic / privacy / ...)
4  ├── hyperparameter_space() → 超參數搜尋空間
5  ├── fit(dataloader)        → 訓練
6  ├── generate(count, constraints) → 生成
7  └── save() / load()        → 序列化

 1# 建議使用 uv 建立隔離環境
 2uv venv synthcity-env --python 3.10
 3source synthcity-env/bin/activate
 4
 5# 基本安裝
 6uv pip install synthcity
 7
 8# 完整安裝（含所有可選依賴）
 9uv pip install "synthcity[all]"
10
11# 含測試工具
12uv pip install "synthcity[testing]"

 1from synthcity.plugins import Plugins
 2
 3# 列出所有可用的生成器
 4all_plugins = Plugins().list()
 5print(f"可用生成器數量: {len(all_plugins)}")
 6print(all_plugins)
 7
 8# 列出隱私類生成器
 9privacy_plugins = Plugins(categories=["privacy"]).list()
10print(f"隱私類生成器: {privacy_plugins}")

 1"""
 2範例 1：EHR 結構化資料合成與隱私評估
 3場景：合成糖尿病患者臨床資料，評估統計品質與隱私風險
 4"""
 5import pandas as pd
 6from sklearn.datasets import load_diabetes
 7from synthcity.plugins import Plugins
 8from synthcity.plugins.core.dataloader import GenericDataLoader
 9from synthcity.benchmark import Benchmarks
10
11# ── 步驟 1：準備資料 ──────────────────────────────
12X, y = load_diabetes(return_X_y=True, as_frame=True)
13X["target"] = y
14
15# 建立 DataLoader，標記敏感欄位
16# 在真實 EHR 中，sensitive_columns 應包含 age, sex, race 等
17loader = GenericDataLoader(
18    X,
19    target_column="target",
20    sensitive_columns=["sex"],  # 用於公平性評估
21)
22
23print(f"原始資料筆數: {len(X)}")
24print(f"欄位數: {X.shape[1]}")
25print(f"欄位名稱: {list(X.columns)}")
26
27# ── 步驟 2：訓練隱私保護生成器 ─────────────────────
28# 使用 PATEGAN：結合 PATE 框架的差分隱私 GAN
29syn_model = Plugins().get(
30    "pategan",
31    # 差分隱私參數
32    epsilon=1.0,           # 隱私預算 (越小越隱私、效用越低)
33    n_teachers=10,         # PATE 教師模型數量
34    moments_order=100,     # 隱私會計矩次數
35)
36
37syn_model.fit(loader)
38
39# ── 步驟 3：生成合成資料 ──────────────────────────
40synthetic_data = syn_model.generate(count=500)
41syn_df = synthetic_data.dataframe()
42
43print(f"\n合成資料筆數: {len(syn_df)}")
44print(f"\n合成資料統計摘要:")
45print(syn_df.describe().round(3))
46
47# ── 步驟 4：全面評估 ──────────────────────────────
48# 使用 Benchmarks 同時比較多個生成器
49score = Benchmarks.evaluate(
50    [
51        ("pategan_eps1", "pategan", {"epsilon": 1.0}),
52        ("pategan_eps5", "pategan", {"epsilon": 5.0}),
53        ("dpgan_eps1",   "dpgan",   {"epsilon": 1.0}),
54        ("adsgan",       "adsgan",  {}),
55    ],
56    loader,
57    synthetic_size=500,
58    metrics={
59        "sanity":      ["data_mismatch", "common_rows_proportion"],
60        "stats":       ["jensenshannon_dist", "inv_kl_divergence"],
61        "privacy":     ["delta-presence", "k-anonymization"],
62        "performance": ["linear_model"],
63    },
64    repeats=2,
65)
66
67# 印出比較結果
68Benchmarks.print(score)

 1"""
 2範例 2：臨床試驗存活端點合成
 3場景：模擬 PFS/OS 存活曲線，用於 protocol 設計的 power analysis
 4"""
 5import pandas as pd
 6import numpy as np
 7from synthcity.plugins import Plugins
 8from synthcity.plugins.core.dataloader import SurvivalAnalysisDataLoader
 9
10# ── 步驟 1：準備存活分析資料 ──────────────────────
11# 模擬臨床試驗資料（真實場景：從 EDC 匯出的 SDTM/ADaM 格式）
12np.random.seed(42)
13n_patients = 200
14
15clinical_data = pd.DataFrame({
16    "age":       np.random.normal(62, 12, n_patients).astype(int),
17    "sex":       np.random.choice([0, 1], n_patients),
18    "stage":     np.random.choice([1, 2, 3, 4], n_patients, p=[0.1, 0.3, 0.4, 0.2]),
19    "treatment": np.random.choice([0, 1], n_patients),      # 0=對照組, 1=實驗組
20    "biomarker": np.random.lognormal(2, 0.8, n_patients),
21    # 存活端點
22    "pfs_weeks": np.random.exponential(24, n_patients),      # PFS (週)
23    "event":     np.random.choice([0, 1], n_patients, p=[0.3, 0.7]),  # 1=事件發生
24})
25
26# 建立存活分析 DataLoader
27surv_loader = SurvivalAnalysisDataLoader(
28    clinical_data,
29    target_column="event",              # 事件指標欄位
30    time_to_event_column="pfs_weeks",   # 事件時間欄位
31)
32
33print(f"原始資料: {len(clinical_data)} 名患者")
34print(f"事件發生率: {clinical_data['event'].mean():.1%}")
35print(f"中位 PFS: {clinical_data['pfs_weeks'].median():.1f} 週")
36
37# ── 步驟 2：訓練存活分析生成器 ─────────────────────
38# SurvivalGAN 專門針對存活資料的分佈特性設計
39surv_model = Plugins().get("survival_gan")
40surv_model.fit(surv_loader)
41
42# ── 步驟 3：生成合成臨床試驗資料 ──────────────────
43syn_surv = surv_model.generate(count=500)
44syn_surv_df = syn_surv.dataframe()
45
46print(f"\n合成資料: {len(syn_surv_df)} 名虛擬患者")
47print(f"合成事件發生率: {syn_surv_df['event'].mean():.1%}")
48print(f"合成中位 PFS: {syn_surv_df['pfs_weeks'].median():.1f} 週")
49
50# ── 步驟 4：比較原始 vs 合成的 Kaplan-Meier 曲線 ──
51# 可搭配 lifelines 繪製 KM 曲線比較
52try:
53    from lifelines import KaplanMeierFitter
54    import matplotlib.pyplot as plt
55
56    fig, ax = plt.subplots(1, 1, figsize=(8, 5))
57
58    kmf_real = KaplanMeierFitter()
59    kmf_real.fit(
60        clinical_data["pfs_weeks"],
61        event_observed=clinical_data["event"],
62        label="Real Data (真實資料)"
63    )
64    kmf_real.plot(ax=ax)
65
66    kmf_syn = KaplanMeierFitter()
67    kmf_syn.fit(
68        syn_surv_df["pfs_weeks"],
69        event_observed=syn_surv_df["event"],
70        label="Synthetic Data (合成資料)"
71    )
72    kmf_syn.plot(ax=ax)
73
74    ax.set_xlabel("Weeks (週)")
75    ax.set_ylabel("Survival Probability (存活機率)")
76    ax.set_title("Real vs Synthetic Kaplan-Meier Curve")
77    plt.tight_layout()
78    plt.savefig("km_comparison.png", dpi=150)
79    print("\nKM 曲線比較圖已儲存: km_comparison.png")
80except ImportError:
81    print("提示：安裝 lifelines 與 matplotlib 可繪製 KM 曲線比較圖")

 1"""
 2範例 3：差分隱私 epsilon 權衡分析
 3場景：為合規團隊提供 epsilon 選擇的量化依據
 4"""
 5import pandas as pd
 6from sklearn.datasets import load_diabetes
 7from synthcity.plugins import Plugins
 8from synthcity.plugins.core.dataloader import GenericDataLoader
 9from synthcity.metrics.eval_statistical import AlphaPrecision
10from synthcity.metrics.eval_privacy import DeltaPresence
11
12# ── 準備資料 ──────────────────────────────────────
13X, y = load_diabetes(return_X_y=True, as_frame=True)
14X["target"] = y
15loader = GenericDataLoader(X, target_column="target")
16
17# ── 不同 epsilon 值的比較實驗 ─────────────────────
18epsilons = [0.1, 0.5, 1.0, 3.0, 5.0, 10.0]
19results = []
20
21for eps in epsilons:
22    print(f"\n{'='*50}")
23    print(f"訓練 DP-GAN, epsilon = {eps}")
24    print(f"{'='*50}")
25
26    # 訓練 DP-GAN
27    model = Plugins().get("dpgan", epsilon=eps)
28    model.fit(loader)
29
30    # 生成合成資料
31    syn = model.generate(count=len(X))
32
33    # 評估統計品質（Alpha Precision）
34    stat_score = AlphaPrecision().evaluate(
35        loader, syn
36    )
37
38    # 評估隱私風險（Delta Presence）
39    priv_score = DeltaPresence().evaluate(
40        loader, syn
41    )
42
43    result = {
44        "epsilon": eps,
45        "alpha_precision": float(stat_score.get("delta_precision_alpha_OC", 0)),
46        "delta_presence": float(priv_score.get("score", 0)),
47    }
48    results.append(result)
49    print(f"  統計品質 (Alpha Precision): {result['alpha_precision']:.4f}")
50    print(f"  隱私風險 (Delta Presence):  {result['delta_presence']:.4f}")
51
52# ── 結果彙整 ─────────────────────────────────────
53df_results = pd.DataFrame(results)
54print("\n" + "="*60)
55print("Epsilon 權衡分析結果")
56print("="*60)
57print(df_results.to_string(index=False))
58print("\n解讀指引:")
59print("  - Alpha Precision 越高 → 統計品質越好")
60print("  - Delta Presence 越低 → 隱私保護越強")
61print("  - 一般建議: 醫療資料 epsilon = 1.0~3.0 為合理區間")
62print("  - HIPAA Safe Harbor: 無明確 epsilon 標準，但建議 epsilon <= 1.0")
63print("  - GDPR: 歐盟尚無具體 epsilon 門檻，但 Article 89 要求 'appropriate safeguards'")

1Synthea (患者模擬)              synthcity (表格合成)
2───────────────────        ───────────────────
3產出完整患者生命歷程            接收任何表格資料
4FHIR/CSV 格式輸出    ─────→    GenericDataLoader 匯入
5基於規則的生成                  基於學習的生成
6無隱私保證                      內建差分隱私
7無品質評估                      完整評估體系

 1# synthcity 生成的合成資料可直接匯入標準 ML/統計工具
 2syn_df = syn_model.generate(count=1000).dataframe()
 3
 4# → pandas 分析
 5syn_df.describe()
 6
 7# → scikit-learn 建模
 8from sklearn.model_selection import train_test_split
 9X_train, X_test = train_test_split(syn_df, test_size=0.2)
10
11# → lifelines 存活分析
12from lifelines import CoxPHFitter
13cph = CoxPHFitter()
14cph.fit(syn_df, duration_col="pfs_weeks", event_col="event")
15
16# → 匯出為 CSV（可轉換為 CDISC SDTM/ADaM 格式）
17syn_df.to_csv("synthetic_clinical_data.csv", index=False)