T-SYNTH (tsynth-release) 完整教學

Repository: https://github.com/DIDSR/tsynth-release Stars: 6 | Tags: breast-cancer, medical-imaging, synthetic-data 授權: CC0 1.0 Universal (Creative Commons Zero; 公眾領域貢獻) 主要語言: Jupyter Notebook / Python 資料集: https://huggingface.co/datasets/didsr/tsynth 論文: https://arxiv.org/abs/2507.04038 (MICCAI Open Data 2025) FDA RST 編號: RST26AI04.01

2. 核心架構

2.1 系統整體架構


flowchart TB
    subgraph VICTRE ["VICTRE Toolkit (上游)"]
        A1[虛擬乳房模型
KB Phantom] --> A2[Monte Carlo
X-ray 模擬]
        A2 --> A3[原始 DBT
3D Volume]
    end

    subgraph TSYNTH ["T-SYNTH Pipeline"]
        A3 --> B1[C-View 合成
DBT → 2D]
        A3 --> B2[像素級分割
Segmentation]
        B1 --> B3[HuggingFace
Dataset 發佈]
        B2 --> B3
        B3 --> C1[下載腳本
download_data.py]
    end

    subgraph TRAIN ["訓練與評估"]
        C1 --> D1[YAML 配置
real / synth / mixed]
        D1 --> D2[custom_datasets.py
EmbedDataset + DbtSynthDataset]
        D2 --> D3[train_detector.py
Faster R-CNN
ResNet-50-FPN]
        D3 --> D4[evaluate_detectors.py
FROC / AUC]
        D4 --> D5[Jupyter Notebooks
視覺化 + 分析]
    end

    subgraph DATA ["外部真實資料"]
        E1[EMBED Dataset
Emory Breast Imaging
AWS Open Data] --> D2
    end

    style VICTRE fill:#e8f4fd,stroke:#1e88e5
    style TSYNTH fill:#fff3e0,stroke:#f57c00
    style TRAIN fill:#e8f5e9,stroke:#43a047
    style DATA fill:#fce4ec,stroke:#e53935

2.2 實驗配置對應圖


flowchart LR
    subgraph EXP ["實驗類型"]
        direction TB
        R[Real Only
20%~100%]
        RS[Real + Synth
混合比例]
        S[Synth Only]
        D[Diffusion
比較實驗]
    end

    subgraph CFG ["YAML 配置"]
        direction TB
        C1["cfg/train/real*.yaml"]
        C2["cfg/train/real*_and_synth*.yaml"]
        C3["cfg/train/synth.yaml"]
        C4["cfg/train/genAI/*.yaml"]
    end

    subgraph MOD ["模態"]
        direction TB
        M1["DBT C-View"]
        M2["DM 2D"]
    end

    R --> C1
    RS --> C2
    S --> C3
    D --> C4
    C1 & C2 & C3 & C4 --> M1
    C1 & C2 & C3 --> M2

    style EXP fill:#e3f2fd,stroke:#1565c0
    style CFG fill:#fff8e1,stroke:#f9a825
    style MOD fill:#f3e5f5,stroke:#8e24aa

2.3 檔案結構

 1tsynth-release/
 2├── LICENSE                          # CC0 1.0
 3├── README.md
 4├── images/
 5│   ├── poster.pdf                   # MICCAI 海報
 6│   └── summary_figure.png
 7└── code/
 8    ├── README.md                    # 安裝與使用說明
 9    ├── requirements.txt             # Python 套件依賴
