# tsseg - Time Series Segmentation

<p align="center">
  <img src="assets/logo_white.png" alt="tsseg logo" width="200px">
</p>

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="https://github.com/fchavelli/tsseg/releases/tag/v0.1.0"><img src="https://img.shields.io/github/v/tag/fchavelli/tsseg?label=version&style=for-the-badge&logo=github" alt="Version"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=for-the-badge" alt="Ruff"></a>
  <a href="https://fchavelli.github.io/tsseg/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=for-the-badge&logo=github" alt="Documentation"></a>
  <a href="https://github.com/fchavelli/tsseg/blob/main/LICENSE"><img src="https://img.shields.io/github/license/fchavelli/tsseg?color=blue&style=for-the-badge" alt="License"></a>
</p>

**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](https://github.com/aeon-toolkit/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

```python
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, axis=0)
y_pred = segmenter.predict(X)

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

📖 **Documentation:** [fchavelli.github.io/tsseg](https://fchavelli.github.io/tsseg/)

## Installation

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

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

<details>
<summary><strong>Manual installation</strong></summary>

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

</details>

<details>
<summary><strong>Lightweight install (no TensorFlow)</strong></summary>

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

```bash
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.

</details>

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

```bash
make test       # run the test suite
make lint       # check style with ruff
make docs       # build the documentation locally
```

See the [Contributing Guide](https://fchavelli.github.io/tsseg/guides/contributing.html) for full instructions.

## License

[AGPLv3](LICENSE) — 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](https://github.com/aeon-toolkit/aeon) |
| `ruptures/` (vendored v1.1.8) | BSD-2 | [deepcharles/ruptures](https://github.com/deepcharles/ruptures) |
| `bocd/` | Apache-2.0 | [hildensia/bayesian_changepoint_detection](https://github.com/hildensia/bayesian_changepoint_detection) |
| `clap/` (ClaSP / CLaP) | BSD-3 | [ermshaua/clasp](https://github.com/ermshaua/clasp) |
| `ggs/` | BSD-2 | [cvxgrp/GGS](https://github.com/cvxgrp/GGS) |
| `icid/` | GPLv3 | [IsolationKernel/iCID](https://github.com/IsolationKernel/iCID) |
| `patss/` | MIT | [KU Leuven DTAI](https://gitlab.kuleuven.be/u0143709/patss) |
| `tglad/vendor/` (uGLAD) | Non-Commercial | [Harshs27/tGLAD](https://github.com/Harshs27/tGLAD) |
| `tirex/` (via tsseg-tirex) | [NXAI Community License](https://github.com/NX-AI/tirex/blob/main/LICENSE) | [NX-AI/tirex](https://github.com/NX-AI/tirex) |
| `autoplait/` | not specified | [Matsubara et al.](https://sites.google.com/site/onlinesemanticsegmentation/) |
| `e2usd/` | not specified | [AI4CTS/E2Usd](https://github.com/AI4CTS/E2Usd) |
| `espresso/` | not specified | [cruiseresearchgroup/ESPRESSO](https://github.com/cruiseresearchgroup/ESPRESSO) |
| `ticc/` | not specified | [davidhallac/TICC](https://github.com/davidhallac/TICC) |
| `time2state/` | not specified | [Lab-ANT/Time2State](https://github.com/Lab-ANT/Time2State) |
| `tire/` | not specified | [De Ryck, De Vos & Bertrand (KU Leuven)](https://github.com/deryckt/TIRE) |
| `tscp2/` | not specified | [Cruise Research Group](https://github.com/cruiseresearchgroup/TSCP2) |

Each vendored directory contains a LICENSE file with full terms.
The TiRex integration is built with technology from [NXAI](https://nx-ai.com).
