pbp-anomaly

Training-free anomaly detection in environmental sensor networks via pseudo-Boolean polynomial (PBP) decomposition.

Reference implementation of the PBP anomaly scoring described in:

T. M. Chikake and B. Goldengorin, "Pseudo-Boolean polynomial anomaly scoring for intelligent multisensor environmental monitoring," in International Conference on Advanced Sensing and Intelligent Systems (ICASIS 2026), Proc. SPIE 14309, 2026. https://doi.org/10.1117/12.3121130

The repository also contains the multi-dataset experiments of an extended study.

Install

pip install pbp-anomaly

This also installs the PBP core, tmc-pbp (imported as pbp).

Quick start (reproducing the experiments)

git clone https://github.com/Tenfleques/pbp-anomaly.git
cd pbp-anomaly
pip install -e ".[all]"

# Download large datasets (Beijing, NOAA weather stations)
python experiments/download_data.py

# Verify pre-computed results (should report 200+ PASS, 0 FAIL)
python experiments/verify_consistency.py

# Generate all figures
python experiments/generate_figures.py

What this repo contains

• pbp_anomaly/ -- Python package implementing the PBP anomaly detector
• data/ -- Small datasets shipped with the repo (UCI, OpenMeteo); large datasets downloaded via script
• results/precomputed/ -- Pre-computed experiment results (JSON/CSV) for instant verification
• experiments/ -- Scripts to reproduce all results and figures from the paper
• tests/ -- Unit tests (27 tests)

Datasets

The paper evaluates PBP across 9 datasets spanning two sensor domains:

"Shipped" means the CSV is included in this repo. "Download" means download_data.py fetches it automatically.

Reproducing results

Verify pre-computed results

python experiments/verify_consistency.py

This checks every number cited in the manuscript against the pre-computed result files in results/precomputed/. No data download required.

Full replication from raw data

# Download datasets
python experiments/download_data.py

# Run all experiments (may take several hours)
python experiments/replicate_all.py --output-dir results/local

# Verify fresh results
python experiments/verify_consistency.py --results-dir results/local

# Generate figures from fresh results
python experiments/generate_figures.py --results-dir results/local

For a quick smoke test on a single dataset:

python experiments/replicate_all.py --datasets UCI --quick --output-dir results/local

Figures

python experiments/generate_figures.py

Generates Fig 1 (temporal robustness), Fig 2 (hub variable heatmap), and Fig 3 (sensor-pair z-score case study) in figures/.

Library usage

from pbp_anomaly import AnomalyDetector
import pandas as pd

df = pd.read_csv('your_sensor_data.csv')
detector = AnomalyDetector(window_size=6, mode='both')
result = detector.fit_score(df, sensor_cols=['CO', 'NO2', 'O3'])

print(f"AUC-ROC: {result['standard']['auc_roc']:.3f}")
print(f"Top sensor pairs: {result['pair_ranking'][:3]}")

Or via CLI:

pbp-anomaly detect data.csv --sensors CO,NO2,O3 --mode both

Running tests

pytest tests/ -v

Dependencies

Core: numpy, pandas, scipy, scikit-learn, tmc-pbp (Python >= 3.10)

Optional: matplotlib (figures), requests (NOAA download), pytest (tests)

All installed automatically via pip install -e ".[all]".

Citation

@inproceedings{Chikake2026icasis,
  author    = {Chikake, Tendai M. and Goldengorin, Boris},
  title     = {Pseudo-Boolean polynomial anomaly scoring for intelligent multisensor environmental monitoring},
  booktitle = {International Conference on Advanced Sensing and Intelligent Systems (ICASIS 2026)},
  series    = {Proc. SPIE},
  volume    = {14309},
  publisher = {SPIE},
  year      = {2026},
  doi       = {10.1117/12.3121130}
}

License

MIT