10    ├── config_global.py             # 全域路徑設定 (dir_global)
11    ├── custom_datasets.py           # Dataset 類別 (EmbedDataset, DbtSynthDataset)
12    ├── train_detector.py            # 訓練 Faster R-CNN
13    ├── evaluate_detectors.py        # 模型推論與評估
14    ├── cfg/                         # YAML 實驗配置
15    │   ├── train/                   # 訓練配置 (25+ 種組合)
16    │   │   ├── real.yaml
17    │   │   ├── synth.yaml
18    │   │   ├── real_and_synth.yaml
19    │   │   ├── real100_and_synth*.yaml
20    │   │   └── genAI/              # Diffusion 比較實驗
21    │   ├── val/                     # 驗證配置
22    │   ├── test/                    # 測試配置
23    │   └── DM/                      # Digital Mammography 專用配置
24    ├── download_scripts/
25    │   ├── download_data.py         # 從 HuggingFace 下載合成資料
26    │   ├── download_embed_metadata.py
27    │   ├── download_models.py       # 下載預訓練模型
28    │   ├── download_results.py      # 下載評估結果
29    │   └── download_volumes.py      # 下載原始 DBT volumes
30    ├── notebooks/                   # 分析與視覺化
31    │   ├── create_cview.ipynb       # DBT → C-View 轉換
32    │   ├── synthetic_detection.ipynb
33    │   ├── data_augmentation_experiments.ipynb
34    │   ├── diffusion_experiments.ipynb
35    │   ├── tsynth_breast_density.ipynb
36    │   ├── tsynth_lesion_density.ipynb
37    │   ├── tsynth_lesion_size.ipynb
38    │   └── comparison_of_FROC_AUC.ipynb
39    └── utils/
40        ├── duke_dbt_data.py         # DICOM 讀取工具
41        ├── eval_utils.py            # FROC 計算工具
42        └── model_utils.py           # Faster R-CNN 建構

3. 安裝與設定

3.1 環境需求

需求	說明
Python	3.9
GPU	CUDA 11.8 (NVIDIA GPU 強烈建議)
磁碟空間	C-View 資料 ~數十 GB；完整 DBT volumes 需 PrecisionFDA 下載，更大
HuggingFace 帳號	下載資料需要 token
套件	PyTorch 2.3.1+cu118, torchvision 0.18.1, MONAI 1.3.1, pydicom 等

3.2 安裝步驟

 1# 1. Clone repository
 2git clone https://github.com/DIDSR/tsynth-release.git
 3cd tsynth-release
 4
 5# 2. 建立 conda 環境（官方建議 Python 3.9）
 6conda create -n tsynth python=3.9
 7conda activate tsynth
 8
 9# 3. 安裝套件依賴
10pip install -r code/requirements.txt
11
12# 4. 設定 HuggingFace token（下載資料需要）
13huggingface-cli login
14# 貼上你的 HuggingFace Access Token
15
16# 5. （可選）手動下載 pretrained COCO 權重
17#    如果自動下載失敗才需要
18mkdir -p ~/.cache/torch/hub/checkpoints
19cd ~/.cache/torch/hub/checkpoints
20wget https://download.pytorch.org/models/fasterrcnn_resnet50_fpn_coco-258fb6c6.pth
21wget https://download.pytorch.org/models/resnet50-0676ba61.pth

3.3 關鍵配置：config_global.py

1# 修改此路徑為你的本地資料目錄
2dir_global = '/path/to/your/tsynth_data/'

此路徑是所有下載腳本與訓練/評估腳本的全域根目錄。下載的資料會存放在 {dir_global}/data/ 下。

3.4 使用 uv 替代方案（建議）

1# 若偏好 uv 管理環境
2uv venv --python 3.9 .venv
3source .venv/bin/activate
4uv pip install -r code/requirements.txt

4. 使用方式與程式碼範例

範例 1：下載 T-SYNTH 合成資料並視覺化

此範例展示如何下載特定參數組合的合成資料，以及如何下載全部資料。

 1# 進入 code 目錄
 2cd tsynth-release/code
 3
 4# --- 下載特定參數組合 ---
 5# 下載 dense 乳房、5.0mm 病灶、密度 1.1 的合成影像
 6python -u download_scripts/download_data.py \
 7    --density dense \
 8    --size 5.0 \
 9    --lesionDensity 1.1
10
11# --- 下載全部 T-SYNTH C-View 資料 ---
12python -u download_scripts/download_data.py --all
13
14# --- 下載 EMBED（真實資料）metadata ---
15python -u download_scripts/download_embed_metadata.py
16
17# --- 視覺化合成資料 ---
18# 啟動 Jupyter 檢視不同乳房密度的合成影像
19jupyter notebook notebooks/tsynth_breast_density.ipynb
20
21# 檢視不同病灶密度
22jupyter notebook notebooks/tsynth_lesion_density.ipynb
23
24# 檢視不同病灶大小
25jupyter notebook notebooks/tsynth_lesion_size.ipynb

