anomaly-watcher 0.2.0

Source-centric anomaly detection for timestamped sensor and MQTT data

anomaly-watcher

anomaly-watcher detects anomalies in timestamped sensor data with a rolling-window Isolation Forest pipeline. It includes a batch CLI and a local Streamlit dashboard for CSV, MQTT, and project-based monitoring.

Install

python -m pip install anomaly-watcher

The package requires Python 3.13 or newer. The project is licensed under AGPL-3.0-or-later.

Batch CLI

Both input files need a timestamp column and matching signal columns. Numeric, boolean, and categorical signals are supported; incomplete rows are discarded.

anomaly-watcher --train train.csv --test test.csv --output anomaly_overview.png

Useful options include:

• --save-scores scores.csv writes one score row per test window.
• --plot-sensor SENSOR highlights one signal in the overview plot.
• --window-seconds SECONDS controls the rolling feature window.
• --stride-seconds SECONDS controls the distance between windows.
• --threshold-mode max|quantile|std selects threshold calculation.
• --forests-number NUMBER controls the Isolation Forest ensemble size.

Run anomaly-watcher --help for the complete option list.

anomaly-watcher-template copies the bundled CSV template into a target directory.

Dashboard

Launch the local dashboard with:

anomaly-watcher-dashboard

The dashboard creates a project folder containing:

• project_config.json for the project, source, model, and retraining configuration.
• sources/raw_<source-id>.json for persisted source records.
• sources/features.json, sources/scores.json, and sources/anomalies.json for derived results.
• model.joblib for the trained model and scaler.

Each DataSource card keeps its configured name as its source ID. CSV sources can be reloaded from their configured file; MQTT sources can collect train, calibration, or test records; OPC UA is currently an adapter placeholder. MQTT passwords are requested at runtime and are not written to project configuration.

The Run page shows data requirements before training. The Monitoring page displays scaled features, scores, thresholds, and anomaly windows. Clearing source data removes persisted raw records and invalidates derived results while keeping the source card; deleting a source also removes its configuration.

Retraining preserves the original training and calibration records. New good test windows can be allocated as retrain-candidate or recalibrate-candidate, then promoted to retrain-used or recalibrate-used after a successful cycle. Supported allocation strategies are alternating, blocks, ratio, retrain_only, and recalibrate_only.

Bundled demo data

The package includes these fixtures under anomaly_watcher/resources/:

• mock_training.csv: 500 normal records.
• mock_calibration.csv: 300 normal records.
• mock_test_v1.csv: 250 records with a climate anomaly.
• mock_test_v2.csv: 250 records with an air-quality anomaly.
• mock_test_v3.csv: 250 records with an equipment/pressure anomaly.

All fixtures use seven streams sampled every two seconds: room temperature, equipment temperature, humidity, CO2, ozone, air pressure, and VOC.

anomaly-watcher --train src/anomaly_watcher/resources/mock_training.csv --test src/anomaly_watcher/resources/mock_test_v1.csv --output mock_overview.png --save-scores mock_scores.csv --plot-sensor temperature_room --window-seconds 10 --stride-seconds 4 --forests-number 3 --relief-margin 0

Development and release

From the anomaly_watcher directory:

python -m pip install -e ".[test,release]"
python -m pytest tests/ -q
python -m build
python -m twine check dist/*

The current package version is 0.2.0. These commands build and validate the PyPI artifacts locally; uploading requires an explicit twine upload dist/* step and configured PyPI credentials.