Recurrence Quantification Analysis

rqa(R; kwargs...)

Calculate all RQA parameters of a recurrence matrix R. See the functions referred to below for the definition of the different parameters and the default values of the arguments. Using this function is much more efficient than calling all individual functions one by one.

Return

The returned value contains the following entries, which can be retrieved as from a dictionary (e.g. results[:RR], etc.):

• :RR: recurrence rate (see recurrencerate)
• :DET: determinsm (see determinism)
• :L: average length of diagonal structures (see dl_average)
• :Lmax: maximum length of diagonal structures (see dl_max)
• :DIV: divergence (see divergence)
• :ENTR: entropy of diagonal structures (see dl_entropy)
• :TREND: trend of recurrences (see trend)
• :LAM: laminarity (see laminarity)
• :TT: trapping time (see trappingtime)
• :Vmax: maximum length of vertical structures (see vl_max)
• :VENTR: entropy of vertical structures (see vl_entropy)
• :MRT: mean recurrence time (see meanrecurrencetime)
• :RTE recurrence time entropy (see rt_entropy)
• :NMPRT: number of the most probable recurrence time (see nmprt)

All the parameters returned by rqa are Float64 numbers, even for parameters like :Lmax, :Vmax or :NMPRT which are integer values. In the case of empty histograms (e.g. no existing vertical lines less than the keyword lminvert) the average and maximum values (:L, :Lmax, :TT, :Vmax, :MRT) are returned as 0.0 but their respective entropies (:ENTR, :VENTR, :RTE) are returned as NaN.

Keyword Arguments

Standard keyword arguments are the ones accepted by the functions listed below, i.e. theiler, lmin, and border:

• theiler is used to define a "Theiler window" around the central diagonal or "line of identity" (LOI): a region of points that are excluded in the calculation of RQA parameters, in order to rule out self-recurrences and apparent recurrences for smooth or high resolution data. The LOI is excluded by default for matrices of the types RecurrenceMatrix or JointRecurrenceMatrix, but it is included for matrices of the type CrossRecurrenceMatrix. theiler=0 means that the whole matrix is scanned for lines. theiler=1 means that the LOI is excluded. In general, theiler=n means that the n central diagonals are excluded (at both sides of the LOI, i.e. actually 2n-1 diagonals are excluded).

• lmin is used to define the minimum line length in the parameters that describe the distributions of diagonal or vertical lines (it is set as 2 by default).

• border is used to avoid border effects in the calculation of :TREND (cf. trend).

In addition theilerdiag, lmindiag may be used to declare specific values that override the values of theiler and lmin in the calculation of parameters related to diagonal structures. Likewise, theilervert and lminvert can be used for the calculation of parameters related to vertical structures.

The keyword argument onlydiagonal (false by default) can be set to true in order to restrict the analysis to the recurrence rate and the parameters related to diagonal structures (:RR, :DET, :L, :Lmax, :DIV and :ENTR), which makes this function slightly faster.

Transitional note on the returned type

In older versions, the rqa function returned a NamedTuple, and in future versions it is planned to return a Dict instead. In both cases, the results can be indexed with square brackets and Symbol keys, as result[:RR], result[:DET], etc. However, named tuples can also be indexed with "dot syntax", e.g. result.RR, whereas this will not be possible with dictionaries, and there are other differences in the indexing and iteration of those two types.

In order to facilitate the transition between versions, this function currently returns a RQA object that essentially works as a dictionary, but can also be indexed with the dot syntax (logging a deprecation warning). The returned type can also be specified as a first argument of rqa in order to replicate the output of different versions:

• rqa(NamedTuple, R...) to obtain the output of the older version (as in 1.3).
• rqa(Dict, R...) to obtain the output of the planned future version.
• rqa(RQA, R...) to obtain the default current output (same as rqa(R...))
• rqa(DT,R...) to obtain the output as DT which is a subtype of AbstractDict (e.g. rqa(OrderedDict,R...) returns an OrderedDict)

recurrencerate(R[; theiler])

Calculate the recurrence rate of the recurrence matrix R.

Description

The recurrence rate is calculated as:

\[RR = \frac{1}{S} \sum R\]

where $S$ is the size of R or the region of R with potential recurrent points. There is not a unique definition of that denominator, which is defined as the full size of the matrix in many sources (e.g. [1]), whereas in others it is adjusted to remove the points of the LOI when they are excluded from the count [2,3].

For matrices of type RecurrenceMatrix or JointRecurrenceMatrix, where the points around the central diagonal are usually excluded, the denominator is adjusted to the size of the matrix outside the Theiler window (by default equal to the LOI, and adjustable with the keyword argument theiler; see rqa for details). For matrices of type CrossRecurrenceMatrix, where normally all points are analyzed, the denominator is always the full size of the matrix, regardless of the Theiler window that might be defined (none by default).