下載腳本工作原理：download_data.py 會遍歷所有 (breast_density, lesion_size, lesion_density) 參數組合，從 HuggingFace Hub (didsr/tsynth) 下載對應的 ZIP 壓縮檔，解壓縮後存放至 {dir_global}/data/cview/output_cview_det_Victre/ 目錄結構。

範例 2：訓練 Faster R-CNN 偵測模型（真實 + 合成混合資料）

此範例展示如何用不同真實/合成資料比例訓練 Lesion Detection (病灶偵測) 模型。

 1cd tsynth-release/code
 2
 3# 取得全域資料目錄
 4DIR_GLOBAL=$(python3 -c "import config_global as cg; print(cg.dir_global)")
 5
 6# --- 實驗 1：100% 真實 + 100% 合成混合訓練 ---
 7EXPERIMENT_NAME=real_and_synth
 8FOLDER_NAME=DBT/trained_on_real_and_synth
 9
10for run_id in 1 2 3 4 5; do
11    MODEL_SAVEDIR="${DIR_GLOBAL}/my_models/${FOLDER_NAME}/${run_id}/"
12    mkdir -p "$MODEL_SAVEDIR"
13    python train_detector.py \
14        --experiment $EXPERIMENT_NAME \
15        --save_name "$MODEL_SAVEDIR" \
16        --training_steps 3000 \
17        --lr 0.0001 \
18        --val_every_n_step 100
19done
20
21# --- 實驗 2：60% 真實 + 40% 合成（替換實驗）---
22EXPERIMENT_NAME=real60_and_synth40
23FOLDER_NAME=DBT/repl/real60_and_synth40
24
25for run_id in 1 2 3 4 5; do
26    MODEL_SAVEDIR="${DIR_GLOBAL}/my_models/${FOLDER_NAME}/${run_id}/"
27    mkdir -p "$MODEL_SAVEDIR"
28    python train_detector.py \
29        --experiment $EXPERIMENT_NAME \
30        --save_name "$MODEL_SAVEDIR"
31done
32
33# --- 實驗 3：純合成資料訓練 ---
34python train_detector.py \
35    --experiment synth \
36    --save_name "${DIR_GLOBAL}/my_models/DBT/synth/1/"

YAML 配置解析（real_and_synth.yaml）：

 1# 三個 dataset 同時載入：
 2# 1. EMBED 真實正例（有病灶的乳房影像）
 3# 2. EMBED 真實負例（無病灶的乳房影像）
 4# 3. T-SYNTH 合成資料（多密度/大小組合，C-View 模式）
 5dataset_names_list:
 6  - EmbedDataset       # 真實正例
 7  - EmbedDataset       # 真實負例
 8  - DbtSynthDataset    # 合成資料
 9
10batch_size_list: [8, 8, 10]  # 各 dataset 的 batch size

範例 3：評估模型效能與結果視覺化

 1cd tsynth-release/code
 2
 3DIR_GLOBAL=$(python3 -c "import config_global as cg; print(cg.dir_global)")
 4
 5# --- 方法 A：下載預訓練模型與結果（快速複現）---
 6python -u download_scripts/download_models.py --all
 7python -u download_scripts/download_results.py --all
 8
 9# --- 方法 B：自行跑評估 ---
