1# 使用 pip（推薦搭配虛擬環境）
2pip install sdmetrics
3
4# 使用 conda
5conda install -c conda-forge sdmetrics
6
7# 使用 uv（AIKT 推薦方式）
8uv pip install sdmetrics

1import sdmetrics
2print(sdmetrics.__version__)
3
4# 載入 demo 資料驗證
5from sdmetrics import load_demo
6real_data, synthetic_data, metadata = load_demo(modality='single_table')
7print(f"Real data shape: {real_data.shape}")
8print(f"Synthetic data shape: {synthetic_data.shape}")
9print(f"Metadata columns: {list(metadata['columns'].keys())}")

 1metadata = {
 2    "columns": {
 3        "gene_expr_A": {"sdtype": "numerical"},
 4        "gene_expr_B": {"sdtype": "numerical"},
 5        "cell_type": {"sdtype": "categorical"},
 6        "patient_id": {"sdtype": "id"},
 7        "measurement_date": {"sdtype": "datetime", "datetime_format": "%Y-%m-%d"}
 8    },
 9    "primary_key": "patient_id"
10}

 1import pandas as pd
 2import numpy as np
 3from sdmetrics.reports.single_table import QualityReport, DiagnosticReport
 4
 5# === 模擬藥物開發場景的資料 ===
 6np.random.seed(42)
 7n = 500
 8
 9# 真實資料：臨床試驗的受試者數據
10real_data = pd.DataFrame({
11    "patient_age": np.random.normal(55, 12, n).clip(18, 85),
12    "tumor_size_mm": np.random.lognormal(3.0, 0.5, n),
13    "biomarker_level": np.random.gamma(2, 3, n),
14    "treatment_group": np.random.choice(["drug_A", "drug_B", "placebo"], n, p=[0.4, 0.4, 0.2]),
15    "response": np.random.choice(["CR", "PR", "SD", "PD"], n, p=[0.15, 0.25, 0.35, 0.25]),
16})
17
18# 合成資料（假設由某個 SDG 模型生成）
19synthetic_data = pd.DataFrame({
20    "patient_age": np.random.normal(54, 13, n).clip(18, 85),
21    "tumor_size_mm": np.random.lognormal(3.1, 0.6, n),
22    "biomarker_level": np.random.gamma(2.1, 2.8, n),
23    "treatment_group": np.random.choice(["drug_A", "drug_B", "placebo"], n, p=[0.38, 0.42, 0.20]),
24    "response": np.random.choice(["CR", "PR", "SD", "PD"], n, p=[0.13, 0.27, 0.33, 0.27]),
25})
26
27# Metadata 定義
28metadata = {
29    "columns": {
30        "patient_age": {"sdtype": "numerical"},
31        "tumor_size_mm": {"sdtype": "numerical"},
32        "biomarker_level": {"sdtype": "numerical"},
33        "treatment_group": {"sdtype": "categorical"},
34        "response": {"sdtype": "categorical"},
35    }
36}
37
38# === 生成品質報告 ===
39quality_report = QualityReport()
40quality_report.generate(real_data, synthetic_data, metadata)
41
42# 取得整體分數
43print(f"Overall Quality Score: {quality_report.get_score():.2%}")
44
45# 取得各 property 的分數
46properties = quality_report.get_properties()
47print(properties)
48# 輸出範例：
49#            Property Name  Score
50# 0          Column Shapes  0.89
51# 1     Column Pair Trends  0.76
52
53# 取得各欄位的詳細分數
54details = quality_report.get_details(property_name='Column Shapes')
55print(details)
56# 輸出範例：
57#           Column  Metric     Score
58# 0    patient_age  KSComplement  0.92
59# 1  tumor_size_mm  KSComplement  0.85
60# 2  biomarker_level  KSComplement  0.88
61# 3  treatment_group  TVComplement  0.94
62# 4       response  TVComplement  0.91
63
64# === 生成診斷報告 ===
65diagnostic_report = DiagnosticReport()
66diagnostic_report.generate(real_data, synthetic_data, metadata)
67print(f"Diagnostic Score: {diagnostic_report.get_score():.2%}")
68
69# === 視覺化 ===
70# 產生 Plotly 互動圖（在 Jupyter Notebook 中直接顯示）
71fig = quality_report.get_visualization(property_name='Column Shapes')
72# fig.show()  # 取消註解以顯示
73
74# 儲存報告
75quality_report.save(filepath='clinical_trial_quality.pkl')

 1from sdmetrics.single_table import NewRowSynthesis
 2from sdmetrics.single_table.privacy import (
 3    DisclosureProtection,
 4    DCRBaselineProtection,
 5    DCROverfittingProtection,
 6    CategoricalCAP,
 7)
 8
 9# === 檢查合成資料是否為真實資料的複製品 ===
