timeseries.cross_recurrence_plot

Provides classes for the analysis of dynamical systems and time series based on recurrence plots, including measures of recurrence quantification analysis (RQA) and recurrence network analysis.

class pyunicorn.timeseries.cross_recurrence_plot.CrossRecurrencePlot(x, y, metric='supremum', normalize=False, sparse_rqa=False, silence_level=0, **kwds)[source]

Bases: RecurrencePlot

Class CrossRecurrencePlot for generating and quantitatively analyzing cross recurrence plots.

The CrossRecurrencePlot class supports the construction of cross recurrence plots from two multi-dimensional time series, optionally using embedding. Currently, manhattan, euclidean and supremum norms are provided for measuring distances in phase space.

Methods for calculating commonly used measures of recurrence quantification analysis (RQA) are provided, e.g., determinism, maximum diagonal line length and laminarity. The definitions of these measures together with a review of the theory and applications of cross recurrence plots are given in [Marwan2007].

Examples:

  • Create an instance of CrossRecurrencePlot from time series x and y with a fixed recurrence threshold and without embedding:

    CrossRecurrencePlot(x, y, threshold=0.1)
    
  • Create an instance of CrossRecurrencePlot at a fixed recurrence rate and using time delay embedding:

    CrossRecurrencePlot(x, y, dim=3, tau=2,
                        recurrence_rate=0.05).recurrence_rate()
    
CR

The cross recurrence matrix.

M

The length of the embedded time series y.

N: int

The length of the embedded time series x.

__cache_state__() Tuple[Hashable, ...][source]

Hashable tuple of mutable object attributes, which will determine the instance identity for ALL cached method lookups in this class, in addition to the built-in object id(). Returning an empty tuple amounts to declaring the object immutable in general. Mutable dependencies that are specific to a method should instead be declared via @Cached.method(attrs=(…)).

NOTE: A subclass is responsible for the consistency and cost of this state descriptor. For example, hashing a large array attribute may be circumvented by declaring it as a property, with a custom setter method that increments a dedicated mutation counter.

__init__(x, y, metric='supremum', normalize=False, sparse_rqa=False, silence_level=0, **kwds)[source]

Initialize an instance of CrossRecurrencePlot.

Note

For a cross recurrence plot, time series x and y generally do not need to have the same length!

Either recurrence threshold threshold or recurrence rate recurrence_rate have to be given as keyword arguments.

Embedding is only supported for scalar time series. If embedding dimension dim and delay tau are both given as keyword arguments, embedding is applied. Multidimensional time series are processed as is by default. The same delay embedding is applied to both time series x and y.

Parameters:
  • x (2D array (time, dimension)) – One of the time series to be analyzed, can be scalar or multi-dimensional.

  • y (2D array (time, dimension)) – One of the time series to be analyzed, can be scalar or multi-dimensional.

  • metric (str) – The metric for measuring distances in phase space (“manhattan”, “euclidean”, “supremum”).

  • normalize (bool) – Decide whether to normalize both time series to zero mean and unit standard deviation.

  • silence_level (number) – Inverse level of verbosity of the object.

  • threshold (number) – The recurrence threshold keyword for generating the cross recurrence plot using a fixed threshold.

  • recurrence_rate (number) – The recurrence rate keyword for generating the cross recurrence plot using a fixed recurrence rate.

  • dim (number) – The embedding dimension.

  • tau (number) – The embedding delay.

__str__()[source]

Returns a string representation.

balance()[source]

Return balance of the cross recurrence plot.

Might be useful for detecting the direction of coupling between systems using cross recurrence analysis.

cross_recurrence_rate()[source]

Return cross recurrence rate.

Return type:

number (float)

Returns:

the cross recurrence rate.

diagline_dist()[source]

Not implemented yet

distance_matrix(metric)[source]

Return phase space cross distance matrix \(D\) according to the chosen metric.

Parameters:

metric (str) – The metric for measuring distances in phase space (“manhattan”, “euclidean”, “supremum”).

Return type:

2D square array

Returns:

the phase space cross distance matrix \(D\)

euclidean_distance_matrix()[source]

Return the euclidean distance matrix from two (embedded) time series.

Return type:

2D rectangular Numpy array

Returns:

the euclidean distance matrix.

manhattan_distance_matrix()[source]

Return the manhattan distance matrix from two (embedded) time series.

Parameters:
  • x_embedded (2D Numpy array (time, embedding dimension)) – The phase space trajectory x.

  • y_embedded (2D Numpy array (time, embedding dimension)) – The phase space trajectory y.

Return type:

2D rectangular Numpy array

Returns:

the manhattan distance matrix.

recurrence_matrix()[source]

Return the current cross recurrence matrix \(CR\).

Return type:

2D square Numpy array

Returns:

the current cross recurrence matrix \(CR\).

recurrence_rate()[source]

Return cross recurrence rate.

Alias to cross_recurrence_rate(), since RecurrencePlot.recurrence_rate() would give incorrect results here.

Return type:

number (float)

Returns:

the cross recurrence rate.

set_fixed_recurrence_rate(recurrence_rate)[source]

Set the cross recurrence plot to a fixed recurrence rate.

Modifies / sets the class variables CR, N and M accordingly.

Parameters:

recurrence_rate (number) – The recurrence rate.

set_fixed_threshold(threshold)[source]

Set the cross recurrence plot to a fixed threshold.

Modifies / sets the class variables CR, N and M accordingly.

Parameters:

threshold (number) – The recurrence threshold.

supremum_distance_matrix()[source]

Return the supremum distance matrix from two (embedded) time series.

Return type:

2D rectangular Numpy array

Returns:

the supremum distance matrix.

vertline_dist()[source]

Not implemented yet

white_vertline_dist()[source]

Not implemented yet

x

The time series x.

property x_embedded: ndarray

The embedded time series x.

y

The time series y.

property y_embedded: ndarray

The embedded time series y.