TimeDelayEmbedding

class kooplearn.preprocessing.TimeDelayEmbedding(history_length: int, stride: int = 1)

Bases: BaseEstimator, TransformerMixin

A scikit-learn compatible transformer that constructs time-delay embeddings (temporal windows) from trajectory data, with a configurable stride.

Each output sample corresponds to a flattened temporal window of length \(H\), with a stride \(s\) between the starting points of consecutive windows.

Parameters:

• history_length (int) – Number of consecutive time steps per embedding window (\(H\)).

• stride (int, default 1) – Step between the starts of successive windows (\(s\)).

Variables:

• n_samples_in (int) – Number of samples in the input data seen during fitting.

• n_features_in (int) – Number of features per sample in the input data.

Notes

• The inverse_transform method only works when ``stride=1``. Using stride>1 will raise a ValueError, because reconstruction requires overlapping windows.

Examples

>>> import numpy as np
>>> traj = np.arange(20).reshape(10, 2)
>>> tde = TimeDelayEmbedding(history_length=3, stride=1)
>>> X = tde.fit_transform(traj)
>>> X.shape
(8, 6)
>>> reconstructed = tde.inverse_transform(X)
>>> np.allclose(traj, reconstructed, atol=1e-8)
True

>>> tde2 = TimeDelayEmbedding(history_length=3, stride=2)
>>> X2 = tde2.fit_transform(traj)
>>> X2.shape
(4, 6)

Methods

fit(X, y=None)

Fit the transformer by storing the input data shape.

This method validates the input array and stores its dimensions for later use in transformations or inverse transformations.

Parameters:

• X (ndarray of shape (n_samples, n_features)) – Input trajectory data.

• y (None) – Ignored. Present for API compatibility with scikit-learn pipelines.

Returns:

self – Fitted transformer instance.

Return type:

TimeDelayEmbedding

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Input samples.

• y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).

• **fit_params (dict) – Additional fit parameters.

Returns:

X_new – Transformed array.

Return type:

ndarray array of shape (n_samples, n_features_new)

inverse_transform(X)

Reconstruct input trajectory from flattened time-delay embeddings.

This method reverses the transformation performed by transform(). It is only supported when stride=1, since larger strides lead to non-overlapping windows and ambiguous reconstruction.

Parameters:

X (ndarray of shape (n_windows, history_length * n_features_in_)) – Flattened time-delay embedded data.

Returns:

Approximate reconstruction of the original trajectory.

Return type:

ndarray of shape (n_samples, n_features_in_)

Raises:

• ValueError – If stride != 1.

• ValueError – If input shape is incompatible with history_length and the number of input features.

transform(X)

Construct the time-delay embedding of the input trajectory.

Builds overlapping or non-overlapping temporal windows of length history_length with stride between successive windows.

Parameters:

X (ndarray of shape (n_samples, n_features)) – Input trajectory data to embed.

Returns:

Time-delay embedded representation of the input data.

Return type:

ndarray of shape (n_windows, history_length * n_features)

Raises:

• ValueError – If history_length exceeds the number of samples in X.

• ValueError – If stride is not a positive integer.