anomaly-watcher 0.1.0

Isolation Forest anomaly detection for timestamped sensor CSV data

anomaly-watcher

CLI tool for Isolation Forest based anomaly detection on timestamped sensor CSV files.

Slides a rolling window over sensor signals, extracts 9 statistical features per sensor (mean, std, min, max, slope, last value, difference std, skewness, kurtosis) plus elapsed time, trains a two-pass Isolation Forest on the training set (first pass discards outlier training windows above a cleanup quantile), then scores test windows against a configurable threshold. The final scoring pass runs --forests-number Isolation Forest instances (default: 3), uses the mean score per window for thresholding, and plots the mean plus a shaded +/- 1 std band. Three threshold modes are available: max (max score * relief margin), quantile (score quantile), and std (mean + std * relief margin).

Sensor columns are auto-detected as numeric, boolean, or categorical. CSV rows with missing values are dropped. The output is a 6-panel overview PNG (raw features, z-score features, and anomaly scores for train and test) with anomalous test windows highlighted. Optional score CSV output includes the mean anomaly score, per-window score standard deviation, and one score column per forest run.

Usage

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

Both CSV files must contain a timestamp column and the same signal columns. Signal columns may be numeric, logical/boolean, or categorical strings. Rows with missing values after conversion are removed.

Run anomaly-watcher --help for all options. The companion command anomaly-watcher-template copies the template CSV to a target directory for quick project setup.

Local dashboard

The lightweight local dashboard can be launched with:

anomaly-watcher-dashboard

The dashboard starts from a local project configuration. New projects choose one mode:

• batch: train and test with CSV files.
• real-time: train from an initial CSV, then monitor incoming stream data such as MQTT JSON messages.

By default, the dashboard proposes a project folder named anomaly_watcher_project under the directory where you launched the dashboard. If launched from the repo root, that resolves to C:\Users\apoli\Documents\GitHub\python-tools\anomaly_watcher_project. The Project Setup page shows the resolved absolute folder before saving.

The first dashboard milestone includes project setup, batch CSV detection, a CSV replay incoming-data inspector, and scheduled retraining settings placeholders. Continuous MQTT and OPC UA integrations are planned behind the same source interface.

Mock data

Example CSV files are included under src/anomaly_watcher/resources/:

• mock_training.csv
• mock_test.csv

They contain numeric, boolean, and categorical signal columns and can be used for a quick package test. The test file includes a clear injected anomaly where Temp_bed drops strongly while Temp_tool0 and Humidity rise sharply.

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

With these compact demo settings, the mock test set should produce confirmed anomalous windows around the injected fault segment.