tsseg — Time Series Segmentation

tsseg logo

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.

Overview

The library is organised around three concepts:

  • Datasets — loaders for the bundled and external benchmark datasets.

  • Detectors — 30+ change-point and state-detection algorithms exposed through a single fit / predict / fit_predict API.

  • Evaluation — evaluation metrics for both change-point and state-labelling tasks.

An interactive demo is available on Hugging Face Spaces.

Installation

From PyPI:

pip install tsseg

With optional extras:

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

From source (requires conda):

git clone https://github.com/fchavelli/tsseg.git
cd tsseg
make install
conda activate tsseg-env

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

Extra

What it adds

tsseg[aeon]

Compatibility helpers for the aeon ecosystem

tsseg[prophet]

Facebook Prophet (ProphetDetector)

tsseg[patss]

Bayesian HSMM dependencies (PatssDetector)

tsseg[torch]

PyTorch-based detectors (TireDetector, Time2StateDetector)

tsseg[tglad]

PyTorch + NetworkX (TGLADDetector)

tsseg[tscp2]

TensorFlow + TCN layer (TSCP2Detector)

tsseg[accelerators]

Numba / Cython speedups

tsseg[docs]

Sphinx documentation toolchain

tsseg[all]

Everything above

Usage

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}")

See Getting started for a longer walk-through.

License

tsseg is released under the AGPLv3.

Several detectors bundle adapted or vendored code under their own licenses (BSD, MIT, Apache-2.0, GPLv3, etc.). Each vendored directory contains a LICENSE file with the full terms.

Citation

If you use tsseg in academic work, please cite:

@software{tsseg,
  author  = {Chavelli, F\'elix and contributors},
  title   = {tsseg: a Python library for time-series segmentation},
  year    = {2026},
  url     = {https://github.com/fchavelli/tsseg},
  version = {<package version>},
}

Note

A reference publication is in preparation; the BibTeX entry above is a placeholder and will be updated when the paper is available.

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)

Contributions are welcome — see Contributions for development setup, code style and testing guidelines.

Indices