Hint: to reproduce the calculations done following the formulas that use the full size of the matrix in the denominator, use CrossRecurrenceMatrix(s,s,ε) to define the recurrence matrix, instead of RecurrenceMatrix(s,ε), setting theiler=1 (or theiler=n in general) to explicitly exclude the LOI or other diagonals around it.

References

[1] : N. Marwan et al., "Recurrence plots for the analysis of complex systems", Phys. Reports 438(5-6), 237-329 (2007). DOI:10.1016/j.physrep.2006.11.001

[2] : C.L. Webber & J.P. Zbilut, "Recurrence Quantification Analysis of Nonlinear Dynamical Systems", in: Riley MA & Van Orden GC, Tutorials in Contemporary Nonlinear Methods for the Behavioral Sciences, 26-94 (2005). URL: https://www.nsf.gov/pubs/2005/nsf05057/nmbs/nmbs.pdf

[3] : N. Marwan & C.L. Webber, "Mathematical and computational foundations of recurrence quantifications", in: Webber, C.L. & N. Marwan (eds.), Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 3-43 (2015).

determinism(R[; lmin=2, theiler])

Calculate the determinism of the recurrence matrix R:

Description

The determinism is calculated as:

\[DET = \frac{\sum_{l=lmin}{l P(l)}}{\sum_{l=1}{l P(l)}} = \frac{\sum_{l=lmin}{l P(l)}}{\sum R}\]

where $l$ stands for the lengths of diagonal lines in the matrix, and $P(l)$ is the number of lines of length equal to $l$.

lmin is set to 2 by default, and this calculation rules out all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

dl_average(R[; lmin=2, theiler])

Calculate the average of the diagonal lines contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

dl_max(R[; lmin=2, theiler])

Calculate the longest diagonal line contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

dl_entropy(R[; lmin=2, theiler])

Calculate the Shannon entropy of the diagonal lines contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

Notes: This metric was first proposed in the paper "Exploiting Nonlinear Recurrence and Fractal Scaling Properties for Voice Disorder Detection" as Recurrence Period Density Entropy or Recurrence Probability Density Entropy (RPDE). It is a normalized dimensionless metric in the range [0,1]. In the 2018 article "Recurrence threshold selection for obtaining robust recurrence characteristics in different embedding dimensions", the indicator RPDE is explicitly called Recurrence Time Entropy (RTE). Here RPDE and RTE are clearly the same indicator.

divergence(R[; theiler])

Calculate the divergence of the recurrence matrix R (actually the inverse of dl_max).

trend(R[; border=10, theiler])

Calculate the trend of recurrences in the recurrence matrix R.

Description

The trend is the slope of the linear regression that relates the density of recurrent points in the diagonals parallel to the LOI and the distance between those diagonals and the LOI. It quantifies the degree of system stationarity, such that in recurrence plots where points "fade away" from the central diagonal, the trend will have a negative value.

It is calculated as:

\[TREND = 10^3\frac{\sum_{d=\tau}^{\tilde{N}}\delta[d]\left(RR[d]-\langle RR[d]\rangle\right)}{\sum_{d=\tau}^{\tilde{N}}\delta[d]^2}\]

where $RR[d]$ is the local recurrence rate of the diagonal $d$, $\delta[d]$ is a balanced measure of the distance between that diagonal and the LOI, $\tau$ is the Theiler window (number of central diagonals that are excluded), and $\tilde{N}$ is the number of the outmost diagonal that is included.

This parameter is expressed in units of variation recurrence rate every 1000 data points, hence the factor $10^3$ in the formula [1].

The 10 outermost diagonals (counting from the corners of the matrix) are excluded by default to avoid "border effects". Use the keyword argument border to define a different number of excluded lines, and theiler to define the size of the Theiler window (see rqa for details).

Note: In rectangular cross-recurrence plots (i.e. when the time series that originate them are not of the same length), the limits of the formula for TREND are not clearly defined. For the sake of consistency, this function limits the calculations to the biggest square matrix that contains the LOI.

References

[1] C.L. Webber & J.P. Zbilut, "Recurrence Quantification Analysis of Nonlinear Dynamical Systems", in: Riley MA & Van Orden GC, Tutorials in Contemporary Nonlinear Methods for the Behavioral Sciences, 2005, 26-94. https://www.nsf.gov/pubs/2005/nsf05057/nmbs/nmbs.pdf

laminarity(R[; lmin=2, theiler])

Calculate the laminarity of the recurrence matrix R.

Description

The laminarity is calculated as:

