README.md

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Models
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

Adapting existing outlier detection & prediction methods into a time series outlier detection system is not a simple task. Good news: OATS has done the heavy lifting for you!

We present a straight-forward interface for popular, state-of-the-art detection methods to assist you in your experiments. In addition to the models, we also present different options when it comes to selecting a final threshold for predictions.

OATS seamlessly supports both univariate and multivariate time series regardless of the model choice and guarantees the same output shape, enabling a modular approach to time series anoamly detection.

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

>=3.9, <3.13 (recommended) or

Installation

Recommended: uv (Fast & Modern)

The fastest way to get started with OATS:

1. Install uv if you haven't already:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and install:

   git clone https://github.com/georgian-io/pyoats.git && cd pyoats
   uv sync --all-extras
   

3. Run tests or use the package:

   uv run pytest
   # or
   uv run python your_script.py
   

Alternative: Docker (For GPU or Isolated Environments)

Perfect for GPU acceleration or containerized deployments:

1. Build the image:

   git clone https://github.com/georgian-io/pyoats.git && cd pyoats
   docker build -t pyoats .
   

2. Run container:

   # CPU only
   docker run -it pyoats
   
   # With NVIDIA GPU support
   docker run -it --gpus all pyoats
   

(back to top)

Usage

Quick Start

For a quick start, please refer to our blog or copy our Colab notebook!

Getting Anomaly Score

from oats.models import NHiTSModel

model = NHiTSModel(window=20, use_gpu=True)
model.fit(train)
scores = model.get_scores(test)

Getting Threshold

from oats.threshold import QuantileThreshold

t = QuantileThreshold()
threshold = t.get_threshold(scores, 0.99)
anom = scores > threshold

For more examples, please refer to the Documentation

(back to top)

Models

For more details about the individual models, please refer to the Documentation or this blog for deeper explanation.

Model	Type	Multivariate Support*	Requires Fitting	DL Framework Dependency	Paper	Reference Model
ARIMA	Predictive	⚠️	✅			statsmodels.ARIMA
FluxEV	Predictive	⚠️	✅		📝
LightGBM	Predictive	⚠️	✅			darts.LightGBM
Moving Average	Predictive	⚠️
N-BEATS	Predictive	✅	✅		📝	darts.NBEATS
N-HiTS	Predictive	✅	✅		📝	darts.NHiTS
RandomForest	Predictive	⚠️	✅			darts.RandomForest
Regression	Predictive	⚠️	✅			darts.Regression
RNN	Predictive	✅	✅			darts.RNN
Temporal Convolution Network	Predictive	✅	✅		📝	darts.TCN
Temporal Fusion Transformers	Predictive	✅	✅		📝	darts.TFT
Transformer	Predictive	✅	✅		📝	darts.Transformer
Isolation Forest	Distance-Based	✅	✅			pyod.IForest
Matrix Profile	Distance-Based	✅			📝	stumpy
TranAD	Reconstruction-Based	✅	✅		📝	tranad
Variational Autoencoder	Reconstruction-Based	✅	✅		📝	pyod.VAE
Quantile	Rule-Based	⚠️

* For models with ⚠️, score calculation is done separately along each column. This implicitly assumes independence of covariates, which means that the resultant anomaly scores do not take into account of inter-variable dependency structures.

(back to top)

Roadmap

• Automatic hyper-parameter tuning
• More examples
• More preprocessors
• More models from pyod

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/amazing_feature)
3. Commit your Changes (git commit -m 'Add some amazing_feature')
4. Push to the Branch (git push origin feature/amazing_feature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

Benjamin Ye

Project Link: https://github.com/georgian-io/oats

(back to top)

Acknowledgments

I would like to thank my colleagues from Georgian for all the help and advice provided along the way.

• Angeline Yasodhara
• Akshay Budhkar
• Borna Almasi
• Parinaz Sobhani
• Rodrigo Ceballos Lentini

I'd also like to extend my gratitude to all the contributors at Darts (for time series predictions) and PyOD (for general outlier detection), whose projects have enabled a straight-forward extension into the domain of time series anomaly detection.

Finally, it'll be remiss of me to not mention DATA Lab @ Rice University, whose wonderful TODS package served as a major inspiration for this project. Please check them out especially if you're looking for AutoML support.

(back to top)