Quick Start

This guide will get you up and running with Fast-BOCPD in 5 minutes.

Installation

Install via pip:

pip install fast-bocpd

Or install from source:

git clone https://github.com/TiaanViviers/Fast_BOCPD.git
cd Fast_BOCPD
pip install -e .

Basic Usage

Let’s detect a changepoint in some synthetic data.

Step 1: Generate Test Data

import numpy as np

# Create data with a mean shift at t=100
segment1 = np.random.normal(0, 1, 100)   # Mean = 0
segment2 = np.random.normal(5, 1, 100)   # Mean = 5
data = np.concatenate([segment1, segment2])

Step 2: Set Up the Detector

import fast_bocpd as fb

# Choose a model (Gaussian for continuous data)
model = fb.GaussianNIG(
    mu0=0.0,      # Prior mean
    kappa0=1.0,   # Prior precision
    alpha0=1.0,   # Prior shape
    beta0=1.0     # Prior scale
)

# Choose a hazard function (constant = memoryless)
hazard = fb.ConstantHazard(lambda_=100)  # Expected run length

# Create detector
detector = fb.BOCPD(model, hazard, max_run_length=250)

Step 3: Detect Changepoints

# Process data (offline/batch mode)
results = detector.batch_update(data)

# Extract changepoints
changepoints = results.get_changepoints(threshold=0.5)
print(f"Detected changepoints: {changepoints}")
# Output: Detected changepoints: [100]

Visualizing Results

import matplotlib.pyplot as plt

# Plot data with detected changepoints
plt.figure(figsize=(12, 4))
plt.plot(data, 'k-', alpha=0.5, label='Data')

for cp in changepoints:
    plt.axvline(cp, color='r', linestyle='--',
                label='Detected changepoint')

plt.xlabel('Time')
plt.ylabel('Value')
plt.legend()
plt.title('Changepoint Detection Results')
plt.show()

Online (Streaming) Mode

For real-time applications, use online mode:

from fast_bocpd import OnlineChangeDetector

# Create online wrapper
online_detector = OnlineChangeDetector(detector)

# Process data point-by-point
for t, x in enumerate(data):
    result = online_detector.update(x)

    # Check for changepoint
    if result.changepoint_detected(threshold=0.5):
        print(f"Changepoint detected at t={t}")

Next Steps

Choosing the Right Observation Model - Learn which model to use for your data
Tuning Parameters - Understand hyperparameters
Stock Volatility Detection - See a real-world example
API Reference - Full API reference

Common Mistakes

Wrong model for data type: Use PoissonGamma for count data, not GaussianNIG
Lambda too small: If lambda_=10 but changepoints are rare (every 1000 points), the detector will be too sensitive
Not resetting detector: Call detector.reset() between independent datasets
Forgetting threshold: get_changepoints() requires a threshold (typically 0.3-0.7)