\[LAM = \frac{\sum_{v=lmin}{v P(l)}}{\sum_{v=1}{v P(v)}} = \frac{\sum_{v=lmin}{v P(l)}}{\sum R}\]

where $v$ stands for the lengths of vertical lines in the matrix, and $P(v)$ is the number of lines of length equal to $v$.

lmin is set to 2 by default, and this calculation rules out all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

trappingtime(R[; lmin=2, theiler])

Calculate the trapping time of the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

The trapping time is the average of the vertical line structures and thus equal to vl_average.

vl_average(R[; lmin=2, theiler])

Calculate the average of the vertical lines contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

vl_max(R[; lmin=2, theiler])

Calculate the longest vertical line contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

vl_entropy(R[; lmin=2, theiler])

Calculate the Shannon entropy of the vertical lines contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

Notes: This metric was first proposed in the paper "Exploiting Nonlinear Recurrence and Fractal Scaling Properties for Voice Disorder Detection" as Recurrence Period Density Entropy or Recurrence Probability Density Entropy (RPDE). It is a normalized dimensionless metric in the range [0,1]. In the 2018 article "Recurrence threshold selection for obtaining robust recurrence characteristics in different embedding dimensions", the indicator RPDE is explicitly called Recurrence Time Entropy (RTE). Here RPDE and RTE are clearly the same indicator.

meanrecurrencetime(R[; lmin=2, theiler])

Calculate the mean recurrence time of the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

Equivalent to rt_average.

nmprt(R[; lmin=2, theiler])

Calculate the number of the most probable recurrence time (NMPRT), ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

This number indicates how many times the system has recurred using the recurrence time that appears most frequently, i.e it is the maximum value of the histogram of recurrence times [1].

References

[1] : E.J. Ngamga et al. "Recurrence analysis of strange nonchaotic dynamics", Physical Review E, 75(3), 036222(1-8) (2007) DOI:10.1103/physreve.75.036222

rt_entropy(R[; lmin=2, theiler])

Calculate the Shannon entropy of the recurrence times contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

Notes: This metric was first proposed in the paper "Exploiting Nonlinear Recurrence and Fractal Scaling Properties for Voice Disorder Detection" as Recurrence Period Density Entropy or Recurrence Probability Density Entropy (RPDE). It is a normalized dimensionless metric in the range [0,1]. In the 2018 article "Recurrence threshold selection for obtaining robust recurrence characteristics in different embedding dimensions", the indicator RPDE is explicitly called Recurrence Time Entropy (RTE). Here RPDE and RTE are clearly the same indicator.

rt_average(R[; lmin=2, theiler])

Calculate the average of the recurrence times contained in the recurrence matrix R, ruling out the lines shorter than lmin (2 by default) and all the points inside the Theiler window (see rqa for the default values and usage of the keyword argument theiler).

recurrencestructures(x::AbstractRecurrenceMatrix;
                         diagonal=true,
                         vertical=true,
                         recurrencetimes=true,
                         kwargs...)

Return a dictionary with the histograms of the recurrence structures contained in the recurrence matrix x, with the keys "diagonal", "vertical" or "recurrencetimes", depending on what keyword arguments are given as true.

Description

Each item of the dictionary is a vector of integers, such that the i-th element of the vector is the number of lines of length i contained in x.

• "diagonal" counts the diagonal lines, i.e. the recurrent trajectories.
• "vertical" counts the vertical lines, i.e. the laminar states.
• "recurrencetimes" counts the vertical distances between recurrent states, i.e. the recurrence times.

All the points of the matrix are counted by default. The keyword argument theiler can be passed to rule out the lines around the main diagonal. See the arguments of the function rqa for further details.

"Empty" histograms are represented always as [0].

Notice: There is not a unique operational definition of "recurrence times". In the analysis of recurrence plots, usually the "second type" of recurrence times as defined by Gao and Cai [1] are considered, i.e. the distance between consecutive (but separated) recurrent structures in the vertical direction of the matrix. But that distance is not uniquely defined when the vertical recurrent structures are longer than one point. The recurrence times calculated here are the distance between the midpoints of consecutive lines, which is a balanced estimator of the Poincaré recurrence times [2].

References

[1] J. Gao & H. Cai. "On the structures and quantification of recurrence plots". Physics Letters A, 270(1-2), 75–87 (2000).

[2] N. Marwan & C.L. Webber, "Mathematical and computational foundations of recurrence quantifications", in: Webber, C.L. & N. Marwan (eds.), Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 3-43 (2015).

windowed(rmat, f, width, step = 1; kwargs...)

A convenience function that applies the RQA function f, such as determinism, to windowed views of the given recurrence matrix rmat with given window width and step. The kwargs... are propagated to the call f(rmat_view; kwargs...).