tadkit-core

TADkit – Timeseries Anomaly Detection kit

Website and documentation : irt-systemx.github.io/tadkit-core/

Overview

tadkit-core is a flexible and extensible Python toolkit for detecting anomalies in time-series data. It empowers data scientists and developers to quickly identify unusual patterns, monitor system behavior, and build predictive models—all with a modular design that makes integration and customization straightforward.

It builds upon scikit-learn for interfacing anomaly detection algorithms.

🔍 Key Features

• Unified Interfaces for Anomaly Detection Provides a coherent set of interfaces for different time-series anomaly detection methods. The main abstractions are:

  • Formater: prepares raw timeseries data into a machine-learning-friendly format.
  • TADLearner: enforces .fit(X), .score_samples(X), and .predict(X) coherently for unsupervised anomaly detection.

• Supports Multiple Detection Methods Includes methods from scikit-learn and Confiance.ai components (TDAAD and KCPD). All learners can be instantiated with default parameters.

• Dynamic Component Loading Only installed components are made available in the system; unavailable components are automatically skipped.

• Extensible and Modular Designed for easy integration of new anomaly detection methods and smooth scaling across different datasets and applications.

🛠 Installation

Install from PyPI (recommended):

pip install tadkit-core

Or install from source:

git clone https://github.com/IRT-SystemX/tadkit-core.git
cd tadkit-core
pip install -r requirements.txt

Requirements:

• Python ≥ 3.8+
• See requirements.txt for full dependency list

🚀 Quickstart

# Prepare your data
from tadkit.catalog.rawtowideformatter import RawToWideFormatter
formatter = RawToWideFormatter(data=my_raw_data, backend="pandas")
X = formatter.format()

# Query the available anomaly detection methods that are compatible with your data (univariate or multivariate, etc.)
from tadkit.base.registry import registry
for learner_cls in registry.match_learners(formatter):
    learner = learner_cls()  # instantiate directly
    # Learner calibration
    learner.fit(X)
    # Anomaly scores
    y_score = learner.score_samples(X)
    # Detect anomalies
    predictions = learner.predict(X)

The modular architecture allows easy swapping of learners and formatters for experimentation with different anomaly detection algorithms.

🪸⁠ Deep Dive 🪼

TADkit includes a range of introductory and example notebooks that are good entry points to understand the proposed features:

• Univariate anomaly detection example Learn how to craft your own anomaly detection method for a univariate timeseries.
• Interactive anomaly detector demo Experiment with multiple anomaly detectors concurrently.

TADkit data ingestion

The Formatter abstract class provides array-agnostic interface for connecting your data to your anomaly detection algorithm.

TADkit offers a functional RawToWideFormatter that ingests your timeseries data, converts it to Wide Format and supports both pandas DataFrame and NumPy array outputs.

Learning with TADkit

The TADLearner interface

TADLearner standardizes anomaly detection methods through a protocol that enforces:

• .fit(X): for calibrating the model,
• .score_samples(X): for producing anomaly scores (unbounded),
• .predict(X): for producing anomaly labels (1 = normal, -1 = abnormal)

Catalog of methods

TADkit provides a catalog of methods following the TADLearner interface, including methods from the Confiance.ai program:

• TDAAD: topological data embedding + minimum covariance determinant analysis Catalog page and github
• KCPD: Kernel Change Point analysis for anomalies - Catalog page and github

The following methods from the Confiance.ai program were also originally supported, but are no longer accessible:

• CNNDRAD: two-step deep 1D-CNN for anomaly detection (representation learning + reconstruction score) - Catalog page
• SBAD: counterfactual-based multivariate anomaly detection and diagnosis - Catalog page

The TADkit catalog also includes base learners such as Kernel density-based anomaly detection, Gaussian mixtures anomaly detection, etc...

📚 Documentation & Resources

• 📖 Full API Documentation
• 🧪 Examples
• 🛠 Contributing Guide
• 🗒 Changelog

Contributors and Support

This work has been supported by the French government under the "France 2030” program, as part of the SystemX Technological Research Institute within the Confiance.ai project. 

TADkit is developed by IRT SystemX and supported by the European Trustworthy AI Association