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 提供了一个研究级、基于扩散的工具箱，开箱即用，并可扩展因果或连续时间生成能力。