bayesian_changepoint_detection

Bayesian Changepoint Detection

A modern, PyTorch-based library for Bayesian changepoint detection in time series data. This library implements both online and offline methods with GPU acceleration support for high-performance computation.

Features

PyTorch Backend: Leverages PyTorch for efficient computation and automatic differentiation
GPU Acceleration: Automatic device detection with support for CUDA and Apple Silicon (MPS)
Online & Offline Methods: Sequential and batch changepoint detection algorithms
Multiple Distributions: Support for univariate and multivariate Student's t-distributions
Flexible Priors: Constant, geometric, and negative binomial prior distributions
Type Safety: Full type annotations for better development experience
Comprehensive Testing: Extensive test suite with GPU testing support

Installation

This package is published on PyPI as bayescd — the name bayesian-changepoint-detection on PyPI belongs to an unrelated project. The import name is unaffected:

pip install bayescd

import bayesian_changepoint_detection

The sections below cover the supported installation methods with modern Python package managers. Choose the one that best fits your workflow.

Method 1: Using UV (Recommended)

UV is a fast Python package installer and resolver. It's the recommended approach for new projects.

Install UV

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Install the package with UV

# Create a new virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install bayescd

# Or install directly with auto-managed environment
uv run python -c "import bayesian_changepoint_detection; print('Success!')"

Development installation with UV

git clone https://github.com/estcarisimo/bayesian_changepoint_detection.git
cd bayesian_changepoint_detection

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with all dependencies
uv pip install -e ".[dev]"

# Or install specific dependency groups
uv pip install -e ".[dev,docs,gpu]"

Method 2: Using pip with Virtual Environments

Create and activate a virtual environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

Install the package

# Install from PyPI (when available)
pip install bayescd

# Or install from source
git clone https://github.com/estcarisimo/bayesian_changepoint_detection.git
cd bayesian_changepoint_detection
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Method 3: Using conda/mamba

# Create conda environment
conda create -n bayesian-cp python=3.9
conda activate bayesian-cp

# Install PyTorch first (recommended for better compatibility)
conda install pytorch torchvision torchaudio -c pytorch

# Install the package
pip install bayescd

# Or from source
git clone https://github.com/estcarisimo/bayesian_changepoint_detection.git
cd bayesian_changepoint_detection
pip install -e ".[dev]"

Dependency Groups

The package defines several optional dependency groups:

dev: Development and test tools (pytest, numpy, scipy, black, mypy, etc.)
plot: Plotting for the examples and notebooks (matplotlib, seaborn)
docs: Documentation generation (sphinx, numpydoc)
gpu: GPU support (CUDA-enabled PyTorch)

The library itself depends only on PyTorch.

Install specific groups

# With UV
uv pip install "bayescd[dev,gpu]"

# With pip
pip install "bayescd[dev,gpu]"

GPU Support

For CUDA support, ensure you have CUDA-compatible hardware and drivers, then:

Option 1: Install PyTorch with CUDA manually (Recommended)

# Visit https://pytorch.org/get-started/locally/ for the latest commands
# Example for CUDA 11.8:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Example for CUDA 12.1:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Then install the package
pip install bayescd
# or from source:
pip install -e .

Option 2: Install with GPU extras (May install CPU-only PyTorch)

# Note: The [gpu] extra attempts to install torch[cuda], but this may not always
# install the GPU version correctly. Option 1 is more reliable.

# UV
uv pip install "bayescd[gpu]"

# pip
pip install "bayescd[gpu]"

Verify GPU Support

# Check if PyTorch can see your GPU
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'GPU count: {torch.cuda.device_count()}')"
python -c "import torch; print(f'GPU name: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"No GPU\"}')"

GPU/CUDA Acceleration

The library provides GPU acceleration for significant performance improvements. Here's a quick example:

…

Performance Benefits:

10-100x speedup on compatible hardware
Especially beneficial for large datasets (>1000 points) and multivariate data
Automatic memory management and device detection

For a complete GPU guide with benchmarks, multivariate examples, and memory management tips, see

Verify Installation

Test your installation:

import torch
from bayesian_changepoint_detection import get_device_info

# Check device availability
print(get_device_info())

# Quick test
from bayesian_changepoint_detection.generate_data import generate_mean_shift_example
partition, data = generate_mean_shift_example(3, 50)
print(f"Generated test data: {data.shape}")

Or run one of the examples (they plot, so they need the plot extra):

pip install -e ".[plot]"

# Run example from the project root
PYTHONPATH=. python examples/simple_example.py

# Run the test suite (requires the dev extra)
pip install -e ".[dev]"
pytest

Development Setup

For contributors and developers:

…

Troubleshooting

Common Issues

pytest command not found

