Bayesian Histogram Anomaly Detection (BHAD)

A Python implementation of the Bayesian Histogram-based Anomaly Detection (BHAD) algorithm for unsupervised anomaly detection with explainability features.

Overview

BHAD is an explainable anomaly detection method that leverages Bayesian inference and histogram-based modeling to identify outliers in high-dimensional datasets. The algorithm provides both global and local explainability due to its linear structure, making it particularly valuable for applications requiring interpretable results.

Key Features

• Explainable AI: Provides both global and local explanations for anomaly predictions
• Bayesian Approach: Uses Bayesian inference for robust uncertainty quantification
• High-Dimensional Data: Handles high-dimensional datasets effectively
• Unsupervised Learning: No labeled data required for training
• Linear Structure: Interpretable model architecture

Installation

Using uv

Install package via uv:

uv venv --python 3.12
uv add bhad

Using pip

python3 -m venv .venv
source .venv/bin/activate
pip install bhad

Quick Start

import numpy as np
import pandas as pd
from bhad.model import BHAD

# Load your data
X = pd.DataFrame(np.random.randn(1000, 10), 
                 columns=[f'feature_{i}' for i in range(10)])

# Create BHAD model with integrated discretization
model = BHAD(contamination=0.01, nbins=None, verbose=False)

# Fit the model and predict anomalies
anomaly_labels = model.fit_predict(X)        # Returns -1 for outliers, 1 for inliers
anomaly_scores = model.decision_function(X)

Documentation

For detailed usage examples, API reference, and tutorials, visit our documentation.

Examples

The package includes Jupyter notebooks with practical examples:

• Toy_Example.ipynb: Simulated data demonstration
• Titanic_Example.ipynb: Real-world dataset application

Research & Publications

This implementation is based on the following research papers:

1. Vosseler, A. (2022): Unsupervised Insurance Fraud Prediction Based on Anomaly Detector Ensembles

2. Vosseler, A. (2023): BHAD: Explainable anomaly detection using Bayesian histograms

Conference Presentations

• PyCon DE & PyData Berlin 2023: Watch the presentation
• MaxEnt 2023: 42nd International Workshop on Bayesian Inference and Maximum Entropy Methods in Science and Engineering, Max-Planck-Institute for Plasma Physics, Garching, Germany

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Alexander Vosseler

Citation

If you use BHAD in your research, please cite:

@article{vosseler2022unsupervised,
  title={Unsupervised Insurance Fraud Prediction Based on Anomaly Detector Ensembles},
  author={Vosseler, Alexander},
  journal={Risks},
  volume={10},
  number={7},
  year={2022},
  month={June}
}