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

Manual installation

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

Lightweight install (no TensorFlow)

If TensorFlow causes issues on your platform, skip the [all] extra and install only the pieces you need:

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

Only TSCP2Detector requires TensorFlow (tsseg[tscp2]). All other 27+ algorithms work without it.

Optional extras

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 doc toolchain
tsseg[all]	Everything above

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:

Component	License	Source
aeon (base, EAgglo, Hidalgo, HMM, IGTS)	BSD-3	aeon-toolkit/aeon
ruptures/ (vendored v1.1.8)	BSD-2	deepcharles/ruptures
bocd/	Apache-2.0	hildensia/bayesian_changepoint_detection
clap/ (ClaSP / CLaP)	BSD-3	ermshaua/clasp
ggs/	BSD-2	cvxgrp/GGS
icid/	GPLv3	IsolationKernel/iCID
patss/	MIT	KU Leuven DTAI
tglad/vendor/ (uGLAD)	Non-Commercial	Harshs27/tGLAD
autoplait/	not specified	Matsubara et al.
e2usd/	not specified	AI4CTS/E2Usd
espresso/	not specified	cruiseresearchgroup/ESPRESSO
ticc/	BSD-2	davidhallac/TICC
time2state/	MIT	Lab-ANT/Time2State
tire/	not specified	De Ryck, De Vos & Bertrand (KU Leuven)
tscp2/	not specified	Cruise Research Group

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)