README.md

metadata

license: apache-2.0
tags:
  - time-series
  - anomaly-detection
  - zero-shot
  - pytorch
  - transformers
library_name: transformers
pipeline_tag: time-series-classification

Time-RCD: Zero-Shot Time Series Anomaly Detection

Time-RCD is a transformer-based model for zero-shot anomaly detection in time series data.

⚠️ IMPORTANT: Custom Model Loading

This model uses a custom architecture not built into transformers.
You MUST include trust_remote_code=True when loading:

# ✅ CORRECT - Will work
from transformers import AutoModel
model = AutoModel.from_pretrained("your-repo/Time-RCD", trust_remote_code=True)

# ❌ WRONG - Will throw KeyError: 'time_rcd'
model = AutoModel.from_pretrained("your-repo/Time-RCD")  # Missing trust_remote_code=True

Quick Start

from transformers import AutoModel, AutoConfig
import numpy as np

# Load model (trust_remote_code=True is REQUIRED!)
model = AutoModel.from_pretrained(
    "thu-sail-lab/Time_RCD",
    trust_remote_code=True
)

# Load processor
from transformers import AutoProcessor
processor = AutoProcessor.from_pretrained(
    "thu-sail-lab/Time_RCD",
    trust_remote_code=True
)

# Prepare data
data = np.random.randn(10000, 1)  # [n_samples, n_features]

# Process data
processed = processor(
    data,
    return_tensors="pt"
)

# Get anomaly scores
outputs = model(**processed)
anomaly_scores = outputs.anomaly_scores.numpy()

Model Details

• Architecture: Transformer encoder with patch embedding
• Parameters: ~5M parameters
• Patch Size: 4
• Hidden Dimension: 512
• Projection Dimension: 256
• Layers: 8 transformer layers
• Attention Heads: 8 heads

Features

✅ Zero-shot detection - No training required
✅ Multi-variate support - Handle multiple features
✅ Flexible windows - Configurable window sizes
✅ Robust normalization - Built-in preprocessing

Usage Examples

Basic Anomaly Detection

from transformers import AutoModel
import numpy as np

# IMPORTANT: trust_remote_code=True is required!
model = AutoModel.from_pretrained("thu-sail-lab/Time_RCD", trust_remote_code=True)

# Your time series (n_samples, n_features)
data = np.random.randn(10000, 1)

# Get anomaly scores using the zero_shot method
scores, logits = model.zero_shot(data)

# Flatten scores from list of batches
import numpy as np
all_scores = np.concatenate(scores, axis=0).flatten()

# Detect anomalies (e.g., top 5%)
threshold = np.percentile(all_scores, 95)
anomalies = all_scores > threshold

With Custom Processing

from transformers import AutoModel
from processing_time_rcd import TimeRCDProcessor
import numpy as np

# IMPORTANT: trust_remote_code=True is required!
model = AutoModel.from_pretrained("thu-sail-lab/Time_RCD", trust_remote_code=True)

# Create and configure processor
processor = TimeRCDProcessor(win_size=5000, normalize=True)

# Process data
data = np.random.randn(10000, 1)
processed = processor(data, return_tensors="pt")

# Get predictions
outputs = model(**processed)
anomaly_scores = outputs.anomaly_scores

Configuration

Parameter	Default	Description
patch_size	4	Patch size for embedding
d_model	512	Model dimension
d_proj	256	Projection dimension
num_layers	8	Transformer layers
num_heads	8	Attention heads
use_rope	True	Rotary position embeddings

Performance

Evaluated on various time series anomaly detection benchmarks.

Limitations

• Requires sufficient data (> window size)
• Performance varies by domain
• High-dimensional data may need preprocessing

Troubleshooting

KeyError: 'time_rcd'

If you see this error:

KeyError: 'time_rcd'
The checkpoint you are trying to load has model type `time_rcd` but Transformers does not recognize this architecture.

Solution: Add trust_remote_code=True to your loading code:

# This will fix the error
model = AutoModel.from_pretrained("your-repo/Time-RCD", trust_remote_code=True)

This is required because Time-RCD is a custom architecture not built into the transformers library. The trust_remote_code=True flag tells transformers to load and execute the custom model code from the repository.

Other Common Issues

Issue: ModuleNotFoundError: No module named 'einops'
Solution: Install einops: pip install einops

Issue: Model runs slowly on CPU
Solution: Move model to GPU: model = model.to('cuda')

Issue: Out of memory errors
Solution: Reduce window size or batch size in the processor:

processor = TimeRCDProcessor(win_size=2000, batch_size=32)

Citation

@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}, 
}

License

Apache 2.0