Time Series Metrics API

class pynamicalsys.core.time_series_metrics.TimeSeriesMetrics(time_series: ndarray[tuple[int, ...], dtype[float64]])[source]

Bases: object

recurrence_matrix(compute_white_vert_distr=False, return_eps=False, **kwargs) → ndarray[tuple[int, ...], dtype[uint8]] | Tuple[ndarray[tuple[int, ...], dtype[uint8]], ndarray[tuple[int, ...], dtype[float64]]] | Tuple[ndarray[tuple[int, ...], dtype[uint8]], float] | Tuple[ndarray[tuple[int, ...], dtype[uint8]], ndarray[tuple[int, ...], dtype[float64]], float][source]

Compute the recurrence matrix for the time series.

The recurrence threshold can be determined in three different ways, controlled by threshold_mode:

  • threshold_mode="direct": threshold is used directly as the recurrence threshold.

  • threshold_mode="std": the threshold is computed from the standard deviation of the data as

    eps = threshold * ||sigma||_p

    where sigma is the vector of component-wise standard deviations.

  • threshold_mode="rr": the threshold is chosen such that the recurrence matrix achieves the desired recurrence rate, where threshold is interpreted as the target recurrence rate.

For backward compatibility, the deprecated parameter threshold_std may still be used. If threshold_std=True, the threshold strategy is treated as threshold_mode="std". A warning will be issued and the parameter will be removed in a future release.

Parameters

compute_white_vert_distrbool, default=False

If True, also return the white vertical line length distribution.

return_epsbool, default=False

If True, also return the threshold used in the recurrence matrix construction.

metric{‘supremum’, ‘euclidean’, ‘manhattan’} or callable, default=’supremum’

Distance metric used to compute pairwise distances between state vectors.

If a callable is provided, it must have signature metric(x, y) -> float, where x and y are 1D NumPy arrays representing state vectors.

The callable must be Numba-compatible, since it will be executed inside a Numba-compiled routine. For best performance and reliability, the metric should be decorated with @numba.njit.

std_metric{‘supremum’, ‘euclidean’, ‘manhattan’} or callable, default=’supremum’

Metric used in the standard-deviation-based threshold calculation.

If a callable is provided, it must take the vector of component-wise standard deviations and return a scalar with signature std_metric(sigma) -> float. It must be Numba-compatible (ideally decorated with @numba.njit).

thresholdfloat, default=0.1

Threshold parameter. Its meaning depends on the selected strategy:

  • threshold_mode="direct": direct recurrence threshold

  • threshold_mode="std": scaling factor for the standard-deviation threshold

  • threshold_mode="rr": target recurrence rate

threshold_mode{‘direct’, ‘std’, ‘rr’}, optional

Strategy used to determine the recurrence threshold.

threshold_stdbool, optional

Deprecated. If set to True, the threshold will be computed using the standard deviation of the data (equivalent to threshold_mode="std"). This parameter will be removed in a future release.

lminint, default=1

Minimum white vertical line length considered when computing the white vertical line length distribution.

Returns

NDArray[np.uint8] or tuple

The returned value depends on the optional flags:

  • If compute_white_vert_distr=False and return_eps=False: returns recmat.

  • If compute_white_vert_distr=True and return_eps=False: returns (recmat, distr), where distr is the white vertical line length distribution.

  • If compute_white_vert_distr=False and return_eps=True: returns (recmat, eps), where eps is the recurrence threshold used to construct the matrix.

  • If compute_white_vert_distr=True and return_eps=True: returns (recmat, distr, eps).

recurrence_time_entropy(**kwargs)[source]

Compute the recurrence time entropy (RTE) of the time series.

The recurrence time entropy is computed from the distribution of white vertical line lengths in the recurrence matrix.

Parameters

metric{‘supremum’, ‘euclidean’, ‘manhattan’} or callable, default=’supremum’

Distance metric used to compute pairwise distances between state vectors.

If a callable is provided, it must have signature metric(x, y) -> float. The callable must be Numba-compatible, since it will be executed inside a Numba-compiled routine. For best performance, decorate it with @numba.njit.

std_metric{‘supremum’, ‘euclidean’, ‘manhattan’} or callable, default=’supremum’

Metric used in the standard-deviation-based threshold calculation.

If a callable is provided, it must take the vector of component-wise standard deviations and return a scalar with signature std_metric(sigma) -> float. It must be Numba-compatible (ideally decorated with @numba.njit).

thresholdfloat, default=0.1

Threshold parameter. Its interpretation depends on threshold_mode.

threshold_mode{‘direct’, ‘std’, ‘rr’}, optional

Strategy used to determine the recurrence threshold.

  • direct: use threshold directly as the recurrence threshold

  • std: compute eps = threshold * ||sigma||_p

  • rr: choose the threshold so that the recurrence matrix achieves the desired recurrence rate

threshold_stdbool, optional

Deprecated. If set to True, the threshold will be computed using the standard deviation of the data (equivalent to threshold_mode="std"). This parameter will be removed in a future release.

lminint, default=1

Minimum white vertical line length considered in the entropy calculation.

return_recmatbool, default=False

If True, also return the recurrence matrix.

return_pbool, default=False

If True, also return the normalized white vertical line length distribution used to compute the entropy.

Returns

float or tuple

  • If return_recmat=False and return_p=False: returns the recurrence time entropy.

  • If return_recmat=True: returns (rte, recmat).

  • If return_p=True: returns (rte, P).

  • If both are True: returns (rte, recmat, P).

hurst_exponent(wmin: int = 2)[source]

Estimate the Hurst exponent for a system trajectory using the rescaled range (R/S) method.

Parameters

uNDArray[np.float64]

Initial condition vector of shape (n,).

parametersNDArray[np.float64]

Parameters passed to the mapping function.

total_timeint

Total number of iterations used to generate the trajectory.

mappingCallable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]

A function that defines the system dynamics, i.e., how u evolves over time given parameters.

wminint, optional

Minimum window size for the rescaled range calculation. Default is 2.

transient_timeOptional[int], optional

Number of initial iterations to discard as transient. If None, no transient is removed. Default is None.

Returns

NDArray[np.float64]

Estimated Hurst exponents for each dimension of the input vector u, of shape (n,).

Notes

The Hurst exponent is a measure of the long-term memory of a time series:

  • H = 0.5 indicates a random walk (no memory).

  • H > 0.5 indicates persistent behavior (positive autocorrelation).

  • H < 0.5 indicates anti-persistent behavior (negative autocorrelation).

This implementation computes the rescaled range (R/S) for various window sizes and performs a linear regression in log-log space to estimate the exponent.

The function supports multivariate time series, estimating one Hurst exponent per dimension.