ruptures: Python change point detection for non-stationary signals, off-line only

Off-line detection means the full signal is available before analysis begins

Change point detection finds moments in a signal where its statistical properties shift: a mean that steps to a different level, a variance that tightens or widens, or a correlation structure that reorganizes between segments. ruptures targets this problem in the off-line setting, where the entire signal is recorded and available before any algorithm runs. That constraint stands in direct contrast to online methods, which update their estimate incrementally as each new sample arrives and never have access to future data.

Off-line detection gives algorithms access to future samples when making decisions about past points, which is why exact methods can find a globally optimal segmentation rather than a locally consistent one. For the use cases ruptures targets, such as biological signals, remote sensing time series, and sports performance data, complete recordings are often available before any segmentation is needed.

The package covers parametric models, where the form of the distribution within each segment is specified, and non-parametric models, which make fewer assumptions about the shape of the data. Algorithms for exact detection search over all possible segmentations to find the optimal one. Approximate algorithms trade some of that optimality for faster computation on longer signals.

Pelt detects change points by minimizing a penalized cost; the usage example shows the three-step workflow

A basic detection run follows three steps: fit the algorithm to the signal, predict the change point positions, and visualize. The example from the README generates a synthetic three-dimensional signal of 1000 samples with 4 breakpoints, applies Pelt with a radial basis function kernel model, and displays the result:

import matplotlib.pyplot as plt
import ruptures as rpt

# generate signal
n_samples, dim, sigma = 1000, 3, 4
n_bkps = 4  # number of breakpoints
signal, bkps = rpt.pw_constant(n_samples, dim, n_bkps, noise_std=sigma)

# detection
algo = rpt.Pelt(model="rbf").fit(signal)
result = algo.predict(pen=10)

# display
rpt.display(signal, bkps, result)
plt.show()

`rpt.pw_constant` generates a piecewise constant signal with Gaussian noise, giving both the signal array and the ground-truth breakpoint positions. `rpt.Pelt` is the Pelt algorithm, which uses a penalized least-squares criterion to find an efficient exact partition. The `model="rbf"` argument selects the radial basis function kernel cost. Calling `predict(pen=10)` returns the estimated breakpoint positions as a list. `rpt.display` then plots the signal with alternating colors marking the detected regimes and dashed lines at the estimated change points.

ruptures installs from PyPI and conda-forge; Cython and C extensions compile at build time

PyPI package name is `ruptures`. A conda-forge package under the same name is also available. Full installation instructions are at the documentation site at https://centre-borelli.github.io/ruptures-docs/install/. Python 3.10, 3.11, 3.12, 3.13 and 3.14 are supported, per the badge in the README.

The pyproject.toml lists build requirements: setuptools>=42, wheel, Cython>=0.28.5, setuptools_scm[toml]>=3.4, numpy>=2.0.0 and scipy>=0.19.1. Cython is a build-time requirement because two C extensions compile during installation. The first, `ruptures.detection._detection.ekcpd`, contains the kernelized detection computation and the Pelt kernelized implementation. The second, `ruptures.utils._utils.convert_path_matrix`, handles path matrix conversion. Both are defined in setup.py with .pyx source files alongside C files.

For environments where compiling is difficult, a pre-built wheel from PyPI or the conda-forge package avoids the compilation step entirely. The numpy>=2.0.0 requirement also means NumPy 1.x installations are not compatible with the current version.

Modular algorithm and model pairing: the rbf model is one of several cost options

ruptures' described architecture separates algorithms from cost models. An algorithm controls how the search over segmentations is conducted: exhaustively, with dynamic programming, or with an approximation. A cost model defines what makes a segmentation good within a segment, such as least squares for piecewise constant signals or a kernel cost like rbf for more general distributional shifts.

Swapping the model argument changes the cost function without changing the search algorithm, while swapping the algorithm class changes the search strategy while keeping the same cost function. Per the README, different algorithms and models can be connected and extended within the package. That design means an approximate algorithm can be combined with a parametric cost when exact search is computationally prohibitive on a long signal, without rewriting the rest of the detection pipeline. A user can also extend the library with a custom cost model and plug it into any of the existing search algorithms without modifying library internals.