10EXPERIMENT_FOLDER_NAME=DBT/trained_on_real_and_synth
11TEST_CONFIG='cfg/test/real.yaml'
12TESTRESULTS="${DIR_GLOBAL}/my_results/${EXPERIMENT_FOLDER_NAME}"
13
14for run_id in 1 2 3 4 5; do
15    MODEL="${DIR_GLOBAL}/data/pretrained_models/${EXPERIMENT_FOLDER_NAME}/${run_id}/best_ckpt.pth"
16    python evaluate_detectors.py \
17        --config $TEST_CONFIG \
18        --model_path "$MODEL" \
19        --save_name "${TESTRESULTS}/${run_id}/results.csv" \
20        --non_max_suppression_threshold 0.25
21done
22
23# --- 視覺化結果（Jupyter Notebooks）---
24# Fig. 4: 純合成資料偵測結果
25jupyter notebook notebooks/synthetic_detection.ipynb
26
27# Fig. 5: 真實:合成比例消融實驗
28jupyter notebook notebooks/data_augmentation_experiments.ipynb
29
30# Fig. 6: T-SYNTH vs Diffusion 比較
31jupyter notebook notebooks/diffusion_experiments.ipynb
32
33# Fig. 9: DM vs DBT 全 EMBED 評估
34jupyter notebook notebooks/dbt_and_dm_all_images_results.ipynb
35
36# Fig. 10: FROC AUC 比較
37jupyter notebook notebooks/comparison_of_FROC_AUC.ipynb

評估指標說明：

指標	說明
FROC (Free-response ROC; 自由反應操作特性曲線)	醫學影像偵測標準指標，衡量 sensitivity vs. 每影像假陽性數
AUC-FROC	FROC 曲線下面積，越高越好
IoU (Intersection over Union; 交集比聯集)	預測框與真實框的重疊度，閾值預設 0.5
NMS (Non-Max Suppression; 非極大值抑制)	移除重疊預測框，閾值預設 0.25

5. 在醫療結構化資料合成生態系中的定位

5.1 Domain 1-D：臨床試驗資料合成子域

T-SYNTH 隸屬 Bio-SDG 生態系 Domain 1「醫療結構化資料合成」的 Sub-domain D：Clinical Trial Data (臨床試驗資料)，與以下工具同屬：

工具	類型	T-SYNTH 的關係
VICTRE	上游基礎工具	T-SYNTH 的影像來源，Monte Carlo X-ray 模擬引擎
M-SYNTH	姊妹資料集	合成數位乳房攝影 (DM)，T-SYNTH 為 DBT 版
TrialSynth	臨床試驗文本合成	不同層級——文本 vs. 影像
Simulants	模擬人物生成	人口統計層級 vs. 影像層級

5.2 與其他子域的對比

 1Domain 1 醫療結構化資料合成
 2├── A. Patient Simulation (Synthea)
 3│   └── 全患者生命週期模擬 → 結構化 EHR
 4├── B. Privacy-Preserving SDG (DP tools)
 5│   └── 差分隱私保護 → 表格/時序資料
 6├── C. Medical Tabular SDG (synthcity, COR-GAN)
 7│   └── EHR 表格資料生成
 8├── D. Clinical Trial Data ← T-SYNTH 在此
 9│   └── 虛擬臨床試驗影像 + 偵測模型評估
10├── E. Medical Time Series (TemporAI)
11│   └── 時序臨床資料
12└── F. Specialized (SDM-TIB)
13    └── 特定疾病資料

5.3 獨特價值

T-SYNTH 的特殊定位在於它是極少數由 FDA 官方 CDRH 發佈、被列入 Catalog of Regulatory Science Tools (RST; 法規科學工具目錄) 的合成資料工具。這意味著：

法規先例 (Regulatory Precedent)：FDA 官方認可合成資料用於醫療器械評估的範式
IVCTE (In Silico Virtual Clinical Trial Evidence; 電腦模擬虛擬臨床試驗證據)：是虛擬臨床試驗 (Virtual Clinical Trial) 概念的具體實踐
可複現基準 (Reproducible Benchmark)：提供標準化的偵測模型比較基準

6. 與其他工具的整合

6.1 與 VICTRE 的整合

T-SYNTH 的影像源自 VICTRE 模擬。若需自行生成新的合成組合（非使用現有資料集），須先安裝 VICTRE toolkit：

