microsoft/TimeCraft

📚 What is TimeCraft?

TimeCraft is a Microsoft‑Research open‑source framework for synthetic time‑series generation built on diffusion models. It tackles three practical pain points that often arise when working with real‑world sequential data:

1. Cross‑domain generalisation – a single model can be adapted to new domains (e.g., energy, finance, health) with only a few example series, thanks to a learned latent prototype dictionary and a lightweight Prototype Assignment Module (PAM).
2. Text‑based controllability – natural‑language prompts (e.g., “increase seasonal spikes in summer”) are turned into conditioning signals via a multi‑agent system that generates textual descriptions of patterns and couples them with the prototype prompts.
3. Target‑aware generation – synthetic samples are explicitly optimised to improve a downstream task (forecasting, classification, anomaly detection) by using influence‑function‑guided diffusion, i.e., the model looks at how a generated point would change the loss of a user‑provided downstream model and steers generation accordingly.

The repo bundles the core diffusion engine, data‑pre‑processing scripts, and three optional extensions that push the research frontier:

• CaTSG – adds causal constraints to the diffusion process.
• OATS – an online data‑augmentation engine for training large‑scale Time‑Series Foundation Models.
• Diff‑MN – continuous‑time generation from irregularly sampled observations.

---

🚀 Key Features (at a glance)

Feature	Why it matters
Universal latent space with prototypes	Re‑use a small set of learned temporal patterns across any domain; only a few domain‑specific examples are needed to create a domain prompt.
Few‑shot domain adaptation	No full retraining when you move from electricity to traffic data – just feed a handful of target series.
Free‑form text control	Write “a rising trend with weekly seasonality” and the model will honour it, making synthetic data creation intuitive for non‑experts.
Target‑aware diffusion	Generation is guided by gradients from your own downstream model, so the synthetic data is useful for the task you care about, not just realistic.
Modular extensions (CaTSG, OATS, Diff‑MN)	Plug‑in causal reasoning, online augmentation for foundation‑model pre‑training, or continuous‑time generation without extra code changes.
State‑of‑the‑art results	Reported improvements of 25 %–53 % on MMD/KL vs. baselines, better text‑to‑series consistency, and downstream performance that can match or exceed real data on medical benchmarks.

---

🎯 Typical Use‑Cases

Scenario	How TimeCraft helps
Data‑scarce domains (e.g., rare disease ICU records)	Generate high‑fidelity synthetic series that preserve clinically relevant patterns while respecting privacy.
Simulation & “what‑if” analysis	Use the causal extension (CaTSG) to produce series that obey known cause‑effect relations, enabling safe risk evaluation.
Rapid prototyping of forecasting models	Produce large, diverse training sets on‑the‑fly with OATS, improving zero‑shot performance of large time‑series foundation models.
Domain‑specific storytelling	Non‑technical stakeholders can describe desired behaviours in plain English and obtain matching synthetic data instantly.
Benchmark creation	Generate cross‑domain test suites for evaluating new forecasting or anomaly‑detection algorithms.

---

🛠️ Getting Started (quick‑start)

# 1. Clone and create the conda environment
git clone https://github.com/microsoft/TimeCraft.git
cd TimeCraft
conda env create -f environment.yml   # installs PyTorch, diffusion libs, etc.
conda activate timecraft

# 2. Download and preprocess a public dataset (e.g., electricity)
python TimeDP/utils/prepare_datasets.py   # pulls data from Zenodo / GluonTS and creates .npy windows

# 3. Train the core model (example for electricity, 96‑step windows)
python main.py --dataset electricity_96 --epochs 200 --batch_size 64

# 4. Generate with a text prompt
python inference.py \
    --prompt "a weekly seasonal pattern with a rising upward trend" \
    --output generated.npy

# 5. (Optional) Target‑aware generation for a downstream classifier
python inference.py \
    --downstream_model path/to/rnn.pt \
    --guidance_set path/to/guidance.pkl \
    --tar_diff True

The repository also contains ready‑made scripts for the three extensions (./CaTSG, ./OATS, ./Diff-MN) and example notebooks that walk through the full pipeline from data download to evaluation.

---

📂 Repository Layout (high‑level)

TimeCraft/
├─ TimeDP/                 # Core diffusion model, prototype dictionary, PAM
├─ CaTSG/                  # Causal diffusion extension
├─ OATS/                   # Online augmentation engine
├─ Diff-MN/                # Continuous‑time generation module
├─ process/                # Text‑template generation & ts‑to‑text scripts
├─ supplementary/          # Detailed docs, training/inference command cheatsheets
├─ environment.yml         # Conda env definition
├─ main.py                 # Training entry point
├─ inference.py            # Generation entry point (supports all three inputs)
└─ README.md               # (this file)

---

📖 Further Reading & Resources

• Microsoft Research blog posts – give a non‑technical overview of the three pillars (cross‑domain, text control, target‑aware).
• ArXiv papers – each major component has its own paper (e.g., CaTSG 2025, OATS 2026, Diff‑MN 2026) linked throughout the README.
• Example notebooks – located under supplementary/, they show end‑to‑end runs on the electricity benchmark and on the MIMIC‑III ICU‑stay prediction task.

---

✅ Bottom Line

If you need synthetic, controllable, and task‑aware time‑series data—whether for privacy‑preserving health research, financial market simulation, or building robust forecasting models—TimeCraft provides a research‑grade, diffusion‑based toolbox that works out‑of‑the‑box and can be extended with causal or continuous‑time capabilities.