Embedding

Time-delay embedding and parameter estimation for recurrence analysis.

driada.recurrence.embedding.takens_embedding(data, tau, m)[source]

Construct time-delay embedding matrix.

Given a 1D time series x of length N, constructs the matrix:

[[x[0],        x[1],        ..., x[N_e-1]       ],
 [x[tau],      x[tau+1],    ..., x[tau+N_e-1]   ],
 ...
 [x[(m-1)*tau], ...              x[N-1]          ]]

where N_e = N - (m-1)*tau.

Parameters:

  • data (array-like, 1D) – Time series of length N.

  • tau (int) – Time delay in samples. Must be >= 1.

  • m (int) – Embedding dimension. Must be >= 2.

Returns:

Delay-embedded matrix. Rows are embedding dimensions, columns are time points. Matches ProximityGraph (features, samples) convention.

Return type:

ndarray of shape (m, N_embedded)

Raises:

ValueError – If data is not 1D, or series is too short for given tau and m.

driada.recurrence.embedding.estimate_tau(data, max_shift=100, method='first_minimum', estimator='gcmi', **estimator_kwargs)[source]

Estimate optimal time delay for Takens embedding.

Parameters:

  • data (array-like, 1D) – Time series.

  • max_shift (int, optional) – Maximum lag to evaluate. Default: 100.

  • method ({'first_minimum', 'exponential_fit'}) –

    • ‘first_minimum’: First local minimum of time-delayed mutual information.

    • ’exponential_fit’: Fit exponential decay to TDMI, return -1/slope.

  • estimator ({'gcmi', 'ksg'}, optional) – MI estimator passed to get_tdmi(). Default: ‘gcmi’.

  • **estimator_kwargs – Additional kwargs passed to get_tdmi() (e.g., nn=5 for KSG).

Returns:

Optimal time delay in samples. Always >= 1.

Return type:

int

Raises:

ValueError – If method is not recognized.

driada.recurrence.embedding.estimate_embedding_dim(data, tau, max_dim=10, r_tol=10.0, a_tol=2.0, fnn_threshold=0.05, return_fractions=False)[source]

Estimate embedding dimension via false nearest neighbors (FNN).

For each candidate dimension m (from 2 to max_dim), embeds the time series, finds each point’s nearest neighbor, and checks whether that neighbor is still close in dimension m + 1. “False” neighbors appear close only because the attractor is projected into too few dimensions.

Parameters:

  • data (array-like, 1D) – Time series.

  • tau (int) – Time delay for embedding.

  • max_dim (int, optional) – Maximum dimension to test. Default: 10.

  • r_tol (float, optional) – Distance-ratio threshold (Kennel et al. 1992). Default: 10.0.

  • a_tol (float, optional) – Absolute threshold relative to attractor size. Default: 2.0.

  • fnn_threshold (float, optional) – FNN fraction below which the dimension is accepted. Default: 0.05 (5 %).

  • return_fractions (bool, optional) – If True, also return per-dimension FNN fractions for diagnostic plots. Default: False.

Returns:

Estimated embedding dimension (minimum 2). When return_fractions is True, returns (dim, fractions) where fractions is [(m, fnn_fraction), ...] for each tested dimension.

Return type:

int or (int, list of (int, float))