1# VICTRE 安裝（上游依賴）
2# 參見 https://github.com/DIDSR/VICTRE
3git clone https://github.com/DIDSR/VICTRE.git
4
5# 生成虛擬乳房 phantom → X-ray 模擬 → 得到 DBT volume
6# 然後使用 T-SYNTH 的 create_cview.ipynb 將 volume 轉為 C-View
7python -u download_scripts/download_volumes.py  # 下載範例 volume
8jupyter notebook notebooks/create_cview.ipynb    # DBT → C-View 轉換

6.2 與 M-SYNTH 的整合

M-SYNTH 是 T-SYNTH 的姊妹專案，專注 DM (2D) 合成影像。兩者可合併使用以同時評估 2D/3D 偵測效能：

1# 下載 M-SYNTH DM 資料
2# 參見 https://github.com/DIDSR/msynth-release
3git clone https://github.com/DIDSR/msynth-release.git
4# 按其文件下載 DM 合成影像，放置於同一 dir_global 結構下

6.3 與 EMBED 真實資料的整合

T-SYNTH 的訓練流程高度依賴 EMBED (Emory Breast Imaging Dataset; Emory 乳房影像資料集) 作為真實資料來源：

1# 下載 EMBED metadata
2python -u download_scripts/download_embed_metadata.py
3
4# EMBED 完整 DICOM 影像需從 AWS Open Data 下載
5# https://registry.opendata.aws/emory-breast-imaging-dataset-embed/

6.4 與 PrecisionFDA 的整合

完整 DBT 3D Volumes 托管在 FDA 的 PrecisionFDA 平台：

 1# 安裝 PrecisionFDA CLI
 2wget https://pfda-production-static-files.s3.amazonaws.com/cli/pfda-linux-2.10.3.tar.gz
 3tar zxvf pfda-linux-2.10.3.tar.gz
 4
 5# 登入
 6KEY=YOUR-PFDA-KEY
 7pfda ls -key $KEY
 8
 9# 下載特定組合的 volume（例：lesion density 1.0, fatty, size 7.0）
10pfda -folder-id 8726058 -recursive -public

6.5 潛在延伸整合

整合對象	整合方式	用途
Synthea	Synthea 生成合成患者 EHR → T-SYNTH 生成對應影像	建立完整合成患者（結構化 + 影像）
synthcity	T-SYNTH 影像 metadata 餵入 synthcity 生成更多表格資料	擴增影像配對的臨床參數
MONAI	T-SYNTH 已依賴 MONAI 1.3.1	進階醫學影像處理與訓練框架
COR-GAN / synthEHRella	合成 EHR 搭配合成影像	多模態合成資料完整性驗證

7. 優缺點分析

7.1 優點

面向	說明
FDA 官方背書	列入 RST 目錄，具法規科學先例價值；任何涉及 AI 醫療器械的送審都可參考此範式
CC0 授權	完全公眾領域，無商業使用限制；適合學術與產業研究
完整實驗框架	25+ 種實驗配置覆蓋各種 real:synth 比例消融實驗，可直接複現論文結果
知識驅動合成 (Knowledge-Based)	基於物理模擬而非純統計生成，影像具有物理真實性
配對標註	像素級分割 + 邊界框 + 多參數元資料，標註品質高且無人工標註誤差
模態覆蓋	同時涵蓋 DM (2D) 與 DBT C-View (3D)，支援跨模態研究
與 Diffusion 模型比較	內建 T-SYNTH vs. Diffusion 基準，為 GenAI 在醫學影像的應用提供客觀對照

7.2 缺點

面向	說明
僅限乳房影像	聚焦 DBT/DM，不適用於其他器官或影像模態（CT, MRI 等）
非結構化臨床資料	純影像資料集，不含 CDISC SDTM/ADaM 格式的結構化臨床試驗數據
GPU 硬需求	訓練 Faster R-CNN 需要 NVIDIA GPU + CUDA 11.8，無 CPU-only 路徑
大資料量	完整下載需數十 GB（C-View），原始 volumes 更大；需要充足儲存空間
Conda 鎖定	官方僅提供 conda + pip 安裝路徑，requirements.txt 鎖死版本（含 CUDA-specific wheels）
EMBED 外部依賴	真實資料對照組需從 AWS Open Data 另行下載 EMBED，增加環境設定複雜度
Python 3.9 限制	官方指定 Python 3.9，較新版本的相容性未經驗證
非 MDDT 資格	雖列入 RST 但尚未取得 MDDT (Medical Device Development Tool; 醫療器械開發工具) 認證，送審時仍需個案說明適用性