10# NewRowSynthesis：計算合成列中有多少比例是「新」的（非真實資料的精確複製）
11new_row_score = NewRowSynthesis.compute(
12    real_data,
13    synthetic_data,
14    metadata,
15    numerical_match_tolerance=0.01,  # 數值容差 1%
16    synthetic_sample_size=100,       # 抽樣 100 列做比對
17)
18print(f"New Row Synthesis Score: {new_row_score:.4f}")
19# 理想值 = 1.0（所有合成列都是新的）
20# 警戒值 < 0.9（過多複製）
21
22# === Disclosure Protection（洩漏防護）===
23# 衡量攻擊者能否透過合成資料推斷真實資料中的敏感欄位
24disclosure_score = DisclosureProtection.compute(
25    real_data,
26    synthetic_data,
27    metadata,
28    known_column_names=["treatment_group", "patient_age"],  # 攻擊者已知的欄位
29    sensitive_column_names=["response"],                     # 敏感欄位（目標推斷）
30)
31print(f"Disclosure Protection Score: {disclosure_score:.4f}")
32# 高分 = 隱私保護好，攻擊者難以推斷
33
34# === DCR (Distance to Closest Record) 指標 ===
35# DCRBaselineProtection：合成資料與真實資料的最近距離是否高於隨機基線
36dcr_baseline = DCRBaselineProtection.compute(
37    real_data,
38    synthetic_data,
39    metadata,
40)
41print(f"DCR Baseline Protection: {dcr_baseline:.4f}")
42
43# DCROverfittingProtection：合成資料是否過擬合（memorize）訓練資料
44dcr_overfit = DCROverfittingProtection.compute(
45    real_data,
46    synthetic_data,
47    metadata,
48)
49print(f"DCR Overfitting Protection: {dcr_overfit:.4f}")
50
51# === 解讀隱私分數的決策框架 ===
52print("\n=== 隱私評估摘要 ===")
53privacy_pass = True
54checks = {
55    "New Row Synthesis": (new_row_score, 0.9),
56    "Disclosure Protection": (disclosure_score, 0.7),
57    "DCR Baseline": (dcr_baseline, 0.5),
58    "DCR Overfitting": (dcr_overfit, 0.5),
59}
60for name, (score, threshold) in checks.items():
61    status = "PASS" if score >= threshold else "FAIL"
62    if score < threshold:
63        privacy_pass = False
64    print(f"  {name}: {score:.3f} (threshold={threshold}) [{status}]")
65
66print(f"\nOverall Privacy: {'PASS - Safe to share' if privacy_pass else 'FAIL - Review needed'}")

 1from sdmetrics.reports.single_table import QualityReport
 2from sdmetrics.single_table import NewRowSynthesis
 3from sdmetrics.single_column import KSComplement, TVComplement, BoundaryAdherence
 4import pandas as pd
 5import numpy as np
 6
 7# === 假設有三個模型的合成輸出 ===
 8# （實際使用中，這些會由 SDV/CTGAN/TabDDPM 分別生成）
 9models = {
10    "CTGAN": synthetic_data_ctgan,       # CTGAN 生成的資料
11    "TabDDPM": synthetic_data_tabddpm,   # TabDDPM 生成的資料
12    "GaussianCopula": synthetic_data_gc, # GaussianCopula 生成的資料
13}
14
15# === 逐模型評估 ===
16results = []
17
18for model_name, syn_data in models.items():
19    # 品質報告
20    qr = QualityReport()
21    qr.generate(real_data, syn_data, metadata)
22    quality_score = qr.get_score()
23
24    # 隱私分數
25    privacy_score = NewRowSynthesis.compute(
26        real_data, syn_data, metadata,
27        numerical_match_tolerance=0.01,
28        synthetic_sample_size=min(100, len(syn_data)),
29    )
30
31    # 逐欄位 KS / TV 分數
32    column_scores = {}
33    for col, col_meta in metadata["columns"].items():
34        if col_meta["sdtype"] == "numerical":
35            column_scores[col] = KSComplement.compute(real_data[col], syn_data[col])
36        elif col_meta["sdtype"] == "categorical":
37            column_scores[col] = TVComplement.compute(real_data[col], syn_data[col])
38
39    # 邊界遵守
40    boundary_scores = {}
41    for col, col_meta in metadata["columns"].items():
42        if col_meta["sdtype"] == "numerical":
43            boundary_scores[col] = BoundaryAdherence.compute(real_data[col], syn_data[col])
44
45    results.append({
46        "Model": model_name,
47        "Quality Score": quality_score,
48        "Privacy Score": privacy_score,
49        "Avg Column Score": np.mean(list(column_scores.values())),
50        "Avg Boundary Adherence": np.mean(list(boundary_scores.values())),
51    })
52
53# === 比較結果表 ===
54comparison_df = pd.DataFrame(results)
55comparison_df = comparison_df.sort_values("Quality Score", ascending=False)
56print(comparison_df.to_string(index=False))
57
58# 輸出範例：
59#          Model  Quality Score  Privacy Score  Avg Column Score  Avg Boundary Adherence
60#        TabDDPM          0.91           0.98              0.89                    0.95
61#          CTGAN          0.84           1.00              0.82                    0.88
62#  GaussianCopula          0.79           0.99              0.77                    0.92
63
64# === 決策建議 ===
65best_model = comparison_df.iloc[0]
66print(f"\n推薦模型: {best_model['Model']}")
67print(f"  品質分數: {best_model['Quality Score']:.2%}")
68print(f"  隱私分數: {best_model['Privacy Score']:.2%}")

