time-series-homology

Compute persistent homology for univariate or multivariate time series using horizontal and non-horizontal filtrations, as described in [1] and [2], respectively.

The main entry point is tsh.TimeSeriesHomology, which largely follows the API conventions from scikit-learn.

Installation

Install from PyPI:

pip install -U time-series-homology

Install from source:

git clone https://github.com/m-a-huber/time-series-homology.git
cd time-series-homology
pip install -e .

Quick start

import numpy as np
from tsh import TimeSeriesHomology

# A univariate time series represented as (time, value) pairs
t = np.linspace(0, 4 * np.pi, 200)
ts = np.column_stack([t, np.sin(t)])

model = TimeSeriesHomology(
    filtration_type="horizontal",
    use_extended_persistence=True,
)

# Input is a list of time series; each element is an array of shape
# (n_time_steps, n_features + 1), where column 0 is time.
persistence = model.fit_transform([ts])

Input and output format

Input:

• A list of arrays, where each array has shape (n_time_steps, n_features + 1);
• column 0 stores time values; and
• columns 1 through n store the signal coordinates.

Output:

• An object of type list[list[list[list[np.ndarray]]]], where the first axis indexes input time series;
• the second axis indexes signal coordinates (that is, columns 1 through n in each input array);
• the third axis indexes diagram families (ordinary/relative/essential for extended persistence, ordinary only otherwise); and
• the fourth axis indexes homology dimensions, so that the array at index i contains (birth, death) pairs for homology dimension i.

When use_extended_persistence=True, each coordinate returns three diagram families (ordinary, relative, essential). Otherwise, ordinary persistence is used and it returns one family.

Key parameters

• filtration_type: one of horizontal, sloped, sigmoid, arctan
• slope: controls the non-horizontal sweeping function for sloped/sigmoid/arctan
• padding_factor: stabilization padding used by sigmoid and arctan
• use_extended_persistence: switch between extended and ordinary persistence
• min_persistence: persistence threshold for filtering generators
• drop_inf_persistence: drop infinite-lifespan generators for ordinary persistence output
• n_jobs: parallel processing setting via joblib

For details, use:

from tsh import TimeSeriesHomology
help(TimeSeriesHomology)

References

[1] Lara Ost, Sebastiano Cultrera di Montesano, and Herbert Edelsbrunner. Banana Trees for the Persistence in Time Series Experimentally. 41st International Symposium on Computational Geometry (SoCG 2025). https://doi.org/10.4230/LIPIcs.SoCG.2025.71

[2] Marius Huber, David Robert Reich, and Lena Ann Jäger. 2026. Fixation Sequences as Time Series: A Topological Approach to Dyslexia Detection. In Proceedings of the 2026 Symposium on Eye Tracking Research and Applications (ETRA '26). Association for Computing Machinery, New York, NY, USA, Article 12, 1–13. https://doi.org/10.1145/3797246.3803045