tadkit-core

---

TADkit – Timeseries Anomaly Detection kit

Website and documentation : https://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 github, SBAD, KCPD and github, CNNDRAD, ...). 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 enforcing the TADLearner interface, including the methods from the Confiance.ai program:

• CNNDRAD: two-step deep 1D-CNN for anomaly detection (representation learning + reconstruction score) - catalog.confiance.ai/records/af2ab-hw426
• TDAAD: topological data embedding + minimum covariance determinant analysis catalog.confiance.ai/records/ve158-h4h60 and github
• KCPD: Kernel Change Point analysis for anomalies - catalog.confiance.ai/records/6atzy-3yn05 and github
• SBAD: counterfactual-based multivariate anomaly detection and diagnosis - catalog.confiance.ai/records/npea5-hhw40

Access to some libraries requires Confiance.ai credentials.

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

Document generation

To regenerate the documentation, rerun the following commands from the project root, adapting if necessary:

pip install -r docs/docs_requirements.txt -r requirements.txt
sphinx-apidoc -o docs/source/generated tadkit
sphinx-build -M html docs/source docs/build -W --keep-going

Contributors and Support

Tadkit-core is developed by and supported by the