pybocd-Examples

Minimal, runnable examples demonstrating how to use the pybocd library for Bayesian online change detection (BOCD). This repository contains two example drivers and plotting helpers that show typical workflows for synthetic and real (IIoT) time series data.

Contents

• simulated.py — end-to-end example using BOCDGMM on synthetic data.
• iiot.py — example using BOCDNIG on an IIoT CPU iowait timeseries.
• data/ — CSV inputs used by the examples (simulated.csv, iiot.csv).
• plots/ — example output plots saved by the scripts.
• logs/ — runtime logs produced by example runs.
• utils/ — plotting helpers used by the examples.

Requirements

• Python 3.8+
• numpy, pandas, matplotlib, scikit-learn
• pybocd (install from PyPI or your local development copy)

Install required packages with pip:

pip install numpy pandas matplotlib scikit-learn pybocd

If you are developing pybocd locally, ensure your virtualenv has it installed in editable mode, e.g. pip install -e /path/to/pybocd.

Quick Start

Run the simulated example:

python simulated.py

Run the IIoT example:

python iiot.py

Each script reads CSV input from data/, runs the BOCD algorithm, writes a small log to logs/, and saves visualization SVGs into plots/<example>/.

Configuration

Both simulated.py and iiot.py include simple, easy-to-edit configuration variables near the top of the file (data paths, BOCD hyperparameters, run length). Edit those values to change datasets, algorithm hyperparameters, or output locations.

Key variables to review:

• DATA_PATH, PLT_DIR, LOG_PATH — file locations for input, plots, logs.
• BOCD_START, BOCD_END — slice of the data to process.
• Hyperparameters passed to BOCDGMM / BOCDNIG in each script.

What the examples demonstrate

• iiot.py shows BOCD with Normal-Inverse-Gamma (NIG) conjugate model for a simple single-dimensional timeseries and demonstrates level-shift detection.
• simulated.py shows BOCD with a Gaussian mixture (GMM) model; it records MAP path, parameters ($\mu$, $\sigma$), and computes confusion metrics for outlier detection.

Both examples produce plots that illustrate detected change points, MAP run-length, and credible intervals.

Extending or Reproducing

• To run a subset of a dataset, edit BOCD_START / BOCD_END.
• To add a new dataset, put a CSV in data/ with the same column names used by the example (simulated.csv expects data, is_level_shift, is_anomaly, baseline; iiot.csv expects cpu-iowait).
• The plotting helpers in utils/ are small and intended to be easy to reuse in other projects.

Data Attribution

The Industrial IoT dataset (data/iiot.csv) used in the iiot.py example is sourced from Westermo and is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License. We gratefully acknowledge Westermo for making this real-world telemetry data available for research and development purposes.

License

This repository is distributed under the GNU General Public License v3.0. See the top-level LICENSE file for details.

Contact / Contributing

If you find issues or want to contribute examples, open an issue or a PR.

Small, focused examples and documentation improvements are especially welcome.