Change Point Detection

A modular Python library for online and offline change point detection. Implements 14 online detectors, 4 locators, 2 offline detectors, and 2 hierarchical frameworks from 15+ peer-reviewed publications, all behind a unified API.

Supports univariate and multivariate data, parametric and nonparametric methods, Bayesian and frequentist approaches, and comes with built-in evaluation metrics, hyperparameter tuning, and 32 bundled real-world benchmark datasets.

Requirements

• Python >= 3.10
• numpy >= 1.24
• scipy >= 1.10
• pandas >= 2.0
• matplotlib >= 3.10.8

Installation

git clone https://github.com/chanyikchong/Change-Point-Detection.git && cd Change-Point-Detection
uv sync

Quick Start

Online detection

import cpd
from cpd.datasets import make_mean_shift

X, true_cps = make_mean_shift(n=1000, changepoints=[500], shifts=[3.0])

detector = cpd.CUSUM(h=5.0, v=0.5)
detector.fit(X[:200])  # learn in-control baseline

for t, x in enumerate(X[200:], start=200):
    result = detector.update(x)
    if result.is_changepoint:
        print(f"Change detected at t={t}")
        break

Hierarchical detection + localization

hcpd = cpd.HCPD(
    detectors=[cpd.preset_detector("MCUSUM", arl=500, k=0.5)],
    locator=cpd.preset_locator("LepageLocator", arl=500),
)
hcpd.fit(X[:200])
for x in X[200:]:
    result = hcpd.update(x)

Pre-calibrated presets

detector = cpd.preset_detector("CUSUM", arl=500)  # ready-to-use with calibrated threshold

Evaluation

from cpd.metrics import precision_recall_f1, detection_delay

scores = precision_recall_f1(true_cps, detected_cps, tolerance=5)
delay = detection_delay(true_cps, detected_cps)

Documentation

Full API reference with per-class documentation, parameter descriptions, and usage examples:

• API Index -- categorised listing of all classes and functions
  • Base Classes & Result Types
  • Online Detectors (14 detectors)
  • Change Point Locators
  • Frameworks (HCDT, HCPD, NHCPD)
  • Offline Detectors
  • Datasets (synthetic + 32 bundled TCPD)
  • Metrics
  • Tuning, Calibration & Presets
  • Evaluation

Examples

Runnable scripts in the examples/ directory:

• quickstart.py -- basic CUSUM usage with metrics
• hcpd_example.py -- hierarchical detection + localization
• arl_calibration.py -- ARL-based threshold calibration for detectors
• benchmark_example.py -- cross-algorithm benchmarking

See Adding Algorithms for how to extend the library.

Citation

If you find the code useful in your research and applications, please cite using this BibTeX:

@inproceedings{chen2023coupling,
  title={Coupling QoS Co-Simulation with Online Adaptive Arrival Forecasting},
  author={Chen, Yichong and Roveri, Manuel and Tuli, Shreshth and Casale, Giuliano},
  booktitle={2023 19th International Conference on Network and Service Management (CNSM)},
  pages={1--9},
  year={2023},
  organization={IEEE}
}

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.