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 는 출시 직후 바로 사용 가능한 연구 수준의 확산 기반 도구 상자이며, 인과성 또는 연속 시간 생성 기능을 확장 가능합니다.