changepoynt 0.1.1

Efficient and readable change point detection package implemented in Python. (Singular Spectrum Transformation - SST, IKA-SST, ulSIF, RuLSIF, KLIEP, FLUSS, FLOSS, etc.)

Python Changepoint Detection (changepoynt)

Table of content:

• Quickstart
• Examples
• Algorithms
• Installation
• Contributing
• Known Issues
• Outlook

This is the repository hosting the pip-installable python package changepoynt. It implements several change point detection techniques, while focusing mostly on "localized" algorithms, that could be run in an online fashion.

Current algorithms come from the field of:

• Subspace Estimation (Extracting the characteristic signals)

• Statistics (Detection of Change in the statistical properties)

• Time Series Segmentation (Algorithms focused on comparing time series shape)

The package is aimed at execution performance (using JIT compilation and standing on the shoulders of giants like numpy and scipy) while also keeping code readable and maintainable. This includes comments as well as architectural choices. This might not be perfect, but we are trying!

All of our algorithms are implementations of a base changepoint detection interface and therefore are interchangeable. Currently, we are focused on shifting to the very common and existing sklearn interface of fit and transform. This enables our algorithms to be part of the standard sklearn pipeline for preprocessing.

Quick Start

If you want to start using the package right away, we recommend using one of the singular spectrum transformation algorithms (SST). The first step is to install the package using pip. Then you can use the following example code:

import numpy as np  # for signal creation
import matplotlib.pyplot as plt  # to show the plot
from changepoynt.algorithms.esst import ESST  # import the scoring algorithm
from changepoynt.visualization.score_plotting import plot_data_and_score  # import a visualization function

# simulate a signal that goes from exponential decline into a sine wave
# the signals is only for demonstration purposes and can be replaced by your signal
steady_before = np.ones(200)
exp_signal = np.exp(-np.linspace(0, 5, 200))
steady_after = np.exp(-5)*np.ones(150)
sine_after = 0.2*np.sin(np.linspace(0, 3*np.pi*10, 300))
signal = np.concatenate((steady_before, exp_signal, steady_after, sine_after))
signal += 0.01*np.random.randn(signal.shape[0])  # add some minor noise

# This part is all you need to do to score a signal with our package 
# create the scorer and compute the change score
detector = ESST(30)
detection = detector.transform(signal)

# make the plot using the built-in function of the package                                               
plot_data_and_score(signal, detection)
plt.show()

The result looks like this:

Examples

You can find example code within the examples folder of this repository. We also wanted to tease the functionality using two different signals in order to show the capabilities of one of our recommended algorithms ESST. If you want to use the algorithms on the contents of a CSV directly, there is a frontend demonstrator currently hosted here (the adress is https://demo.changepoynt.de/, the code for the demonstrator is here).

The first application is a simulated temperature of a component in a power plant during shutdown. We artificially added a disturbance at the end of the shutdown, to show the capability of the algorithm to detect a change even in case of another major change.

The other application is for anomaly detection within periodic signals. The example is time series 34 from the Hexagon ML/UCR Time Series Anomaly Detection dataset, where we set the window size for the ESST to three times the estimated period in samples (estimated using maximum of FFT).

Both plots have been created using changepoynt.algorithms.esst and the plot function from changepoynt.visualization.score_plotting.

Installation

You can install changepoynt from the common package index PyPi using the following line with pip:

pip install changepoynt

Please be aware that we are currently in an alpha development phase, as this is part of a research project at the FAU Erlangen together with SIEMENS Energy developed by me. Nevertheless, we aim to be open-source and try our best to guarantee that all the code we use has very permissive licenses.

You can also install the code from source using the following line

pip install git+https://github.com/Lucew/changepoynt.git

Frequently Asked Questions (FAQ)

Find the FAQs in the related Markdown document.

Algorithms

We are actively working on the package. Therefore, some algorithms are already available, while others are currently under development. An overview with sources can be seen here:

Algorithm	Source	Status
SST	Idé	Stable :heavy_check_mark:
Accelerated SST	Weber et al.	Stable :heavy_check_mark:
IKA-SST	Idé	Stable :heavy_check_mark:
Accelerated IKA-SST	Weber et al.	Stable :heavy_check_mark:
ESST	Boelter & Weber et al.	Stable :heavy_check_mark:
RuLSIF	Liu et al.	Stable :heavy_check_mark:
uLSIF	Liu et al.	Stable :heavy_check_mark:
KLIEP	Liu et al.	Planned
ClaSP	Ermshaus et al.	Deactivated :x:
FLUSS	Gharghabi et al.	Stable :heavy_check_mark:
FLOSS	Gharghabi et al.	Stable :heavy_check_mark:
BOCPD	Adams et al.	Experimental (mean change)
Baseline	Weber	Stable :heavy_check_mark:

Contributing

We always love to get feedback or new ideas. If you have any of those, feel free to open an issue. We try to get back to you as soon as we can.

If you are an author of a paper in the field or have another algorithmic idea: Feel free to open a pull request. Currently, we are still working on the contribution guides. But if somebody already comes along and has an idea, we do not want to be in the way!

Known Issues

Division by Zero for SST with IKA

Some of the methods like SST (with method='ika') and (R)uLSIF have issues when running for trivial sections of time series. This includes steady series (e.g., only zero values, just lines with some slope). Intuitively, these methods aim to extract multiple characteristics in these sections but there are none, so they run into issues. Errors you will encounter are: "Matrix is singular" or "division by zero". Unfortunately, the math behind these errors is more complicated and I have not yet found a good way to circumvent these errors.

Fortunately, there is an easy workaround. Just add a small white noise to your signal, e.g. by adding signal += np.random.normal(0, 1e-4, size=signal.shape[0]). With noise much smaller than you signal you will not introduce large additional change points and the methods will not fail.

Python 3.13 not supported for all methods

We are aware that some dependencies currently are not supporting Python 3.13 and higher. These packages are mostly used for the fast_hankel option, and we are currently checking whether to make those packages optional.

Outlook

We are actively working on the package, and currently have the following steps planned:

• We are actively working on a benchmark tool for change point algorithms
• Implement Bayesian online change point detection

If you have further ideas, do not hesitate to open a ticket or a pull request!