7.3 對 Pre-IND 藥物開發的適用性評估

評估面向	評分	說明
直接適用性	低	T-SYNTH 專注乳房影像偵測，非藥物 pre-IND 申請的核心需求
方法論參考	高	FDA 官方認可的合成資料評估框架 → 可作為「合成資料用於 regulatory submission」的方法論引用
技術移轉潛力	中	VICTRE 的 Monte Carlo 模擬概念可延伸至其他影像導向的臨床試驗設計
Blue Ocean 啟發	高	合成臨床試驗影像 + AI 器械送審 → 尚無等效工具涵蓋 CDISC SDTM/ADaM 格式的合成結構化試驗資料

7.4 總結

T-SYNTH 是 FDA 推動虛擬臨床試驗 (Virtual Clinical Trial; VCT) 概念的旗艦資料集，對於理解 FDA 如何看待合成資料在法規科學中的角色具有重要參考價值。雖然其應用範圍限於乳房影像偵測，但其「知識驅動合成 + 系統化消融實驗 + 與 GenAI 對比」的方法論框架，對任何涉及合成資料的醫療 AI 開發都有借鏡意義。

產生時間: 2026-06-11 資料來源: GitHub DIDSR/tsynth-release, HuggingFace didsr/tsynth, arXiv 2507.04038 生態系定位: Bio-SDG Domain 1-D (Clinical Trial Data) — 第 14 號教學

T-SYNTH (tsynth-release) 完整教學

Contents

T-SYNTH (tsynth-release) 完整教學

2. 核心架構

2.1 系統整體架構

2.2 實驗配置對應圖

2.3 檔案結構

3. 安裝與設定

3.1 環境需求

3.2 安裝步驟

3.3 關鍵配置：config_global.py

3.4 使用 uv 替代方案（建議）

4. 使用方式與程式碼範例

範例 1：下載 T-SYNTH 合成資料並視覺化

範例 2：訓練 Faster R-CNN 偵測模型（真實 + 合成混合資料）

範例 3：評估模型效能與結果視覺化

5. 在醫療結構化資料合成生態系中的定位

5.1 Domain 1-D：臨床試驗資料合成子域

5.2 與其他子域的對比

5.3 獨特價值

6. 與其他工具的整合

6.1 與 VICTRE 的整合

6.2 與 M-SYNTH 的整合

6.3 與 EMBED 真實資料的整合

6.4 與 PrecisionFDA 的整合

6.5 潛在延伸整合

7. 優缺點分析

7.1 優點

7.2 缺點

7.3 對 Pre-IND 藥物開發的適用性評估

7.4 總結

Comments

T-SYNTH (tsynth-release) 完整教學

Contents

T-SYNTH (tsynth-release) 完整教學

2. 核心架構

2.1 系統整體架構

2.2 實驗配置對應圖

2.3 檔案結構

3. 安裝與設定

3.1 環境需求

3.2 安裝步驟

3.3 關鍵配置：config_global.py

3.4 使用 uv 替代方案（建議）

4. 使用方式與程式碼範例

範例 1：下載 T-SYNTH 合成資料並視覺化

範例 2：訓練 Faster R-CNN 偵測模型（真實 + 合成混合資料）

範例 3：評估模型效能與結果視覺化

5. 在醫療結構化資料合成生態系中的定位

5.1 Domain 1-D：臨床試驗資料合成子域

5.2 與其他子域的對比

5.3 獨特價值

6. 與其他工具的整合

6.1 與 VICTRE 的整合

6.2 與 M-SYNTH 的整合

6.3 與 EMBED 真實資料的整合

6.4 與 PrecisionFDA 的整合

6.5 潛在延伸整合

7. 優缺點分析

7.1 優點

7.2 缺點

7.3 對 Pre-IND 藥物開發的適用性評估

7.4 總結

Related Posts

Comments