Metadata-Version: 2.4
Name: time-series-homology
Version: 0.1.0
Summary: Persistent homology of time series via horizontal and non-horizontal filtrations.
Author-email: m-a-huber <mariushuber2@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/m-a-huber/time-series-homology
Project-URL: Issues, https://github.com/m-a-huber/time-series-homology/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gudhi>=3.11.0
Requires-Dist: numpy>=2.4.4
Requires-Dist: scikit-learn>=1.8.0
Dynamic: license-file

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

```bash
pip install -U time-series-homology
```

Install from source:

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

## Quick start

```python
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:

```python
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
