microsoft/TimeCraft

Official code for TimeCraft: A Time Series Generation Framework for Real-World Applications

📚 什麼是 TimeCraft？

TimeCraft 是一個基於擴散模型的 Microsoft Research 開源框架，用於 合成時間序列生成。它解決了在處理真實世界序列資料時常見的三個實際痛點：

跨領域泛化 – 借由學習的 潛在原型字典 和輕量級 原型指派模組 (PAM)，單一模型僅需少量範例序列即可適應新領域（例如能源、金融、健康）。
自然語言控制 – 自然語言提示（例如「增加夏季的季節性峰值」）透過多代理系統生成模式的文本描述，並與原型提示結合，轉化為條件信號。
目標感知生成 – 合成樣本透過 影響函數引導的擴散 明確優化，以提升下游任務（預測、分類、異常檢測）的表現，即模型會觀察生成點如何改變使用者提供的下游模型的損失，並據此引導生成過程。

該儲存庫包含核心擴散引擎、資料預處理腳本，以及三個可選擴展，推動研究前沿：

CaTSG – 為擴散過程添加因果約束。
OATS – 用於大規模時間序列基礎模型預訓練的線上資料增強引擎。
Diff‑MN – 從不規則觀測中實現連續時間生成。

🚀 主要特性（概覽）

特性	為何重要
帶原型的通用潛在空間	可在任意領域重用少量學習到的時間模式；僅需少量領域特定範例即可創建領域提示。
少樣本領域適應	從電力資料遷移到交通資料時無需完整重訓練——只需輸入少量目標序列即可。
自由文本控制	輸入「具有週季節性上升趨勢」即可，模型將忠實執行，使非專家也能直覺創建合成資料。
目標感知擴散	生成過程由使用者下游模型的梯度引導，因此合成資料不僅真實，而且對您關心的任務真正有用。
模組化擴展（CaTSG、OATS、Diff‑MN）	無需額外程式碼變更即可插入因果推理、基礎模型預訓練的線上增強或連續時間生成。
最尖端成果	相比基線在 MMD/KL 上提升 25 %–53 %，文本到序列一致性更佳，醫療基準上的下游表現可與真實資料持平或超越。

🎯 典型應用場景

場景	TimeCraft 如何幫助
資料稀缺領域（例如罕見病 ICU 記錄）	生成高保真合成序列，保留臨床相關模式，同時保護隱私。
模擬與「如果……會怎樣」分析	使用因果擴展（CaTSG）生成符合已知因果關係的序列，實現安全的風險評估。
預測模型的快速原型設計	使用 OATS 在線生成大量多樣化訓練集，提升大規模時間序列基礎模型的零樣本性能。
領域特定的故事敘述	非技術人員可用自然語言描述期望行為，立即獲得匹配的合成資料。
基準建立	生成跨領域測試套件，用於評估新的預測或異常檢測演算法。

🛠️ 快速入門（快速開始）

# 1. 克隆並建立 conda 環境
git clone https://github.com/microsoft/TimeCraft.git
cd TimeCraft
conda env create -f environment.yml   # 安裝 PyTorch、擴散庫等
conda activate timecraft

# 2. 下載並預處理公開資料集（例如：電力）
python TimeDP/utils/prepare_datasets.py   # 從 Zenodo / GluonTS 下載資料並建立 .npy 窗口

# 3. 訓練核心模型（例如電力，96步窗口）
python main.py --dataset electricity_96 --epochs 200 --batch_size 64

# 4. 使用文本提示生成
python inference.py \
    --prompt "a weekly seasonal pattern with a rising upward trend" \
    --output generated.npy

# 5. （可選）為下游分類器進行目標感知生成
python inference.py \
    --downstream_model path/to/rnn.pt \
    --guidance_set path/to/guidance.pkl \
    --tar_diff True

該儲存庫還包含三個擴展的現成腳本（./CaTSG、./OATS、./Diff-MN）和範例筆記本，完整示範從資料下載到評估的流程。

📂 儲存庫結構（概覽）

TimeCraft/
├─ TimeDP/                 # 核心擴散模型、原型字典、PAM
├─ CaTSG/                  # 因果擴散擴展
├─ OATS/                   # 在線資料增強引擎
├─ Diff-MN/                # 連續時間生成模組
├─ process/                # 文本模板生成與 ts-to-text 腳本
├─ supplementary/          # 詳細文件、訓練/推理命令速查表
├─ environment.yml         # conda 環境定義
├─ main.py                 # 訓練入口點
├─ inference.py            # 生成入口點（支援所有三種輸入）
└─ README.md               # （此檔案）

📖 進一步閱讀與資源

Microsoft Research 博客文章 – 提供跨領域、自然語言控制、目標感知三大支柱的非技術性概述。
ArXiv 論文 – 每個主要組件均有獨立論文（如 CaTSG 2025、OATS 2026、Diff‑MN 2026），在 README 中均有連結。
範例筆記本 – 位於 supplementary/，展示在電力基準和 MIMIC‑III ICU 住院預測任務上的端到端執行。

✅ 總結

如果您需要 合成、可控且任務感知的時間序列資料——無論是用於隱私保護的醫療研究、金融市場模擬，還是建構穩健的預測模型——TimeCraft 提供了一個研究級、基於擴散的工具箱，開箱即用，並可擴展因果或連續時間生成能力。