# Option 1: Use python -m pytest
python -m pytest

# Option 2: Ensure pytest is installed
pip install pytest

# Option 3: Run just the basic online-detection tests
python -m pytest tests/test_online_detection.py

PyTorch installation conflicts

# Uninstall and reinstall PyTorch
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio

CUDA version mismatch

# Check CUDA version
nvidia-smi

# Install matching PyTorch version from https://pytorch.org/

Virtual environment issues

# Recreate virtual environment
rm -rf venv  # or .venv
python -m venv venv
source venv/bin/activate
pip install --upgrade pip

Permission errors

# Use --user flag if you can't create virtual environments
pip install --user bayescd

Quick Start

Online Changepoint Detection

…

Why not simply threshold R[0, :]? Under a constant hazard the posterior probability of run length 0 is the hazard rate at every step, whatever the data say; the evidence for a change at t shows up in the following columns as mass at run length k in column t + k. changepoint_probabilities reads exactly that.

Offline Changepoint Detection

…

GPU Acceleration

# Automatic GPU detection
device = get_device()  # Selects best available device
print(f"Using device: {device}")

# Force specific device
likelihood = StudentT(device='cuda')  # Use GPU
data_gpu = data.to('cuda')

# All computations will run on GPU
R, map_run_lengths = online_changepoint_detection(data_gpu, hazard_func, likelihood)

Multivariate Data

from bayesian_changepoint_detection.online_likelihoods import MultivariateT

# Generate multivariate data
dims = 3
data = torch.cat([
    torch.randn(50, dims) + torch.tensor([0, 0, 0]),
    torch.randn(50, dims) + torch.tensor([2, -1, 1]),
    torch.randn(50, dims) + torch.tensor([0, 0, 0]),
])

# Multivariate likelihood
likelihood = MultivariateT(dims=dims)

# Run detection
R, map_run_lengths = online_changepoint_detection(data, hazard_func, likelihood)
print(get_map_changepoints(R))

Mathematical Background

This library implements Bayesian changepoint detection as described in:

Paul Fearnhead (2006). "Exact and Efficient Bayesian Inference for Multiple Changepoint Problems." Statistics and Computing, 16(2), 203-213.
Ryan P. Adams and David J.C. MacKay (2007). "Bayesian Online Changepoint Detection." arXiv preprint arXiv:0710.3742.
Xuan Xiang and Kevin Murphy (2007). "Modeling Changing Dependency Structure in Multivariate Time Series." ICML, 1055-1062.

Key Concepts

Run Length: Time since the last changepoint
Hazard Function: Prior probability of a changepoint at each time step
Likelihood Model: Distribution of observations within segments
Posterior: Probability distribution over run lengths given data

API Reference

Core Functions

online_changepoint_detection(): Sequential changepoint detection
offline_changepoint_detection(): Batch changepoint detection

Likelihood Models

StudentT: Univariate Student's t-distribution (unknown mean and variance)
MultivariateT: Multivariate Student's t-distribution

Prior Distributions

const_prior(): Uniform prior over changepoint locations
geometric_prior(): Geometric distribution for inter-arrival times
negative_binomial_prior(): Generalized geometric distribution

Hazard Functions

constant_hazard(): Constant probability of changepoint occurrence

Device Management

get_device(): Automatic device selection
to_tensor(): Convert data to PyTorch tensors
get_device_info(): Get information about available devices

Performance

The PyTorch implementation provides significant performance improvements:

Vectorized Operations: Efficient batch computations
GPU Acceleration: 10-100x speedup on compatible hardware
Memory Efficiency: Optimized memory usage for large datasets
Parallel Processing: Multi-threaded CPU operations

Benchmarks

Theoretical estimates, must be benchmarked

On a typical dataset (1000 time points, univariate):

Method	Device	Time	Speedup
Original (NumPy)	CPU	2.3s	1x
PyTorch	CPU	0.8s	2.9x
PyTorch	GPU (RTX 3080)	0.05s	46x

Examples

See the examples/ directory for complete examples:

examples/basic_usage.py: Simple univariate example
examples/multivariate_example.py: Multivariate time series
examples/gpu_acceleration.py: GPU usage examples
examples/Example_Code.ipynb: Jupyter notebook tutorial

Development

Running Tests

Basic Tests

# Run the basic online-detection tests (univariate and multivariate)
python -m pytest tests/test_online_detection.py

Full Test Suite

# First, install development dependencies
pip install -e ".[dev]"

# Run all tests in the tests/ directory
pytest tests/
# or if pytest is not in PATH:
python -m pytest tests/

# Run with verbose output
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=bayesian_changepoint_detection
# or:
python -m pytest tests/ --cov=

bayesian_changepoint_detection

工具介绍