Skip to main content

Quick and Easy Time Series Outlier Detection

Project description

Contributors Stargazers Issues Apache 2.0 License Last Commit


Logo

OATS

Quick and Easy Outlier Detection for Time Series
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  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

Python Poetry

Pytorch PytorchLightning TensorFlow Numpy

Darts PyOD

(back to top)

Getting Started


Usage Example

Prerequisites

Python >=3.8, <3.11

For Docker Install:

Docker

For Local Install:

Poetry

Installation

PyPI

  1. Install package via pip
    pip install pyoats
    
    ❗ Installing using an environment manager such as conda, venv, and poetry is highly encouraged as this package contains deep learning frameworks.

Docker

  1. Clone the repo
    git clone https://github.com/georgian-io/pyoats.git && cd pyoats 
    
  2. Build image
    docker build -t pyoats . 
    
  3. Run Container
    # CPU Only
    docker run -it pyoats
    
    # with GPU
    docker run -it --gpus all pyoats
    

Local

  1. Clone the repo
    git clone https://github.com/georgian-io/pyoats.git && cd pyoats 
    
  2. Install via Poetry
    poetry install
    

(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 Pytorch 📝 darts.NBEATS
N-HiTS Predictive Pytorch 📝 darts.NHiTS
RandomForest Predictive ⚠️ darts.RandomForest
Regression Predictive ⚠️ darts.Regression
RNN Predictive Pytorch darts.RNN
Temporal Convolution Network Predictive Pytorch 📝 darts.TCN
Temporal Fusion Transformers Predictive Pytorch 📝 darts.TFT
Transformer Predictive Pytorch 📝 darts.Transformer
Isolation Forest Distance-Based pyod.IForest
Matrix Profile Distance-Based 📝 stumpy
TranAD Reconstruction-Based TensorFlow 📝 tranad
Variational Autoencoder Reconstruction-Based TensorFlow 📝 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 Github LinkedIn eMail

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.

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.

Darts PyOD TODS

(back to top)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyoats-0.1.4.tar.gz (48.3 kB view details)

Uploaded Source

Built Distribution

pyoats-0.1.4-py3-none-any.whl (63.4 kB view details)

Uploaded Python 3

File details

Details for the file pyoats-0.1.4.tar.gz.

File metadata

  • Download URL: pyoats-0.1.4.tar.gz
  • Upload date:
  • Size: 48.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.6 Linux/5.15.146.1-microsoft-standard-WSL2

File hashes

Hashes for pyoats-0.1.4.tar.gz
Algorithm Hash digest
SHA256 6a20913adfc390161a8e713285cabb2e66d4f703069499306213a34b0358e9dc
MD5 fe932d26f9b1f74a6bb003cfde0badf5
BLAKE2b-256 74f8aea6d2043d930c971aea23cbd22e0a22c9f827b0980e1a0f13e0d459bb1f

See more details on using hashes here.

File details

Details for the file pyoats-0.1.4-py3-none-any.whl.

File metadata

  • Download URL: pyoats-0.1.4-py3-none-any.whl
  • Upload date:
  • Size: 63.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.6 Linux/5.15.146.1-microsoft-standard-WSL2

File hashes

Hashes for pyoats-0.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 c7a958da51e578fda54d71001a4df8ce29319999b6ca31cf03753282d52c8457
MD5 36a448e9eaadd4fd9f494018fa82485a
BLAKE2b-256 e781c2356b57c3af9907b697e295514393e811889fffb3614c68d2c2683e5ce1

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page