Metadata-Version: 2.4
Name: anomaly-watcher
Version: 0.1.0
Summary: Isolation Forest anomaly detection for timestamped sensor CSV data
Author: Ricardo Cunha
License-Expression: AGPL-3.0
Project-URL: Homepage, https://github.com/ricardo-cunha/python-tools
Project-URL: Repository, https://github.com/ricardo-cunha/python-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: streamlit

# 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

```powershell
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:

```powershell
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.

```powershell
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.