The `model="rbf"` in the example targets kernel-based non-parametric detection. For simpler signals where the model assumption holds, parametric costs may detect changes with fewer samples. The README does not enumerate all available model strings in the section shown, but the documentation at https://centre-borelli.github.io/ruptures-docs covers the full API.

From NASA crop monitoring to Chelsea FC: the use cases span remote sensing, sports and biology

Several documented use cases appear in the README. NASA uses ruptures to monitor crops in California and Iran, as part of work characterizing spatiotemporal variability in irrigation extent and timing through thermal remote sensing (Jalilvand et al., submitted to Remote Sensing of Environment, 2024). Chelsea FC has contacted the authors to monitor players, though no publication is linked yet.

On the biology side, the authors apply ruptures to understand the regulation of acetylcholine, a neurotransmitter relevant to myasthenia gravis, with published results in the Journal of Physiology (doi: 10.1113/JP287243). Researchers in Japan use ruptures to detect changes in classroom engagement and student participation (doi: 10.1186/s40561-024-00317-6). A separate study uses it as part of a pipeline to observe phytoplankton diversity in marine biodiversity monitoring (doi: 10.1007/s10712-024-09859-3). Croatian crystallographers apply it to protein motions using angular diagrams (JCIM, doi: 10.1021/acs.jcim.4c00650).

Those domains share a common structure: time series with distinct phases where statistical properties differ across phases, and where finding those phase boundaries is the scientific question.

Off-line constraint rules out streaming, and the penalty parameter requires manual tuning

Change point detection on a live data stream is not what ruptures does. Because the off-line design requires the full signal before analysis, any use case where latency matters, such as anomaly alerting or real-time monitoring, requires a different library or algorithm category. ruptures will not output a result until the signal is complete.

Penalty parameter selection is another responsibility left to the user. The example uses pen=10, which is an arbitrary value for a demonstration signal. In practice, the correct penalty depends on the signal's noise level, the expected number of change points, and the cost model used. The library does not include an automated penalty selector in the example or in the README section shown, which means a user approaching a new domain must derive or calibrate this value separately.

The alternative to model-based detection is threshold-based segmentation: marking a change point wherever a signal statistic crosses a fixed value. That approach requires less setup but gives no guarantee of statistical optimality and provides no principled way to control the number of detected changes.

BSD-2-Clause license from ENS Paris-Saclay and CNRS, with a published academic citation

License is BSD 2-Clause. Copyright covers 2017-2022 and is held by ENS Paris-Saclay and CNRS. BSD 2-Clause permits redistribution and use in source and binary forms with modification, provided the copyright notice and disclaimer are retained.

For scientific use, the authors request citation of: C. Truong, L. Oudre, N. Vayatis. 'Selective review of offline change point detection methods.' Signal Processing, 167:107299, 2020. That paper predates all three listed releases and establishes the algorithmic foundation.

Version v1.1.10 was released on 2025-09-10, following v1.1.9 on 2023-12-11 and v1.1.8 on 2023-06-07. The gap between v1.1.8 and v1.1.9 was about eighteen months, and the gap between v1.1.9 and v1.1.10 was about twenty-one months, so releases are infrequent. The last push to the repository was on 2026-10-06, and the repository is not archived, showing ongoing work between tagged releases. CHANGELOG.md at the repository root tracks version history. The test suite lives under tests/ with pytest configured via pyproject.toml to run verbosely with minversion = 6.0.

Editorial conclusion

ruptures suits research teams and data scientists who analyze signals with known or suspected regime shifts and have the full signal available before detection runs. It is not suited for real-time or streaming applications, since the off-line design means all data must be collected first. Before using it on a new domain, choose the penalty parameter deliberately with domain knowledge, because the library does not select it automatically and the pen=10 in the example code is a starting point that may not fit your signal.

Frequently asked questions

Official sources

1. deepcharles/ruptures on GitHub
2. Issues
3. License: BSD-2-Clause
4. README
5. Releases