1生成器 (Generator)          評估器 (Evaluator)          決策 (Decision)
2┌─────────────┐            ┌────────────┐             ┌──────────┐
3│ CTGAN       │──┐         │            │──Quality──→ │          │
4│ TabDDPM     │──┼─synthetic│ SDMetrics  │──Privacy──→ │ GO/NO-GO │
5│ GaussianCopula│──┤  data   │            │──Efficacy─→ │          │
6│ ForestDiffusion│──┘        │            │──Diagnostic→│          │
7└─────────────┘            └────────────┘             └──────────┘
8         ↑                       ↑                         │
9    real_data              metadata                   最佳模型選擇

 1# SDV 生成 + SDMetrics 評估的完整流程
 2from sdv.single_table import CTGANSynthesizer, GaussianCopulaSynthesizer
 3from sdv.metadata import Metadata
 4from sdmetrics.reports.single_table import QualityReport
 5
 6# 1. 定義 metadata
 7metadata = Metadata.detect_from_dataframe(real_data)
 8
 9# 2. 訓練 + 生成
10ctgan = CTGANSynthesizer(metadata)
11ctgan.fit(real_data)
12synthetic_ctgan = ctgan.sample(num_rows=len(real_data))
13
14gc = GaussianCopulaSynthesizer(metadata)
15gc.fit(real_data)
16synthetic_gc = gc.sample(num_rows=len(real_data))
17
18# 3. 用 SDMetrics 比較
19for name, syn in [("CTGAN", synthetic_ctgan), ("GaussianCopula", synthetic_gc)]:
20    qr = QualityReport()
21    qr.generate(real_data, syn, metadata.to_dict())
22    print(f"{name}: {qr.get_score():.2%}")

 1# 與 TabDDPM 整合範例
 2# 1. TabDDPM 生成合成資料（見 08-TabDDPM 教學）
 3# synthetic_tabddpm = tabddpm_generate(real_data, ...)
 4
 5# 2. 直接用 SDMetrics 評估
 6from sdmetrics.reports.single_table import QualityReport
 7qr = QualityReport()
 8qr.generate(real_data, synthetic_tabddpm, metadata)
 9
