delay-embedding

Delay embedding (Takens' embedding) for multidimensional time series data in Python.

Features

• Multivariate support — handles both univariate (T,) and multivariate (T, d) time series natively
• Inverse transform — reconstruct the original time series from the embedded matrix (averaging-based approximation)
• Automatic parameter optimization — dimension="auto" and delay="auto" estimate optimal parameters from data
  • Optimal delay via Auto Mutual Information (AMI) first minimum
  • Optimal embedding dimension via False Nearest Neighbours (FNN)
• scikit-learn compatible — BaseEstimator / TransformerMixin API, works in Pipeline (optional dependency)
• Lightweight — core dependency is NumPy only
• Fast — vectorized NumPy fancy indexing, faster than giotto-tda with numerically identical results

Installation

pip install git+https://github.com/Taiyou/delay-embedding.git

With scikit-learn integration:

pip install "delay-embedding[sklearn] @ git+https://github.com/Taiyou/delay-embedding.git"

Quick Start

import numpy as np
from delay_embedding import DelayEmbedding

# Automatic optimization (recommended)
t = np.linspace(0, 10 * np.pi, 1000)
ts = np.column_stack([np.sin(t), np.cos(t)])

emb = DelayEmbedding(dimension="auto", delay="auto")
embedded = emb.fit_transform(ts)
print(f"tau={emb.delay_}, m={emb.dimension_}")

# Manual parameters
emb = DelayEmbedding(dimension=3, delay=5)
embedded = emb.transform(ts)

# Inverse transform
reconstructed = emb.inverse_transform(embedded, d=2)

scikit-learn Pipeline

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler

pipe = Pipeline([
    ("embed", DelayEmbedding(dimension="auto", delay="auto")),
    ("scale", StandardScaler()),
])
result = pipe.fit_transform(ts)

API

DelayEmbedding(dimension=2, delay=1)

Parameter	Type	Default	Description
dimension	int or "auto"	2	Embedding dimension m. "auto" estimates via FNN
delay	int or "auto"	1	Time delay tau. "auto" estimates via AMI

Methods:

Method	Description
fit(X)	Estimate "auto" parameters from data. Sets dimension_ and delay_ attributes
transform(X)	Apply delay embedding. Returns shape (T-(m-1)*tau, d*m)
fit_transform(X)	fit + transform
inverse_transform(embedded, d=1)	Reconstruct original time series

optimal_delay(X, max_delay=50, bins=64)

Select optimal delay via first minimum of Auto Mutual Information.

optimal_dimension(X, delay=1, max_dim=10, fnn_threshold=0.01)

Select optimal embedding dimension via False Nearest Neighbours.

Verification

All results are documented in the project wiki:

• Verification — Lorenz attractor reconstruction, inverse transform roundtrip, optimal parameter selection
• Multivariate Validation — 6 diagnostic tests for multidimensional data
• Comparison with giotto-tda — numerical identity and performance comparison

Lorenz Attractor Reconstruction

Multivariate Validation Summary

#	Test	Result	Status
1	Channel ordering	Interleaved as expected	PASS
2	Cross-channel correlation	Max diff 0.000023	PASS
3	Lorenz structure preservation	Butterfly structure recovered	PASS
4	Noise robustness	Distance corr 0.79 at sigma=0.5	PASS
5	Scale invariance	Roundtrip error ~1e-13	PASS
6	Univariate vs multivariate consistency	Diff = 0 (exact match)	PASS

Tests

PYTHONPATH=src python3 -m pytest tests/ -v

50 tests covering core functionality, edge cases, scikit-learn compatibility, and automatic optimization.

Background

Takens' embedding theorem (1981) guarantees that a dynamical system's state space can be reconstructed from delay coordinates with sufficient embedding dimension m and appropriate delay tau:

y(t) = [x(t), x(t+tau), x(t+2*tau), ..., x(t+(m-1)*tau)]

For a d-dimensional time series, the output is a d*m dimensional vector at each time step.

License

MIT