Getting started

This quick guide shows how to install tsseg, load a time series and run a segmentation detector. The instructions assume Python 3.10+ and a virtual environment.

Installation

This library relies on a robust environment. It is recommended to use conda or mamba.

# Clone the repository
git clone https://github.com/fchavelli/tsseg.git
cd tsseg

# Install the environment using the provided makefile
make install
conda activate tsseg-env

If you prefer pip and want to install it as a library in an existing environment:

pip install -e .[all]

Basic usage

This example demonstrates how to use AutoPlaitDetector, an unsupervised algorithm for regime discovery.

import numpy as np
from tsseg.algorithms import AutoPlaitDetector

# Generate a toy signal
rng = np.random.default_rng(42)
seg_lengths = [200, 150, 250]
segments = [rng.normal(mu, 0.2, length) for mu, length in zip([-0.5, 0.8, 0.0], seg_lengths)]
series = np.concatenate(segments)[:, None]  # shape (n_points, n_channels)

# Run the detector
# Note: We initialize the detector with any necessary parameters.
# Unsupervised algorithms do not use 'y' in fit().
model = AutoPlaitDetector()
state_labels = model.fit_predict(series)
print(np.unique(state_labels, return_counts=True))

Most detectors expose the fit, predict, and fit_predict methods and share metadata tags (see Detectors).

Semi-supervised usage

If an algorithm supports semi-supervised learning (check its semi_supervised tag), you can pass labels to fit:

# Example for a semi-supervised detector
# model = SomeSemiSupervisedDetector(n_states=3)
# model.fit(X, y=labels)
# preds = model.predict(X)

Important: Do not pass y to fit if you intend to run in unsupervised mode. Previous versions might have inferred parameters from y; this is no longer supported. Explicitly set parameters like n_segments or n_states in the constructor.

Running the test suite

To ensure your environment is healthy:

make test

Or directly:

pytest tests/