gridcp: Fast Online Changepoint Detection in Python

Abstract

Online changepoint detection is the problem of detecting distributional changes in a data stream in real-time. A large body of methodology exists for the offline (fixed-size) setting, but applying these methods online quickly becomes infeasible since the per-observation computational cost and memory consumption typically grow at least linearly with the sample size. A recently proposed grid-based methodology (Moen, 2026) overcomes this by evaluating an offline test statistic over a sparse geometric grid of split points, with grid points spaced increasingly far apart further in the past. For a wide class of test statistics, this approach keeps update time and memory consumption growing logarithmic in the length of the data stream, while admitting finite-sample guarantees on the detection delay. Building on this methodology, we present gridcp, an open-source Python package that turns offline changepoint tests into efficient online detectors through a single, uniform interface. Users can choose from nine Numba-accelerated built-in tests, spanning changes in the mean, variance, covariance, and regression coefficients, as well as nonparametric tests and generalized likelihood-ratio tests for exponential-family models. Users can also supply their own test, which the package handles identically. For any test, gridcp provides Monte Carlo routines that calibrate the detection threshold to a target false alarm probability or average run length, including data-driven variants when no parametric null model is available. Through simulations and three real-data case studies, we show that calibration is accurate, that runtime scales favorably with both stream length and dimension, and that the complete pipeline, from calibration to deployment, runs efficiently on long real-world streams with only a short detection delay.