pbp-anomaly 0.2.0__tar.gz

pbp_anomaly-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tendai Chikake, Boris Goldengorin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pbp_anomaly-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pbp-anomaly
+Version: 0.2.0
+Summary: Training-free anomaly detection via pseudo-Boolean polynomial decomposition
+Author: Boris Goldengorin
+Author-email: Tendai Chikake <tendaichikake@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/Tenfleques/pbp-anomaly
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: tmc-pbp>=0.1.0
+Provides-Extra: noaa
+Requires-Dist: requests; extra == "noaa"
+Provides-Extra: figures
+Requires-Dist: matplotlib>=3.5; extra == "figures"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: requests; extra == "all"
+Requires-Dist: matplotlib>=3.5; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install pbp-anomaly
+```
+
+This also installs the PBP core, [`tmc-pbp`](https://pypi.org/project/tmc-pbp/) (imported as `pbp`).
+
+## Quick start (reproducing the experiments)
+
+```bash
+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:
+
+| Dataset | Domain | Sensors | Readings | Source | Shipped |
+|---------|--------|---------|----------|--------|---------|
+| UCI Air Quality (Italy) | Air quality | 8 | 9,357 | [UCI MLR](https://archive.ics.uci.edu/dataset/360/air+quality) | Yes |
+| Beijing Dongsi | Air quality | 10 | 35,064 | [Zhang et al. 2017](https://archive.ics.uci.edu/dataset/501/beijing+multi+site+air+quality+data) | Download |
+| EPA AQS (Los Angeles) | Air quality | 4 | 26,280 | [EPA AQS](https://aqs.epa.gov/aqsweb/airdata/download_files.html) | Optional |
+| Sao Paulo (CAMS) | Air quality | 6 | 17,520 | [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api) | Yes |
+| Cape Town (CAMS) | Air quality | 6 | 17,520 | [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api) | Yes |
+| Chicago O'Hare | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| Miami | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| San Francisco | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| Fairbanks | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+
+"Shipped" means the CSV is included in this repo. "Download" means `download_data.py` fetches it automatically.
+
+## Reproducing results
+
+### Verify pre-computed results
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+python experiments/replicate_all.py --datasets UCI --quick --output-dir results/local
+```
+
+### Figures
+
+```bash
+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
+
+```python
+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:
+
+```bash
+pbp-anomaly detect data.csv --sensors CO,NO2,O3 --mode both
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+## Dependencies
+
+Core: numpy, pandas, scipy, scikit-learn, [tmc-pbp](https://github.com/Tenfleques/tmc-pbp) (Python >= 3.10)
+
+Optional: matplotlib (figures), requests (NOAA download), pytest (tests)
+
+All installed automatically via `pip install -e ".[all]"`.
+
+## Citation
+
+```bibtex
+@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

pbp_anomaly-0.2.0/README.md

@@ -0,0 +1,153 @@
+# 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
+
+```bash
+pip install pbp-anomaly
+```
+
+This also installs the PBP core, [`tmc-pbp`](https://pypi.org/project/tmc-pbp/) (imported as `pbp`).
+
+## Quick start (reproducing the experiments)
+
+```bash
+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:
+
+| Dataset | Domain | Sensors | Readings | Source | Shipped |
+|---------|--------|---------|----------|--------|---------|
+| UCI Air Quality (Italy) | Air quality | 8 | 9,357 | [UCI MLR](https://archive.ics.uci.edu/dataset/360/air+quality) | Yes |
+| Beijing Dongsi | Air quality | 10 | 35,064 | [Zhang et al. 2017](https://archive.ics.uci.edu/dataset/501/beijing+multi+site+air+quality+data) | Download |
+| EPA AQS (Los Angeles) | Air quality | 4 | 26,280 | [EPA AQS](https://aqs.epa.gov/aqsweb/airdata/download_files.html) | Optional |
+| Sao Paulo (CAMS) | Air quality | 6 | 17,520 | [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api) | Yes |
+| Cape Town (CAMS) | Air quality | 6 | 17,520 | [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api) | Yes |
+| Chicago O'Hare | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| Miami | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| San Francisco | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+| Fairbanks | Weather | 6 | 17,520 | [NOAA ISD](https://www.ncei.noaa.gov/products/land-based-station/integrated-surface-database) | Download |
+
+"Shipped" means the CSV is included in this repo. "Download" means `download_data.py` fetches it automatically.
+
+## Reproducing results
+
+### Verify pre-computed results
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+python experiments/replicate_all.py --datasets UCI --quick --output-dir results/local
+```
+
+### Figures
+
+```bash
+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
+
+```python
+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:
+
+```bash
+pbp-anomaly detect data.csv --sensors CO,NO2,O3 --mode both
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+## Dependencies
+
+Core: numpy, pandas, scipy, scikit-learn, [tmc-pbp](https://github.com/Tenfleques/tmc-pbp) (Python >= 3.10)
+
+Optional: matplotlib (figures), requests (NOAA download), pytest (tests)
+
+All installed automatically via `pip install -e ".[all]"`.
+
+## Citation
+
+```bibtex
+@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

pbp_anomaly-0.2.0/pbp_anomaly/__init__.py

@@ -0,0 +1,20 @@
+"""
+pbp-anomaly: Training-free anomaly detection via pseudo-Boolean polynomial decomposition.
+
+Detects anomalies in multivariate sensor streams by extracting polynomial features
+from binarized sliding windows. No training data required.
+
+Usage:
+    from pbp_anomaly import detect, AnomalyDetector
+
+    detector = AnomalyDetector(window_size=6, thresholds='auto')
+    scores = detector.fit_score(dataframe, sensor_cols=['CO', 'NO2', 'O3'])
+
+    # Or one-shot:
+    result = detect(dataframe, sensor_cols=['CO', 'NO2', 'O3'])
+"""
+
+from pbp_anomaly.detector import AnomalyDetector, detect
+
+__all__ = ['AnomalyDetector', 'detect']
+__version__ = '0.2.0'

pbp_anomaly-0.2.0/pbp_anomaly/cli.py

@@ -0,0 +1,104 @@
+"""
+CLI for pbp-anomaly.
+
+Usage:
+    pbp-anomaly detect data.csv --sensors CO,NO2,O3 --mode standard
+    pbp-anomaly detect data.csv --sensors CO,NO2,O3 --mode both --window 12
+    pbp-anomaly info
+"""
+
+import argparse
+import json
+import sys
+
+from pbp_anomaly.detector import AnomalyDetector, get_backend
+
+
+def cmd_detect(args):
+    from pbp_anomaly.parsers import load_csv
+
+    sensor_cols = [s.strip() for s in args.sensors.split(',')]
+    ref_cols = [s.strip() for s in args.ref.split(',')] if args.ref else None
+
+    ds = load_csv(args.csv, sensor_cols, ref_cols, name=args.csv)
+
+    detector = AnomalyDetector(
+        window_size=args.window,
+        mode=args.mode,
+        percentile=args.percentile,
+        two_tailed=args.two_tailed,
+        top_k=args.top_k,
+    )
+
+    print(f"Dataset: {ds['name']}")
+    print(f"Readings: {len(ds['data'])}, Sensors: {len(sensor_cols)}")
+    print(f"Backend: {get_backend()}")
+    print(f"Mode: {args.mode}, Window: {args.window}, Percentile: {args.percentile}")
+    print()
+
+    result = detector.fit_score(ds['data'], ds['sensor_cols'], ds['ref_cols'])
+
+    print(f"Windows: {result['n_windows']}")
+    print(f"Anomaly rate: {100 * result['anomaly_fraction']:.1f}%")
+    print()
+
+    if 'standard' in result:
+        r = result['standard']
+        print(f"PBP standard:  AUC = {r['auc_roc']:.4f}  CI = {r['ci_95']}")
+    if 'pair' in result:
+        r = result['pair']
+        print(f"PBP pair:      AUC = {r['auc_roc']:.4f}  CI = {r['ci_95']}")
+        if 'pair_ranking' in result:
+            print(f"\nTop 5 sensor pairs:")
+            for p in result['pair_ranking'][:5]:
+                print(f"  {p['pair']:<20s} AUC = {p['auc']:.4f}")
+
+    if args.output:
+        # Remove non-serializable arrays
+        out = {k: v for k, v in result.items() if k not in ('scores', 'labels')}
+        with open(args.output, 'w') as f:
+            json.dump(out, f, indent=2, default=str)
+        print(f"\nResults saved to {args.output}")
+
+
+def cmd_info(args):
+    from pbp_anomaly import __version__
+    print(f"pbp-anomaly v{__version__}")
+    print(f"PBP backend: {get_backend()}")
+    print(f"Features per window: 6 (degree, monomial_count, entropy, coeff_std, l1_norm, coeff_range)")
+    print(f"Modes: standard (full-matrix), pair (sensor-pair decomposition), both")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='pbp-anomaly',
+        description='Training-free anomaly detection via PBP decomposition',
+    )
+    sub = parser.add_subparsers(dest='command')
+
+    # detect
+    p_detect = sub.add_parser('detect', help='Run anomaly detection on a CSV file')
+    p_detect.add_argument('csv', help='Path to CSV file')
+    p_detect.add_argument('--sensors', required=True, help='Comma-separated sensor column names')
+    p_detect.add_argument('--ref', default=None, help='Reference columns for labels (default: same as sensors)')
+    p_detect.add_argument('--mode', default='standard', choices=['standard', 'pair', 'both'])
+    p_detect.add_argument('--window', type=int, default=6, help='Window size (default: 6)')
+    p_detect.add_argument('--percentile', type=int, default=95, help='Threshold percentile (default: 95)')
+    p_detect.add_argument('--two-tailed', action='store_true', help='Flag both high and low extremes')
+    p_detect.add_argument('--top-k', type=int, default=5, help='Top-K features for composite (default: 5)')
+    p_detect.add_argument('--output', '-o', help='Save results to JSON file')
+
+    # info
+    sub.add_parser('info', help='Show library info')
+
+    args = parser.parse_args()
+    if args.command == 'detect':
+        cmd_detect(args)
+    elif args.command == 'info':
+        cmd_info(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == '__main__':
+    main()