10# 3. 與 CTGAN 的結果並排比較
11# （SDMetrics 不需要知道資料來源）

 1# synthcity 生成 → SDMetrics 獨立評估
 2from synthcity.plugins import Plugins
 3from sdmetrics.reports.single_table import QualityReport
 4
 5# synthcity 生成
 6syn_model = Plugins().get("ctgan")
 7syn_model.fit(real_data)
 8synthetic_synthcity = syn_model.generate(count=len(real_data)).dataframe()
 9
10# SDMetrics 獨立評估
11qr = QualityReport()
12qr.generate(real_data, synthetic_synthcity, metadata)
13print(f"synthcity CTGAN Quality: {qr.get_score():.2%}")

 1# 將 SDMetrics 結果整合到 MLflow 追蹤
 2import mlflow
 3
 4with mlflow.start_run(run_name="sdg_evaluation"):
 5    qr = QualityReport()
 6    qr.generate(real_data, synthetic_data, metadata)
 7
 8    mlflow.log_metric("sdmetrics_quality_score", qr.get_score())
 9
10    details = qr.get_details("Column Shapes")
11    for _, row in details.iterrows():
12        mlflow.log_metric(f"sdmetrics_{row['Column']}_{row['Metric']}", row['Score'])

 1from sdmetrics.single_column import (
 2    KSComplement,          # 數值分布 (越高越好)
 3    TVComplement,          # 類別分布 (越高越好)
 4    BoundaryAdherence,     # 邊界遵守 (越高越好)
 5    CategoryCoverage,      # 類別覆蓋 (越高越好)
 6    RangeCoverage,         # 範圍覆蓋 (越高越好)
 7    StatisticSimilarity,   # 統計量相似 (越高越好)
 8)
 9
10from sdmetrics.column_pairs.statistical import (
11    CorrelationSimilarity, # 相關性相似 (越高越好)
12    ContingencySimilarity, # 列聯相似 (越高越好)
13)
14
15from sdmetrics.single_table import (
16    NewRowSynthesis,       # 新列比例 (越高越好)
17)
18
19from sdmetrics.single_table.privacy import (
20    DisclosureProtection,      # 洩漏防護 (越高越好)
21    DCRBaselineProtection,     # DCR 基線 (越高越好)
22    DCROverfittingProtection,  # DCR 過擬合 (越高越好)
23)
24
25from sdmetrics.reports.single_table import (
26    QualityReport,         # 一鍵品質報告
27    DiagnosticReport,      # 一鍵診斷報告
28)

 1pharma_metadata = {
 2    "columns": {
 3        "patient_id": {"sdtype": "id"},
 4        "age": {"sdtype": "numerical"},
 5        "weight_kg": {"sdtype": "numerical"},
 6        "sex": {"sdtype": "categorical"},
 7        "diagnosis": {"sdtype": "categorical"},
 8        "treatment_arm": {"sdtype": "categorical"},
 9        "dosage_mg": {"sdtype": "numerical"},
10        "response_rate": {"sdtype": "numerical"},
11        "adverse_event": {"sdtype": "boolean"},
12        "enrollment_date": {"sdtype": "datetime", "datetime_format": "%Y-%m-%d"},
13    },
14    "primary_key": "patient_id"
15}