Official model repository. This Hugging Face repository hosts the checkpoints used by the official Time-RCD GitHub project, as well as a Transformers-compatible model implementation. The recommended inference API is TimeRCDDetector below.

Time-RCD

Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy

📰 News

• 2026.05: Time-RCD has been accepted by ICML 2026. We also release the pre-trained dataset generation code and hyperparameters.

• 2026.04: With a new dataset and new checkpoints, Time-RCD achieves better results. The univariate setting improves VUS-PR by an absolute 6.7 points, and the multivariate setting improves VUS-PR by an absolute 4.5 points.

🔍 About

Time-RCD is a zero-shot foundation model for time series anomaly detection. Given a univariate or multivariate series, it outputs a per-timestep anomaly score without any task-specific training on your data.

🐘 On the TSB-AD benchmark, Time-RCD achieves a Univariate VUS-PR of 0.52 and a Multivariate VUS-PR of 0.32.

🌟 Live Demo on Hugging Face Spaces — try Time-RCD interactively in your browser.

This repository contains:

1. time_rcd/ — a lightweight Python API for inference on your own data

For a step-by-step guide, see Tutorial.md.

🎯 Use on Your Own Data

Installation

conda create -n Time-RCD python=3.10
conda activate Time-RCD

git clone https://github.com/thu-sail-lab/Time-RCD.git
cd Time-RCD
pip install .

When working from a local clone of this Hugging Face repository, install the same official inference package with:

pip install .

Python API (recommended)

Checkpoints are downloaded from Hugging Face automatically on first use and cached locally. For servers in China, set HF_ENDPOINT=https://hf-mirror.com before running the examples or loading a checkpoint.

export HF_ENDPOINT=https://hf-mirror.com

import numpy as np
from time_rcd import TimeRCDDetector

data = np.load("my_series.npy")  # shape (T,) or (T, C)

detector = TimeRCDDetector.from_pretrained(variant="uni")   # or "multi"
scores = detector.predict(data)                             # shape (T,)

Multivariate series — use variant="multi" when C > 1:

detector = TimeRCDDetector.from_pretrained(variant="multi")
scores = detector.predict(multivariate_data)  # shape (T, C) -> scores (T,)

Local checkpoint — if you already downloaded weights:

detector = TimeRCDDetector.from_local(
    "best_model/pretrain_checkpoint_best_uni.pth",
    variant="uni",
)

Quick example

python examples/quickstart.py

See Tutorial.md for CSV loading, hyperparameters, and more examples.

Transformers API

This repository also supports Transformers-based inference. The official TimeRCDDetector API above is recommended, especially for multivariate data. For univariate data, the following loads the same official uni checkpoint:

import numpy as np
from transformers import AutoModel

model = AutoModel.from_pretrained(
    "thu-sail-lab/Time-RCD",
    trust_remote_code=True,
).eval()

data = np.load("my_series.npy")  # shape: (T,)
score_chunks, _ = model.zero_shot(data)
scores = np.concatenate([chunk.reshape(-1) for chunk in score_chunks])[: len(data)]

zero_shot() applies the same global normalization and windowing semantics as the official TimeRCDDetector inference API. The published Transformers configuration is univariate; use TimeRCDDetector.from_pretrained(variant="multi") for multivariate inference.

📁 Project Structure

.
├── time_rcd/              # User-facing inference API
│   ├── detector.py        # TimeRCDDetector
│   └── _core/             # Time-RCD inference model implementation
├── examples/
│   └── quickstart.py      # Minimal inference example
├── Tutorial.md            # Guide for your own data
├── pyproject.toml         # Package metadata and dependencies
├── zero-shot.png          # Model overview
└── README.md

TSB-AD benchmark code

The original benchmark integration, evaluation scripts, and baseline implementations are maintained in the tsb-ad-integration branch. For the lightweight zero-shot inference API, use the main branch.

🔗 Citation

If you find this work useful, please cite our paper:

@misc{lan2025foundationmodelszeroshottime,
      title={Towards Foundation Models for Zero-Shot Time Series Anomaly Detection: Leveraging Synthetic Data and Relative Context Discrepancy}, 
      author={Tian Lan and Hao Duong Le and Jinbo Li and Wenjun He and Meng Wang and Chenghao Liu and Chen Zhang},
      year={2025},
      eprint={2509.21190},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2509.21190}, 
}