timeseries.joint_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.joint_recurrence_plot.JointRecurrencePlot(x, y, metric=('supremum', 'supremum'), normalize=False, lag=0, silence_level=0, **kwds)[source]

Bases: RecurrencePlot

Class JointRecurrencePlot for generating and quantitatively analyzing joint recurrence plots.

The JointRecurrencePlot class supports the construction of joint 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 joint recurrence plots are given in [Marwan2007].

Examples:

  • Create an instance of JointRecurrencePlot with a fixed recurrence threshold and without embedding:

    JointRecurrencePlot(x, y, threshold=(0.1,0.2))
    
  • Create an instance of JointRecurrencePlot with a fixed recurrence threshold in units of STD and without embedding:

    JointRecurrencePlot(x, y, threshold_std=(0.03,0.05))
    
  • Create an instance of JointRecurrencePlot at a fixed recurrence rate and using time delay embedding:

    JointRecurrencePlot(
        x, y, dim=(3,5), tau=(2,1),
        recurrence_rate=(0.05,0.04)).recurrence_rate()
    
JR

The joint recurrence matrix.

N: int

The length of both embedded time series x and y.

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

Initialize an instance of JointRecurrencePlot.

Note

For a joint recurrence plot, time series x and y need to have the same length!

Either recurrence thresholds threshold/threshold_std or recurrence rates 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.

Parameters:
  • x (2D array (time, dimension)) – Time series x to be analyzed (scalar/multi-dimensional).

  • y (2D array (time, dimension)) – Time series y to be analyzed (scalar/multi-dimensional).

  • metric (tuple of string) – The metric for measuring distances in phase space (“manhattan”, “euclidean”, “supremum”). Give separately for each time series.

  • normalize (tuple of bool) – Decide whether to normalize the time series to zero mean and unit standard deviation. Give separately for each time series.

  • lag (number) – To create a delayed version of the JRP.

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

  • threshold (tuple of number) – The recurrence threshold keyword for generating the recurrence plot using a fixed threshold. Give separately for each time series.

  • threshold_std (tuple of number) – The recurrence threshold keyword for generating the recurrence plot using a fixed threshold in units of the time series’ STD. Give separately for each time series.

  • recurrence_rate (tuple of number) – The recurrence rate keyword for generating the recurrence plot using a fixed recurrence rate. Give separately for each time series.

  • dim (tuple of number) – Embedding dimension. Give separately for each time series.

  • tau (tuple of number) – Embedding delay. Give separately for each time series.

__str__()[source]

Returns a string representation.

lag

Used to create a delayed JRP.

recurrence_matrix()[source]

Return the current joint recurrence matrix \(JR\).

Return type:

2D square Numpy array

Returns:

the current joint recurrence matrix \(JR\).

set_fixed_recurrence_rate(recurrence_rate)[source]

Set the joint recurrence plot to fixed recurrence rates.

Modifies / sets the class variables JR and N accordingly.

Parameters:

recurrence_rate (tuple of number) – The recurrence rate. Give for both time series separately.

set_fixed_threshold(threshold)[source]

Set the joint recurrence plot to fixed thresholds.

Modifies / sets the class variables JR and N accordingly.

Parameters:

threshold (tuple of number) – The recurrence threshold. Give for both time series separately.

set_fixed_threshold_std(threshold_std)[source]

Set the joint recurrence plot to fixed thresholds in units of the standard deviation of the time series.

Calculates the absolute thresholds and calls set_fixed_threshold().

Parameters:

threshold_std (tuple of number) – The recurrence threshold in units of the standard deviation of the time series. Give for both time series separately.

x

The time series x.

x_embedded

The embedded time series x.

y

The time series y.

y_embedded

The embedded time series y.