tsseg 0.3.0

Time series segmentation in Python
Change point detection and state detection: 30+ algorithms, one scikit-learn-style API

Documentation · Live demo · Detectors · Metrics · Changelog

What is tsseg?

tsseg gathers classic and recent algorithms for time series segmentation behind a single API, with the metrics to evaluate them and an interactive demo to compare them. It covers the two faces of the problem:

_{A motion-capture recording bundled with tsseg, as shown in the interactive demo: ground truth (top), the change points of a change point detector (middle) and the states of a state detector (bottom).}

Highlights

• One API for every method. Each detector is a scikit-learn estimator that follows the segmenter interface of aeon: fit, predict, fit_predict, get_params, clone.
• Unsupervised or guided. Run a detector without knowing how many segments to expect, or pass the number of change points or states to its constructor when you know it. Tags tell which modes each detector supports.
• Metrics for both tasks. F1, covering, Hausdorff distance and Gaussian F1 for change points; ARI, AMI, NMI, their time sensitive counterparts, and the interpretable SMS for states.
• Light core, opt-in extras. The core needs NumPy, pandas, SciPy, scikit-learn and statsmodels. PyTorch, TensorFlow, Prophet or numba are installed only for the detectors that use them.
• Fast classics. PELT, BinSeg, BottomUp, DynP and Window run on a vendored copy of ruptures with an optional numba backend.
• Try it in the browser. The interactive demo loads a custom series, runs the detectors and compares their results, with nothing to install.

Installation

pip install tsseg

Most detectors work with this alone. Those built on heavier libraries need an extra, for instance pip install "tsseg[torch]", or all of them at once with pip install "tsseg[all]":

FLUSSDetector needs stumpy (pip install stumpy), and AutoPlaitDetector a C binary built from c/autoplait (see its documentation page). The tsseg[patss] extra installs nothing: the deprecated PatssDetector needs npbad, which is not on PyPI and must be installed by hand.

git clone https://github.com/fchavelli/tsseg.git
cd tsseg
make install          # creates the conda env and installs tsseg
conda activate tsseg-env

conda env create -f environment.yml
conda activate tsseg-env
pip install -e ".[all]"

pip install -e ".[torch,prophet,aeon,accelerators]"

Quick start

Segment a motion-capture recording, then score both results against its ground truth (the state detector needs pip install "tsseg[accelerators,aeon]"):

from tsseg import load_mocap
from tsseg.algorithms import BottomUpDetector, ClapDetector
from tsseg.algorithms.utils import extract_cps
from tsseg.metrics import Covering, StateMatchingScore

# 4 channels (arms and legs), one activity label per time point
X, y = load_mocap(trial=0)  # X: (4579, 4), y: (4579,)
true_cps = extract_cps(y)  # [ 588 1200 2006 2530 3282 4048]

# Change point detection: where does the movement change?
cps = BottomUpDetector(model="rbf", pen_scale="bic").fit_predict(X)
print(cps)  # [ 580 1125 2050 2465 3995]
print(Covering().compute(true_cps, cps, n_timepoints=len(X))["score"])  # 0.748

# State detection: which activity is each time point in?
states = ClapDetector().fit_predict(X)
print(StateMatchingScore().compute(y, states)["score"])  # 0.700

Know how many segments to expect? Pass it to the constructor (guided mode):

from tsseg.algorithms import DynpDetector

print(DynpDetector(model="rbf", n_cps=6).fit_predict(X))
# [ 595 1145 2160 2455 3300 4115]

Detectors accept NumPy arrays of shape (n_timepoints, n_channels) (or 1-D for univariate series), pandas Series and DataFrames. The getting started guide goes further.

Algorithms

Unsup.: runs without being told the number of change points or states. Guided: takes that number in its constructor (n_cps, n_states, …). 📦: needs an optional dependency (see Installation). Each name links to the documentation page of the detector.

Also available: RandomDetector, a random baseline for both tasks.

Evaluation metrics

Every metric returns a dictionary with at least a "score" key: metric.compute(y_true, y_pred)["score"].

Change point detection, on sorted change point indices:

Tip: these metrics need the length of the series: pass compute(y_true, y_pred, n_timepoints=len(X)).

State detection, on one label per time point:

WARI, WNMI and SMS come from Toward Interpretable Evaluation Measures for Time Series Segmentation (NeurIPS 2025).

Interactive demo

The tsseg demo on Hugging Face Spaces runs in the browser: load a series, run segmentation algorithms, then compare and evaluate their results, with nothing to install.

Contributing

Bug reports, questions and new detectors are welcome in the issues. From a clone:

make test                                # run the test suite, as in CI (long)
make test PYTEST_ARGS="-k PeltDetector"  # run a selection of tests
make lint                                # ruff check + ruff format --check, as in CI
make docs                                # build the documentation, as in CI (needs tsseg[docs])

The contributing guide covers the development setup, the code style and the tests a new detector must pass.

Citation

If tsseg helps your work, please cite the ECML-PKDD 2026 paper:

@inproceedings{tsseg2026,
  title     = {tsseg: An Interactive Toolkit for Time Series Segmentation},
  author    = {Chavelli, F{\'e}lix and Ermshaus, Arik and Yang, Fan and Sch{\"a}fer, Patrick and Paparrizos, John and Boniol, Paul},
  booktitle = {Machine Learning and Knowledge Discovery in Databases. Applied Data Science Track, Demo Track and Industrial Track},
  series    = {Lecture Notes in Computer Science},
  year      = {2026},
  pages     = {391--394},
  publisher = {Springer Nature Switzerland},
  doi       = {10.1007/978-3-032-37685-5_41}
}

If you use WARI, WNMI or SMS, please also cite:

@inproceedings{chavelli2025interpretable,
  title     = {Toward Interpretable Evaluation Measures for Time Series Segmentation},
  author    = {Chavelli, F{\'e}lix and Boniol, Paul and Thomazo, Micha{\"e}l},
  booktitle = {Advances in Neural Information Processing Systems},
  year      = {2025}
}

Each detector also cites its original paper on its documentation page.

Contributors

• Félix Chavelli (Inria, ENS, Paris)
• Arik Ermshaus (Humboldt-Universität, Berlin)
• Fan Yang (The Ohio State University, Columbus)
• Paul Boniol (Inria, ENS, Paris)
• Patrick Schäfer (Humboldt-Universität, Berlin)
• John Paparrizos (The Ohio State University, AUTh, Columbus)

License

tsseg is released under the AGPL-3.0.

Third-party components

Several algorithms bundle adapted or vendored code under their own licenses.