Metadata-Version: 2.4
Name: tsseg
Version: 0.1.0
Summary: A library for time series segmentation
Author: Félix Chavelli
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/fchavelli/tsseg
Project-URL: Repository, https://github.com/fchavelli/tsseg
Project-URL: Documentation, https://fchavelli.github.io/tsseg/
Project-URL: Issues, https://github.com/fchavelli/tsseg/issues
Project-URL: Changelog, https://github.com/fchavelli/tsseg/blob/main/docs/changelog.rst
Keywords: time-series,segmentation,change-point,machine-learning
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: pooch
Requires-Dist: tqdm
Requires-Dist: joblib
Requires-Dist: statsmodels
Requires-Dist: future
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: prophet
Requires-Dist: prophet; extra == "prophet"
Provides-Extra: patss
Provides-Extra: legacy-hsmm
Provides-Extra: accelerators
Requires-Dist: numba; extra == "accelerators"
Requires-Dist: cython; extra == "accelerators"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.2; extra == "docs"
Provides-Extra: aeon
Requires-Dist: aeon; extra == "aeon"
Provides-Extra: tscp2
Requires-Dist: tensorflow<2.19,>=2.16; extra == "tscp2"
Requires-Dist: keras-tcn<3.6,>=3.5.0; extra == "tscp2"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: black>=24.8; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Provides-Extra: all
Requires-Dist: tsseg[accelerators,aeon,docs,prophet,tglad,torch,tscp2]; extra == "all"
Provides-Extra: tglad
Requires-Dist: torch>=2.0; extra == "tglad"
Requires-Dist: networkx>=3.0; extra == "tglad"
Dynamic: license-file

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