tsseg - Time Series Segmentation

tsseg is a Python library for Time Series Segmentation, covering both Change Point Detection and State Detection. It bundles 30+ segmentation algorithms, evaluation metrics, data loaders, and real-world benchmark datasets under a unified API.

Segmentation algorithms share the same base class interface as the aeon time series toolkit, making them interoperable with the broader aeon ecosystem. Several aeon segmenters are also re-exposed through tsseg for convenience.

Quick Start

from tsseg.data.datasets import load_mocap
from tsseg.algorithms import ClapDetector
from tsseg.metrics import StateMatchingScore

# Load a time series
X, y_true = load_mocap(trial=0)

# Segment
segmenter = ClapDetector()
segmenter.fit(X)
y_pred = segmenter.predict(X)

# Evaluate
score = StateMatchingScore().compute(y_true, y_pred)
print(f"SMS: {score['score']:.4f}")

📖 Documentation: fchavelli.github.io/tsseg

Interactive Demo

An interactive demo of tsseg is available here, powered by Hugging Face Spaces. You can use it directly in your browser to load data, run segmentation algorithms, compare, and evaluate results.

Installation

From PyPI

pip install tsseg

With optional extras:

pip install tsseg[torch]       # PyTorch-based detectors
pip install tsseg[all]         # all optional dependencies

From source

Requires: conda in your PATH (or set it in a .env file — see .env.example).

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

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

conda env create -f environment.yml
conda activate tsseg-env
pip install -e .[torch,prophet,aeon]   # pick only the extras you want

Optional extras

Most detectors work out of the box. Heavier dependencies are opt-in:

Contributing

make test       # run the test suite
make lint       # check style and linting rules with Ruff
make docs       # build the documentation locally

See the Contributing Guide for full instructions.

License

AGPLv3 — see the LICENSE file for details.

Third-party components

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

Each vendored directory contains a LICENSE file with full terms.

Citation

If you use this work, please consider citing the associated paper:

@inproceedings{chavelli:hal-05654218,
  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},
  URL = {https://inria.hal.science/hal-05654218},
  BOOKTITLE = {{ECML-PKDD 2026 - European Conference on Machine Learning and Principles and Practice of Knowledge Discovery in Databases}},
  ADDRESS = {Naples, Italy},
  YEAR = {2026},
  MONTH = Sep
}

Contributors

• Felix 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)