microsoft/TimeCraft

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

📚 TimeCraft とは何か？

TimeCraft は、拡散モデルに基づく合成時系列データ生成のための Microsoft Research のオープンソースフレームワークです。現実の時系列データを扱う際に頻発する3つの実用的な課題に取り組んでいます：

クロスドメイン一般化 – 学習済みの潜在的プロトタイプ辞書と軽量な Prototype Assignment Module (PAM) を活用することで、エネルギー、金融、医療など新しいドメイン（例：電力、交通）に数例の時系列データでモデルを適応可能にします。
テキストベースの制御性 – 自然言語プロンプト（例：「夏に季節的ピークを増加させる」）を、パターンのテキスト記述を生成するマルチエージェントシステムを介して条件信号に変換し、プロトタイププロンプトと結合します。
ターゲット意識型生成 – ユーザーが提供する下流モデルの損失が生成された点によってどのように変化するかを観察し、その勾配に基づいて生成を調整する インフルエンス関数ガイド付き拡散 を用いて、合成サンプルを下流タスク（予測、分類、異常検出）の改善に向けて明示的に最適化します。

リポジトリには、コアの拡散エンジン、データ前処理スクリプト、および研究の最前線を推進する3つのオプション拡張が含まれています：

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

リポジトリには、3つの拡張機能用の準備済みスクリプト（./CaTSG、./OATS、./Diff-MN）と、データダウンロードから評価までを網羅する例のノートブックも含まれています。

📂 リポジトリ構造（概要）

TimeCraft/
├─ TimeDP/                 # コア拡散モデル、プロトタイプ辞書、PAM
├─ CaTSG/                  # 因果拡散拡張
├─ OATS/                   # オンライン拡張エンジン
├─ Diff-MN/                # 連続時間生成モジュール
├─ process/                # テキストテンプレート生成 & ts-to-text スクリプト
├─ supplementary/          # 詳細ドキュメント、トレーニング/推論コマンドチートシート
├─ environment.yml         # conda環境定義
├─ main.py                 # 学習エントリポイント
├─ inference.py            # 生成エントリポイント（3種類の入力に対応）
└─ README.md               # （このファイル）

📖 詳細リソース

Microsoft Research ブログ記事 – クロスドメイン、テキスト制御、ターゲット意識の3つの柱について、技術的でない概要を提供。
ArXiv論文 – 各主要コンポーネントには独自の論文があります（例：CaTSG 2025、OATS 2026、Diff‑MN 2026）。
例のノートブック – supplementary/ 内にあり、電力ベンチマークおよび MIMIC‑III ICU滞在予測タスクでのエンドツーエンド実行を示します。

✅ まとめ

プライバシー保護された医療研究、金融市場シミュレーション、堅牢な予測モデル構築など、合成的で制御可能かつタスク意識型の時系列データが必要な場合、TimeCraft は出荷時から動作する研究レベルの拡散ベースツールボックスであり、因果的または連続時間生成機能を拡張可能で、即座に利用できます。