Metadata-Version: 2.4
Name: changepoynt
Version: 0.1.2
Summary: Change point / changepoint detection for time series in Python (Singular Spectrum Transformation - SST, IKA-SST, ulSIF, RuLSIF, KLIEP, FLUSS, FLOSS, etc.). Focus on efficient implementation and readable code.
Home-page: https://github.com/Lucew/changepoynt
Author: Lucas Weber
Author-email: Lucas Weber <weber-lucas@web.de>
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://github.com/Lucew/changepoynt
Project-URL: Issues, https://github.com/Lucew/changepoynt/issues
Project-URL: Source, https://github.com/Lucew/changepoynt
Project-URL: Changelog, https://github.com/Lucew/changepoynt/releases
Keywords: change point detection,changepoint detection,change-point detection,change detection,structural break,regime shift,time series,time-series,timeseries,time series analysis,segmentation,anomaly detection,concept drift,drift detection,online detection,streaming,Singular Spectrum Transformation,SST,IKA-SST,density ratio estimation,uLSIF,RuLSIF,KLIEP,matrix profile,FLUSS,FLOSS
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23.5
Requires-Dist: numba>=0.56.4
Requires-Dist: scipy>=1.10.1
Requires-Dist: fbpca>=1.0
Requires-Dist: matplotlib>=3.7.1
Requires-Dist: stumpy>=1.11.1
Requires-Dist: rocket-fft
Provides-Extra: test
Requires-Dist: pytest>=7.2.2; extra == "test"
Requires-Dist: numpy>=1.23.5; extra == "test"
Requires-Dist: numba>=0.56.4; extra == "test"
Requires-Dist: scipy>=1.10.1; extra == "test"
Requires-Dist: fbpca>=1.0; extra == "test"
Requires-Dist: stumpy>=1.11.1; extra == "test"
Requires-Dist: rocket-fft; extra == "test"
Provides-Extra: example
Requires-Dist: pytest>=7.2.2; extra == "example"
Requires-Dist: numpy>=1.23.5; extra == "example"
Requires-Dist: numba>=0.56.4; extra == "example"
Requires-Dist: scipy>=1.10.1; extra == "example"
Requires-Dist: seaborn>=0.12.2; extra == "example"
Requires-Dist: jupyter>=1.0.0; extra == "example"
Requires-Dist: fbpca>=1.0; extra == "example"
Requires-Dist: stumpy>=1.11.1; extra == "example"
Requires-Dist: rocket-fft; extra == "example"
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# Python Changepoint Detection (changepoynt)
[![PyPI version](https://img.shields.io/pypi/v/changepoynt?color=%2376519B)](https://pypi.org/project/changepoynt/)
[![License](https://img.shields.io/pypi/l/changepoynt?color=%2376519B)](https://opensource.org/licenses/BSD-2-Clause)
[![python](https://img.shields.io/pypi/pyversions/changepoynt?color=%2376519B)](https://pypi.org/project/changepoynt/)
[![downloads](https://img.shields.io/pypi/dm/changepoynt?color=%2376519B)](https://pypi.org/project/changepoynt/)

**changepoynt** is a Python library for change point detection / changepoint detection in time series (offline and online).
It includes Singular Spectrum Transformation (SST, IKA-SST, ESST), density-ratio change detection (uLSIF, RuLSIF), 
and matrix-profile segmentation (FLUSS, FLOSS).

Start using it:
```bash
pip install changepoynt
```
or
```bash
uv pip install changepoynt
```


**Table of content:**
 - [Quickstart](#quickstart)
 - [Examples](#examples)
 - [Algorithms](#algorithms)
 - [Installation](#installation)
 - [Contributing](#contributing)
 - [Known Issues](#known-issues)
 - [Outlook](#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 <a id="quickstart"></a>
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:

```python
import numpy as np
import matplotlib.pyplot as plt
from changepoynt.algorithms.esst import ESST
from changepoynt.algorithms.sst import SST
from changepoynt.visualization.score_plotting import plot_data_and_score

# create a signal that goes from steady to exponential decline into a sine curve
exp_signal = np.exp(-np.linspace(0, 5, 200))
steady_after = np.exp(-5)*np.ones(150)
steady_before = np.ones(200)
sine_after = 0.2*np.sin(np.linspace(0, 3*np.pi*10, 300))

# make the signal
signal = np.concatenate((steady_before, exp_signal, steady_after, sine_after))
signal += 0.01*np.random.randn(signal.shape[0])

# make change point detection
esst_detector = ESST(40)
esst_detection = esst_detector.transform(signal)

# make change point detection
sst_detector = SST(40, method='rsvd', mitigate_offset=True)
sst_detection = sst_detector.transform(signal)

# make the plot
plot_data_and_score(signal, esst_detection)
plt.gcf().tight_layout()
plot_data_and_score(signal, sst_detection)
plt.gcf().tight_layout()
plt.show()
```

The result looks like this:

**ESST**:
![image](https://github.com/Lucew/changepoynt/raw/master/images/minimal_example_result_esst.png)
**SST**:
![image](https://github.com/Lucew/changepoynt/raw/master/images/minimal_example_result_sst.png)

# Examples <a id="examples"></a>

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](https://github.com/Lucew/changepoynt/blob/master/changepoynt/algorithms/esst.py) or [SST](https://github.com/Lucew/changepoynt/blob/master/changepoynt/algorithms/sst.py). If you want to use the 
algorithms on the contents of a CSV directly, there is a frontend demonstrator currently hosted 
[here](https://demo.changepoynt.de/) (the adress is https://demo.changepoynt.de/, the 
code for the demonstrator is [here](https://github.com/Lucew/changepoynt/tree/master/frontend)).

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.

![image](https://github.com/Lucew/changepoynt/raw/master/images/simulated_temperature_behavior.png)

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](https://www.cs.ucr.edu/~eamonn/time_series_data_2018/), where we
set the window size for the ESST to three times the estimated period in samples (estimated using maximum of FFT).

![image](https://github.com/Lucew/changepoynt/raw/master/images/034_UCR_Anomaly_DISTORTEDInternalBleeding6_1500_3474_3629.png)
 
Both plots have been created using `changepoynt.algorithms.esst` and the plot function from 
`changepoynt.visualization.score_plotting`.

# Installation <a id="installation"></a>

You can install `changepoynt` from the common package index [PyPi](https://pypi.org/project/changepoynt/) 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](https://www.cs6.tf.fau.de/person/lucas-weber/). 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](https://github.com/Lucew/changepoynt/blob/master/docs/FAQ.md) in the related Markdown 
[document](https://github.com/Lucew/changepoynt/blob/master/docs/FAQ.md).

# Algorithms <a id="algorithms"></a>

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é](https://epubs.siam.org/doi/abs/10.1137/1.9781611972757.63)                   | Stable  :heavy_check_mark:  |
| [Fast SST](https://github.com/Lucew/changepoynt/blob/master/docs/fast-sst.md)     | [Weber et al.](https://doi.org/10.1109/ACCESS.2025.3640386)                        | Stable  :heavy_check_mark:  |
| IKA-SST                                                                           | [Idé](https://epubs.siam.org/doi/abs/10.1137/1.9781611972771.54)                   | Stable  :heavy_check_mark:  |
| [Fast IKA-SST](https://github.com/Lucew/changepoynt/blob/master/docs/fast-sst.md) | [Weber et al.](https://doi.org/10.1109/ACCESS.2025.3640386)                    | Stable  :heavy_check_mark:  |     
| ESST                                                                              | [Boelter & Weber et al.](https://ntrs.nasa.gov/citations/20250002705)              | Stable :heavy_check_mark:   |
| RuLSIF                                                                            | [Liu et al.](https://www.sciencedirect.com/science/article/pii/S0893608013000270)  | Stable  :heavy_check_mark:  |
| uLSIF                                                                             | [Liu et al.](https://www.sciencedirect.com/science/article/pii/S0893608013000270)  | Stable  :heavy_check_mark:  |
| KLIEP                                                                             | [Liu et al.](https://www.sciencedirect.com/science/article/pii/S0893608013000270)  | Planned                     |
| ClaSP                                                                             | [Ermshaus et al.](https://link.springer.com/article/10.1007/s10618-023-00923-x)    | Deactivated :x:             |
| FLUSS                                                                             | [Gharghabi et al.](https://ieeexplore.ieee.org/abstract/document/8215484)          | Stable :heavy_check_mark:   |
| FLOSS                                                                             | [Gharghabi et al.](https://ieeexplore.ieee.org/abstract/document/8215484)          | Stable :heavy_check_mark:   |
| BOCPD                                                                             | [Adams et al.](https://arxiv.org/abs/0710.3742)                                    | Experimental (mean change)  |
| Baseline                                                                          | Weber                                                                              | Stable :heavy_check_mark:   |


# Contributing <a id="contributing"></a>
The main way of contributing to this package is by opening an issue or a pull request. We are happy to answer answer
any questions you might have in an issue.

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.

# Known Issues <a id="known-issues"></a>

### 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.

# Outlook <a id="outlook"></a>

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

- Researching intuitive explanations for SST parametrization
- Setting up a documentation
- Guideline for online deployment of the methods

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