A Julia package that offers tools for computing Recurrence Plots and exploring them within the framework of Recurrence Quantification Analysis and Recurrence Network Analysis. It can be used as a standalone package, or as part of DynamicalSystems.jl.
To install it, run import Pkg; Pkg.add("RecurrenceAnalysis").
All further information is provided in the documentation, which you can either find online or build locally by running the docs/make.jl file.
Webber, C. L., & Marwan, N. (2015). Recurrence Quantification Analysis. (C. L. Webber, & N. Marwan, Eds.). Cham: Springer International Publishing. https://doi.org/10.1007/978-3-319-07155-8
Marwan, N., Carmen Romano, M., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. Physics Reports, 438(5–6), 237–329. https://doi.org/10.1016/j.physrep.2006.11.001
Settings
This document was generated with Documenter.jl version 1.4.1 on Monday 10 June 2024. Using Julia version 1.10.4.
A Julia package that offers tools for computing Recurrence Plots and exploring them within the framework of Recurrence Quantification Analysis and Recurrence Network Analysis. It can be used as a standalone package, or as part of DynamicalSystems.jl.
To install it, run import Pkg; Pkg.add("RecurrenceAnalysis").
All further information is provided in the documentation, which you can either find online or build locally by running the docs/make.jl file.
Webber, C. L., & Marwan, N. (2015). Recurrence Quantification Analysis. (C. L. Webber, & N. Marwan, Eds.). Cham: Springer International Publishing. https://doi.org/10.1007/978-3-319-07155-8
Marwan, N., Carmen Romano, M., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. Physics Reports, 438(5–6), 237–329. https://doi.org/10.1016/j.physrep.2006.11.001
Settings
This document was generated with Documenter.jl version 1.7.0 on Monday 23 September 2024. Using Julia version 1.10.5.
diff --git a/dev/networks/6058792e.png b/dev/networks/6058792e.png
new file mode 100644
index 0000000..dbaf09a
Binary files /dev/null and b/dev/networks/6058792e.png differ
diff --git a/dev/networks/c1865a9f.png b/dev/networks/c1865a9f.png
deleted file mode 100644
index 180df1a..0000000
Binary files a/dev/networks/c1865a9f.png and /dev/null differ
diff --git a/dev/networks/index.html b/dev/networks/index.html
index bda6a2f..01dc7f6 100644
--- a/dev/networks/index.html
+++ b/dev/networks/index.html
@@ -1,5 +1,5 @@
-Recurrence Networks · RecurrenceAnalysis.jl
Recurrence matrices can be reinterpreted as adjacency matrices of complex networks embedded in state space, such that each node or vertex of the network corresponds to a point of the timeseries, and the links of the network connect pairs of points that are mutually close the phase space. The relationship between a recurrence matrix $R$ and its corresponding adjacency matrix $A$ is:
\[R[i,j] = A[i,j] - \delta[i,j]\]
i.e. there is an edge in the associated network between every two neighboring points in the phase space, excluding self-connections (points in the Line Of Identity or main diagonal of $R$).
This definition assumes that $A$ represents an undirected graph, so $R$ must be a symmetric matrix as corresponding to a RecurrenceMatrix or a JointRecurrenceMatrix.
While RQA characterizes the properties of line structures in the recurrence plots, which consider dynamical aspects (e.g. continuity of recurrences, length of sequences, etc.), the analysis of recurrence networks does not take into account time information, since network properties are independent of the ordering of vertices. On the other hand, recurrence network analysis (RNA) provides information about geometric characteristics of the state space, like homogeneity of the connections, clustering of points, etc. More details about the theoretical framework of RNA can be found in the following papers:
R.V. Donner et al. "Complex Network Analysis of Recurrences", in: Webber, C.L. & Marwan N. (eds.) Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 101-165 (2015).
The JuliaGraphs organization provides multiple packages for Julia to create, visualize and analyze complex networks. In particular, the package LightGraphs defines the type SimpleGraph that can be used to represent undirected networks. Such graphs can be created from symmetric recurrence matrices, as in the following example with a Hénon map:
using RecurrenceAnalysis, DynamicalSystemsBase
+Recurrence Networks · RecurrenceAnalysis.jl
Recurrence matrices can be reinterpreted as adjacency matrices of complex networks embedded in state space, such that each node or vertex of the network corresponds to a point of the timeseries, and the links of the network connect pairs of points that are mutually close the phase space. The relationship between a recurrence matrix $R$ and its corresponding adjacency matrix $A$ is:
\[R[i,j] = A[i,j] - \delta[i,j]\]
i.e. there is an edge in the associated network between every two neighboring points in the phase space, excluding self-connections (points in the Line Of Identity or main diagonal of $R$).
This definition assumes that $A$ represents an undirected graph, so $R$ must be a symmetric matrix as corresponding to a RecurrenceMatrix or a JointRecurrenceMatrix.
While RQA characterizes the properties of line structures in the recurrence plots, which consider dynamical aspects (e.g. continuity of recurrences, length of sequences, etc.), the analysis of recurrence networks does not take into account time information, since network properties are independent of the ordering of vertices. On the other hand, recurrence network analysis (RNA) provides information about geometric characteristics of the state space, like homogeneity of the connections, clustering of points, etc. More details about the theoretical framework of RNA can be found in the following papers:
R.V. Donner et al. "Complex Network Analysis of Recurrences", in: Webber, C.L. & Marwan N. (eds.) Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 101-165 (2015).
The JuliaGraphs organization provides multiple packages for Julia to create, visualize and analyze complex networks. In particular, the package LightGraphs defines the type SimpleGraph that can be used to represent undirected networks. Such graphs can be created from symmetric recurrence matrices, as in the following example with a Hénon map:
using RecurrenceAnalysis, DynamicalSystemsBase
using Graphs: SimpleGraph
# make trajectory of Henon map
@@ -11,5 +11,5 @@
# Cast it into a recurrence network
R = RecurrenceMatrix(X, 0.25; metric = Chebyshev())
network = SimpleGraph(R)
{201, 2945} undirected simple Int64 graph
There are various plotting tools that can be used to visualize such graphs. For instance, the following plot made with the package GraphMakie.jl.
LightGraphs has a large set of functions to extract local measures (associated to particular vertices or edges) and global coefficients associated to the whole network. For SimpleGraphs created from recurrence matrices, as the variable network in the previous example, the vertices are labelled with numeric indices following the same ordering as the rows or columns of the given matrix. So for instance degree(network, i) would give the degree of the i-th point of the timeseries (number of connections with other points), whereas degree(network) would give a vector of such measures ordered as the original timeseries.
As in RQA, we provide a function that computes a selection of commonly used global RNA measures, directly from the recurrence matrix:
Calculate a set of Recurrence Network parameters. The input R can be a symmetric recurrence matrix that is interpreted as the adjacency matrix of an undirected complex network, such that linked vertices are neighboring points in the phase space.
Alternatively, the inputs can be a graph object or any valid inputs to the SimpleGraph constructor of the Graphs package.
Return
The returned value is a dictionary that contains the following entries, with the corresponding global network properties[1, 2]:
:density: edge density, approximately equivalent to the global recurrence rate in the phase space.
:transitivity: network transitivity, which describes the
global clustering of points following Barrat's and Weigt's formulation [3].
:averagepath: mean value of the shortest path lengths taken over
all pairs of connected vertices, related to the average separation between points in the phase.
:diameter: maximum value of the shortest path lengths between
pairs of connected vertices, related to the phase space diameter.
References
[1]: R.V. Donner et al. "Recurrence networks — a novel paradigm for nonlinear time series analysis", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025
[2]: R.V. Donner et al., The geometry of chaotic dynamics — a complex network perspective, Eur. Phys. J. B 84, 653–672 (2011) DOI:10.1140/epjb/e2011-10899-1
[3]: A. Barrat & M. Weight, "On the properties of small-world network models", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067
The concept of clustering coefficient at local level (for individual nodes of the network) is clearly defined as the fraction of connecting nodes that are also connected between them, forming "triangles". But at global level it is a source of confusion: the term of "global clustering coefficient" was originally used by Watts and Strogatz[1], referred to the average of local clustering coefficient across all the graph's nodes. But Barrat and Weigt proposed an alternative definition[2] that characterizes the effective global dimensionality of the system, giving equal weight to all triangles in the network[3].
This second definition is often named with the distinctive term of "transitivity", as in the output of rna, whereas the corresponding function of the LightGraphs package is global_clustering_coefficient. The "global clustering coefficient" as by Watts and Strogatz could be obtained as mean(local_clustering_coefficient(network)) – with network being a graph object as in the previous example. (The function mean is in the Julia standard library, and can be brought into scope with the command using Statistics.)
2A. Barrat & M. Weight, "On the properties of small-world network models", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067
3R.V. Donner et al. "Recurrence networks — a novel paradigm for nonlinear time series analysis", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025
Settings
This document was generated with Documenter.jl version 1.4.1 on Monday 10 June 2024. Using Julia version 1.10.4.
LightGraphs has a large set of functions to extract local measures (associated to particular vertices or edges) and global coefficients associated to the whole network. For SimpleGraphs created from recurrence matrices, as the variable network in the previous example, the vertices are labelled with numeric indices following the same ordering as the rows or columns of the given matrix. So for instance degree(network, i) would give the degree of the i-th point of the timeseries (number of connections with other points), whereas degree(network) would give a vector of such measures ordered as the original timeseries.
As in RQA, we provide a function that computes a selection of commonly used global RNA measures, directly from the recurrence matrix:
Calculate a set of Recurrence Network parameters. The input R can be a symmetric recurrence matrix that is interpreted as the adjacency matrix of an undirected complex network, such that linked vertices are neighboring points in the phase space.
Alternatively, the inputs can be a graph object or any valid inputs to the SimpleGraph constructor of the Graphs package.
Return
The returned value is a dictionary that contains the following entries, with the corresponding global network properties[1, 2]:
:density: edge density, approximately equivalent to the global recurrence rate in the phase space.
:transitivity: network transitivity, which describes the
global clustering of points following Barrat's and Weigt's formulation [3].
:averagepath: mean value of the shortest path lengths taken over
all pairs of connected vertices, related to the average separation between points in the phase.
:diameter: maximum value of the shortest path lengths between
pairs of connected vertices, related to the phase space diameter.
References
[1]: R.V. Donner et al. "Recurrence networks — a novel paradigm for nonlinear time series analysis", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025
[2]: R.V. Donner et al., The geometry of chaotic dynamics — a complex network perspective, Eur. Phys. J. B 84, 653–672 (2011) DOI:10.1140/epjb/e2011-10899-1
[3]: A. Barrat & M. Weight, "On the properties of small-world network models", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067
The concept of clustering coefficient at local level (for individual nodes of the network) is clearly defined as the fraction of connecting nodes that are also connected between them, forming "triangles". But at global level it is a source of confusion: the term of "global clustering coefficient" was originally used by Watts and Strogatz[1], referred to the average of local clustering coefficient across all the graph's nodes. But Barrat and Weigt proposed an alternative definition[2] that characterizes the effective global dimensionality of the system, giving equal weight to all triangles in the network[3].
This second definition is often named with the distinctive term of "transitivity", as in the output of rna, whereas the corresponding function of the LightGraphs package is global_clustering_coefficient. The "global clustering coefficient" as by Watts and Strogatz could be obtained as mean(local_clustering_coefficient(network)) – with network being a graph object as in the previous example. (The function mean is in the Julia standard library, and can be brought into scope with the command using Statistics.)
2A. Barrat & M. Weight, "On the properties of small-world network models", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067
3R.V. Donner et al. "Recurrence networks — a novel paradigm for nonlinear time series analysis", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025
Settings
This document was generated with Documenter.jl version 1.7.0 on Monday 23 September 2024. Using Julia version 1.10.5.
A RecurrenceMatrix can be analyzed in several ways to yield information about the dynamics of the trajectory. All these various measures and functions are collectively called "Recurrence Quantification Analysis" (RQA).
To understand how each measure can be useful, we suggest to see the review articles listed in our documentation strings, namely:
N. Marwan et al., "Recurrence plots for the analysis of complex systems", Phys. Reports 438(5-6), 237-329 (2007).
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).
In case you need all of the RQA-related functions (see below) and you don't want to write 10 lines of code to compute them all (since they are so many) we provide an all-in-one function that computes all of them and returns a dictionary with the results!
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.):
: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)
It may be the case that for a given recurrence matrix some structures do not exist at all. For example there are recurrence matrices that have no vertical lengths (or no vertical lengths with length less than lmin). In such cases the behavior of our RQA pipeline is the following:
Quantities that represent maximum or average values are 0.0.
Quantities that represent entropies are NaN.
See also the [windowed] function for a windowed version of rqa.
A RecurrenceMatrix can be analyzed in several ways to yield information about the dynamics of the trajectory. All these various measures and functions are collectively called "Recurrence Quantification Analysis" (RQA).
To understand how each measure can be useful, we suggest to see the review articles listed in our documentation strings, namely:
N. Marwan et al., "Recurrence plots for the analysis of complex systems", Phys. Reports 438(5-6), 237-329 (2007).
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).
In case you need all of the RQA-related functions (see below) and you don't want to write 10 lines of code to compute them all (since they are so many) we provide an all-in-one function that computes all of them and returns a dictionary with the results!
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.):
: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)
It may be the case that for a given recurrence matrix some structures do not exist at all. For example there are recurrence matrices that have no vertical lengths (or no vertical lengths with length less than lmin). In such cases the behavior of our RQA pipeline is the following:
Quantities that represent maximum or average values are 0.0.
Quantities that represent entropies are NaN.
See also the [windowed] function for a windowed version of rqa.
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).
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).
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).
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).
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.
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.
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
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).
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.
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).
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).
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.
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).
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
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.
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).
Theiler window: number of diagonals around the LOI excluded from the analysis. The value 0 means that the LOI is included in the analysis. Use 1 to exclude the LOI.
The functions that we list in this page internally compute histograms of some recurrence structures, like e.g. the vertical lengths. You can access these values directly with the following function:
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).
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).
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).
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).
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.
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.
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
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).
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.
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).
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).
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.
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).
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
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.
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).
Theiler window: number of diagonals around the LOI excluded from the analysis. The value 0 means that the LOI is included in the analysis. Use 1 to exclude the LOI.
The functions that we list in this page internally compute histograms of some recurrence structures, like e.g. the vertical lengths. You can access these values directly with the following function:
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].
[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).
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...).
This document was generated with Documenter.jl version 1.4.1 on Monday 10 June 2024. Using Julia version 1.10.4.
+ 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].
[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).
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...).
A Recurrence plot (which refers to the plot of a recurrence matrix) is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the phase space that it was at some previous time.
The central structure used in these recurrences is the (cross-) recurrence matrix:
A Recurrence plot (which refers to the plot of a recurrence matrix) is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the phase space that it was at some previous time.
The central structure used in these recurrences is the (cross-) recurrence matrix:
where $d(x[i], y[j])$ stands for the distance between trajectory $x$ at point $i$ and trajectory $y$ at point $j$. Both $x, y$ can be single timeseries, full trajectories or embedded timeseries (which are also trajectories).
If $x\equiv y$ then $R$ is called recurrence matrix, otherwise it is called cross-recurrence matrix. There is also the joint-recurrence variant, see below. With RecurrenceAnalysis you can use the following functions to access these matrices
Create a recurrence matrix from timeseries or trajectory x and with recurrence threshold rthres. x is either a StateSpaceSet for multivariate data or an AbstractVector{<:Real} for timeseries.
The variable rthres defines how recurrences are estimated. It can be any subtype of AbstractRecurrenceType, and different types can specify recurrences differently. Alternatively, rthres can be a real number, which then becomes an instance of RecurrenceThreshold.
The keyword metric, if given, must be any subtype of Metric from Distances.jl and defines the metric used to calculate distances for recurrences. By default the Euclidean metric is used, typical alternatives are Chebyshev(), Cityblock().
The keyword parallel decides if the comptutation should be done in parallel using threads. Defaults to length(x) > 500 && Threads.nthreads() > 1.
Description
A (cross-)recurrence matrix is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the state space that it was at some previous time.
The recurrence matrix is a numeric representation of a recurrence plot, described in detail in [Marwan2007] and [Marwan2015]. It represents a a sparse square matrix of Boolean values that quantifies recurrences in the trajectory, i.e., points where the trajectory returns close to itself. Given trajectories x, y, and asumming ε isa Real, the matrix is defined as:
R[i,j] = metric(x[i], y[i]) ≤ ε ? true : false
with the metric being the distance function. The difference between a RecurrenceMatrix and a CrossRecurrenceMatrix is that in the first case x === y.
Objects of type <:AbstractRecurrenceMatrix are displayed as a recurrenceplot.
Create a cross recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible value for rthres and kwargs.
The cross recurrence matrix is a bivariate extension of the recurrence matrix. For the time series x, y, of length n and m, respectively, it is a sparse n×m matrix of Boolean values.
Note that cross recurrence matrices are generally not symmetric irrespectively of rthres.
Create a joint recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible values for rthres and kwargs.
The joint recurrence matrix considers the recurrences of the trajectories of x and y separately, and looks for points where both recur simultaneously. It is calculated by the element-wise multiplication of the recurrence matrices of x and y. If x and y are of different length, the recurrences are only calculated until the length of the shortest one.
Supertype of all recurrence specification types. Instances of subtypes are given to RecurrenceMatrix and similar constructors to specify recurrences. Use recurrence_threshold to extract the numeric distance threshold.
Possible subtypes are:
RecurrenceThreshold(ε::Real): Recurrences are defined as any point with distance ≤ ε from the referrence point.
RecurrenceThresholdScaled(ratio::Real, scale::Function): Here scale is a function of the distance matrix dm (see distancematrix) that is used to scale the value of the recurrence threshold ε so that ε = ratio*scale(dm). After the new ε is obtained, the method works just like the RecurrenceThreshold. Specialized versions are employed if scale is mean or maximum.
GlobalRecurrenceRate(q::Real): Here the number of total recurrence rate over the whole matrix is specified to be a quantile q ∈ (0,1) of the distancematrix. In practice this yields (approximately) a ratio q of recurrences out of the total Nx * Ny for input trajectories x, y.
LocalRecurrenceRate(r::Real): The recurrence threhsold here is point-dependent. It is defined so that each point of x has a fixed number of k = r*N neighbors, with ratio r out of the total possible N. Equivalently, this means that each column of the recurrence matrix will have exactly k true entries. Notice that LocalRecurrenceRate does not guarantee that the resulting recurrence matrix will be symmetric.
Recurrences are defined as any point with distance ≤ d from the referrence point, where d is a scaled ratio (specified by ratio, scale) of the distance matrix. See AbstractRecurrenceType for more.
The recurrence matrices are internally stored as sparse matrices with Boolean values. Typically in the literature one does not sees the plots of the matrices (hence "Recurrence Plots"). By default, when a Recurrence Matrix is created we "show" a mini plot of it which is a text-based scatterplot.
Here is an example recurrence plot/matrix of a full trajectory of the Roessler system:
using RecurrenceAnalysis, DynamicalSystemsBase
+\end{cases}\]
where $d(x[i], y[j])$ stands for the distance between trajectory $x$ at point $i$ and trajectory $y$ at point $j$. Both $x, y$ can be single timeseries, full trajectories or embedded timeseries (which are also trajectories).
If $x\equiv y$ then $R$ is called recurrence matrix, otherwise it is called cross-recurrence matrix. There is also the joint-recurrence variant, see below. With RecurrenceAnalysis you can use the following functions to access these matrices
Create a recurrence matrix from timeseries or trajectory x and with recurrence threshold rthres. x is either a StateSpaceSet for multivariate data or an AbstractVector{<:Real} for timeseries.
The variable rthres defines how recurrences are estimated. It can be any subtype of AbstractRecurrenceType, and different types can specify recurrences differently. Alternatively, rthres can be a real number, which then becomes an instance of RecurrenceThreshold.
The keyword metric, if given, must be any subtype of Metric from Distances.jl and defines the metric used to calculate distances for recurrences. By default the Euclidean metric is used, typical alternatives are Chebyshev(), Cityblock().
The keyword parallel decides if the comptutation should be done in parallel using threads. Defaults to length(x) > 500 && Threads.nthreads() > 1.
Description
A (cross-)recurrence matrix is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the state space that it was at some previous time.
The recurrence matrix is a numeric representation of a recurrence plot, described in detail in [Marwan2007] and [Marwan2015]. It represents a a sparse square matrix of Boolean values that quantifies recurrences in the trajectory, i.e., points where the trajectory returns close to itself. Given trajectories x, y, and asumming ε isa Real, the matrix is defined as:
R[i,j] = metric(x[i], y[i]) ≤ ε ? true : false
with the metric being the distance function. The difference between a RecurrenceMatrix and a CrossRecurrenceMatrix is that in the first case x === y.
Objects of type <:AbstractRecurrenceMatrix are displayed as a recurrenceplot.
Create a cross recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible value for rthres and kwargs.
The cross recurrence matrix is a bivariate extension of the recurrence matrix. For the time series x, y, of length n and m, respectively, it is a sparse n×m matrix of Boolean values.
Note that cross recurrence matrices are generally not symmetric irrespectively of rthres.
Create a joint recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible values for rthres and kwargs.
The joint recurrence matrix considers the recurrences of the trajectories of x and y separately, and looks for points where both recur simultaneously. It is calculated by the element-wise multiplication of the recurrence matrices of x and y. If x and y are of different length, the recurrences are only calculated until the length of the shortest one.
Supertype of all recurrence specification types. Instances of subtypes are given to RecurrenceMatrix and similar constructors to specify recurrences. Use recurrence_threshold to extract the numeric distance threshold.
Possible subtypes are:
RecurrenceThreshold(ε::Real): Recurrences are defined as any point with distance ≤ ε from the referrence point.
RecurrenceThresholdScaled(ratio::Real, scale::Function): Here scale is a function of the distance matrix dm (see distancematrix) that is used to scale the value of the recurrence threshold ε so that ε = ratio*scale(dm). After the new ε is obtained, the method works just like the RecurrenceThreshold. Specialized versions are employed if scale is mean or maximum.
GlobalRecurrenceRate(q::Real): Here the number of total recurrence rate over the whole matrix is specified to be a quantile q ∈ (0,1) of the distancematrix. In practice this yields (approximately) a ratio q of recurrences out of the total Nx * Ny for input trajectories x, y.
LocalRecurrenceRate(r::Real): The recurrence threhsold here is point-dependent. It is defined so that each point of x has a fixed number of k = r*N neighbors, with ratio r out of the total possible N. Equivalently, this means that each column of the recurrence matrix will have exactly k true entries. Notice that LocalRecurrenceRate does not guarantee that the resulting recurrence matrix will be symmetric.
Recurrences are defined as any point with distance ≤ d from the referrence point, where d is a scaled ratio (specified by ratio, scale) of the distance matrix. See AbstractRecurrenceType for more.
The recurrence matrices are internally stored as sparse matrices with Boolean values. Typically in the literature one does not sees the plots of the matrices (hence "Recurrence Plots"). By default, when a Recurrence Matrix is created we "show" a mini plot of it which is a text-based scatterplot.
Here is an example recurrence plot/matrix of a full trajectory of the Roessler system:
using RecurrenceAnalysis, DynamicalSystemsBase
# Create trajectory of Roessler system
@inbounds function roessler_rule(u, p, t)
@@ -75,7 +75,7 @@
|:::'.::'.:'':::.::'..::'::'.::'.:':::.:''||::::::::'.::'.::'.::::::'.::'.::||::::::'..::.::':::::'.::.:''|
- +------------------------------------------------------------+
typeof(R)
RecurrenceMatrix{GlobalRecurrenceRate{Float64}}
summary(R)
"(2001, 2001) RecurrenceMatrix with 400401 recurrences of type GlobalRecurrenceRate."
The above simple plotting functionality is possible through the package UnicodePlots. The following function creates the plot:
Create a text-based scatterplot representation of a recurrence matrix R to be displayed in io (by default stdout) using UnicodePlots. The matrix spans at minimum minh rows and at maximum maxh*displaysize(io)[1] (i.e. by default half the display). As we always try to plot in equal aspect ratio, if the width of the plot is even less, the minimum height is dictated by the width.
The keyword ascii::Bool can ensure that all elements of the plot are ASCII characters (true) or Unicode (false).
The rest of the kwargs are propagated into UnicodePlots.scatterplot.
Notice that the accuracy of this function drops drastically for matrices whose size is significantly bigger than the width and height of the display (assuming each index of the matrix is one character).
Create a text-based scatterplot representation of a recurrence matrix R to be displayed in io (by default stdout) using UnicodePlots. The matrix spans at minimum minh rows and at maximum maxh*displaysize(io)[1] (i.e. by default half the display). As we always try to plot in equal aspect ratio, if the width of the plot is even less, the minimum height is dictated by the width.
The keyword ascii::Bool can ensure that all elements of the plot are ASCII characters (true) or Unicode (false).
The rest of the kwargs are propagated into UnicodePlots.scatterplot.
Notice that the accuracy of this function drops drastically for matrices whose size is significantly bigger than the width and height of the display (assuming each index of the matrix is one character).
Here is the same plot but using Unicode Braille characters
recurrenceplot(R; ascii = false)
(2001, 2001) RecurrenceMatrix with 400401 recurrences of type GlobalRecurrenceRate.┌────────────────────────────────────────────────────────────┐│⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⠞⠃⢀⣴⠟⠁⠀⠀⠀⠀⠀⠀⠀⢀⣴⠟⠁⣠⡾⠋⢀⣤⠞⠁⠀⠀⠀⠀⠀⠀⠀⢀⣤⠞⠁⣀⡴⠟⠀⠀⠀⠀⢀⣤⠄⠀⣀⡴⠛││⠀⠀⠀⢀⡀⠀⠀⣠⣴⠟⠁⣠⡾⠋⠁⠀⠀⠀⣠⡴⠛⠀⣠⡾⠋⢀⣠⠘⠉⣀⡴⠟⠁⠀⠀⠀⢀⡀⠀⠀⣠⡶⠟⠁⣠⡾⠋⠀⠀⠀⠀⣠⡶⠋⢀⣠⡾⠋⠀⠀│
@@ -102,7 +102,7 @@
│⣁⣴⡿⠋⣠⣴⠿⠋⣠⡶⠛⠁⠀⠀⠀⠀⣼⠟⢉⣠⡾⠟⠁⣠⠄⠀⠀⢰⠟⠁⠀⠀⠀⠀⢰⡿⠋⣠⣶⠟⠁⣠⡶⠋⠀⠀⠀⠀⠀⣾⠟⢁⣠⡾⠛⠁⠀⠀⠀⠀││⡿⢋⣴⣾⠟⢁⣴⡾⠋⠀⠀⠀⠀⠀⠀⠀⢠⣴⡿⠋⣀⣴⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⠟⣁⣴⡿⠋⠀⠀⠀⠀⠀⠀⠀⣠⣴⡿⠋⣀⣴⠆⠀⠀⠀⠀││⣾⣿⢟⣡⣾⡿⠋⣀⡄⠀⠀⠀⠀⠀⠀⠀⠻⢋⣤⣾⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⢛⣥⣾⠟⠉⣀⠀⠀⠀⠀⠀⠀⠀⠀⠟⢋⣤⡾⠋⠁⠀⠀⠀⠀⠀│
- └────────────────────────────────────────────────────────────┘
As you can see, the Unicode based plotting doesn't display nicely everywhere. It does display perfectly in e.g. VSCode, which is where it is the default printing type.
Transform the recurrence matrix R into a full matrix suitable for plotting as a grayscale image. By default it returns a matrix with the same size as R, but switched axes, containing "black" values in the cells that represent recurrent points, and "white" values in the empty cells and interpolating in-between for cases with both recurrent and empty cells, see below.
The numeric codes for black and white are given in a 2-element tuple as a second optional argument. Its default value is (0.0, 1.0), i.e. black is coded as 0.0 (no brightness) and white as 1.0 (full brightness). The type of the elements in the tuple defines the type of the returned matrix. This must be taken into account if, for instance, the image is coded as a matrix of integers corresponding to a grayscale; in such case the black and white codes must be given as numbers of the required integer type.
The keyword arguments width and height can be given to define a custom size of the image. If only one dimension is given, the other is automatically calculated. If both dimensions are given, by default they are adjusted to keep an aspect proportional to the original matrix, such that the returned matrix fits into a matrix of the given dimensions. This automatic adjustment can be disabled by passing the keyword argument exactsize=true.
If the image has different dimensions than R, the cells of R are distributed in a grid with the size of the image, and a gray level between white and black is calculated for each element of the grid, proportional to the number of recurrent points contained in it. The levels of gray are coded as numbers of the same type as the black and white codes.
It is advised to use width, height arguments for large matrices otherwise plots using functions like e.g. heatmap could be misleading.
For example, here is the representation of the above R from the Roessler system using both plotting approaches:
using CairoMakie
+ └────────────────────────────────────────────────────────────┘
As you can see, the Unicode based plotting doesn't display nicely everywhere. It does display perfectly in e.g. VSCode, which is where it is the default printing type.
Transform the recurrence matrix R into a full matrix suitable for plotting as a grayscale image. By default it returns a matrix with the same size as R, but switched axes, containing "black" values in the cells that represent recurrent points, and "white" values in the empty cells and interpolating in-between for cases with both recurrent and empty cells, see below.
The numeric codes for black and white are given in a 2-element tuple as a second optional argument. Its default value is (0.0, 1.0), i.e. black is coded as 0.0 (no brightness) and white as 1.0 (full brightness). The type of the elements in the tuple defines the type of the returned matrix. This must be taken into account if, for instance, the image is coded as a matrix of integers corresponding to a grayscale; in such case the black and white codes must be given as numbers of the required integer type.
The keyword arguments width and height can be given to define a custom size of the image. If only one dimension is given, the other is automatically calculated. If both dimensions are given, by default they are adjusted to keep an aspect proportional to the original matrix, such that the returned matrix fits into a matrix of the given dimensions. This automatic adjustment can be disabled by passing the keyword argument exactsize=true.
If the image has different dimensions than R, the cells of R are distributed in a grid with the size of the image, and a gray level between white and black is calculated for each element of the grid, proportional to the number of recurrent points contained in it. The levels of gray are coded as numbers of the same type as the black and white codes.
It is advised to use width, height arguments for large matrices otherwise plots using functions like e.g. heatmap could be misleading.
which justifies why recurrence plots are so fitting to be used in embedded timeseries.
Careful when using Recurrence Plots
It is easy when using grayscale to not change the width/height parameters. The width and height are important when in grayscale when the matrix size exceeds the display size! Most plotting libraries may resample arbitrarily or simply limit the displayed pixels, so one needs to be extra careful.
Besides graphical problems there are also other potential pitfalls dealing with the conceptual understanding and use of recurrence plots. All of these are summarized in the following paper which we suggest users to take a look at:
N. Marwan, How to avoid potential pitfalls in recurrence plot based data analysis, Int. J. of Bifurcations and Chaos (arXiv).
The finite size of a recurrence plot can cause border effects in the recurrence quantification-measures rqa. Also the sampling rate of the data and the chosen recurrence threshold selection method (fixed, fixedrate, FAN) plays a crucial role. They can cause the thickening of diagonal lines in the recurrence matrix. Both problems lead to biased line-based RQA-quantifiers and is discussed in:
K.H. Kraemer & N. Marwan, Border effect corrections for diagonal line based recurrence quantification analysis measures, Phys. Lett. A 2019.
Skeletonize the RecurrenceMatrix R by using the algorithm proposed by Kraemer & Marwan [Kraemer2019]. This function returns R_skel, a recurrence matrix, which only consists of diagonal lines of "thickness" one.
Consider, e.g. a skeletonized version of a simple sinusoidal:
using RecurrenceAnalysis, DelayEmbeddings, CairoMakie
+fig
which justifies why recurrence plots are so fitting to be used in embedded timeseries.
Careful when using Recurrence Plots
It is easy when using grayscale to not change the width/height parameters. The width and height are important when in grayscale when the matrix size exceeds the display size! Most plotting libraries may resample arbitrarily or simply limit the displayed pixels, so one needs to be extra careful.
Besides graphical problems there are also other potential pitfalls dealing with the conceptual understanding and use of recurrence plots. All of these are summarized in the following paper which we suggest users to take a look at:
N. Marwan, How to avoid potential pitfalls in recurrence plot based data analysis, Int. J. of Bifurcations and Chaos (arXiv).
The finite size of a recurrence plot can cause border effects in the recurrence quantification-measures rqa. Also the sampling rate of the data and the chosen recurrence threshold selection method (fixed, fixedrate, FAN) plays a crucial role. They can cause the thickening of diagonal lines in the recurrence matrix. Both problems lead to biased line-based RQA-quantifiers and is discussed in:
K.H. Kraemer & N. Marwan, Border effect corrections for diagonal line based recurrence quantification analysis measures, Phys. Lett. A 2019.
Skeletonize the RecurrenceMatrix R by using the algorithm proposed by Kraemer & Marwan [Kraemer2019]. This function returns R_skel, a recurrence matrix, which only consists of diagonal lines of "thickness" one.
The distance function used in RecurrenceMatrix and co. can be specified either as any Metric instance from Distances. In addition, the following function returns a matrix with the cross-distances across all points in one or two trajectories:
Create a matrix with the distances between each pair of points of the time series x and y using metric.
The time series x and y can be AbstractDatasets or vectors or matrices with data points in rows. The data point dimensions (or number of columns) must be the same for x and y. The returned value is a n×m matrix, with n being the length (or number of rows) of x, and m the length of y.
The metric can be any of the Metrics defined in the Distances package and defaults to Euclidean().
A dedicated interface for sets in a state space. It is an ordered container of equally-sized points of length D. Each point is represented by SVector{D, T}. The data are a standard Julia Vector{SVector}, and can be obtained with vec(ssset::StateSpaceSet). Typically the order of points in the set is the time direction, but it doesn't have to be.
When indexed with 1 index, StateSpaceSet is like a vector of points. When indexed with 2 indices it behaves like a matrix that has each of the columns be the timeseries of each of the variables. When iterated over, it iterates over its contained points. See description of indexing below for more.
StateSpaceSet also supports almost all sensible vector operations like append!, push!, hcat, eachrow, among others.
Description of indexing
In the following let i, j be integers, typeof(X) <: AbstractStateSpaceSet and v1, v2 be <: AbstractVector{Int} (v1, v2 could also be ranges, and for performance benefits make v2 an SVector{Int}).
X[i] == X[i, :] gives the ith point (returns an SVector)
X[v1] == X[v1, :], returns a StateSpaceSet with the points in those indices.
X[:, j] gives the jth variable timeseries (or collection), as Vector
X[v1, v2], X[:, v2] returns a StateSpaceSet with the appropriate entries (first indices being "time"/point index, while second being variables)
X[i, j] value of the jth variable, at the ith timepoint
Use Matrix(ssset) or StateSpaceSet(matrix) to convert. It is assumed that each column of the matrix is one variable. If you have various timeseries vectors x, y, z, ... pass them like StateSpaceSet(x, y, z, ...). You can use columns(dataset) to obtain the reverse, i.e. all columns of the dataset in a tuple.
The distance function used in RecurrenceMatrix and co. can be specified either as any Metric instance from Distances. In addition, the following function returns a matrix with the cross-distances across all points in one or two trajectories:
Create a matrix with the distances between each pair of points of the time series x and y using metric.
The time series x and y can be AbstractStateSpaceSets or vectors or matrices with data points in rows. The data point dimensions (or number of columns) must be the same for x and y. The returned value is a n×m matrix, with n being the length (or number of rows) of x, and m the length of y.
The metric can be any of the Metrics defined in the Distances package and defaults to Euclidean().
A dedicated interface for sets in a state space. It is an ordered container of equally-sized points of length D, with element type T, represented by a vector of type V. Typically V is SVector{D,T} or Vector{T} and the data are always stored internally as Vector{V}.
The underlying Vector{V} can be obtained by vec(ssset), although this is almost never necessary because StateSpaceSet subtypes AbstractVector and extends its interface. StateSpaceSet also supports almost all sensible vector operations like append!, push!, hcat, eachrow, among others. When iterated over, it iterates over its contained points.
Construction
Constructing a StateSpaceSet is done in three ways:
By giving in each individual columns of the state space set as Vector{<:Real}: StateSpaceSet(x, y, z, ...).
By giving in a matrix whose rows are the state space points: StateSpaceSet(m).
By giving in directly a vector of vectors (state space points): StateSpaceSet(v_of_v).
All constructors allow for the keyword container which sets the type of V (the type of inner vectors). At the moment options are only SVector, MVector, or Vector, and by default SVector is used.
Description of indexing
When indexed with 1 index, StateSpaceSet behaves exactly like its encapsulated vector. i.e., a vector of vectors (state space points). When indexed with 2 indices it behaves like a matrix where each row is a point.
In the following let i, j be integers, typeof(X) <: AbstractStateSpaceSet and v1, v2 be <: AbstractVector{Int} (v1, v2 could also be ranges, and for performance benefits make v2 an SVector{Int}).
X[i] == X[i, :] gives the ith point (returns an SVector)
X[v1] == X[v1, :], returns a StateSpaceSet with the points in those indices.
X[:, j] gives the jth variable timeseries (or collection), as Vector
X[v1, v2], X[:, v2] returns a StateSpaceSet with the appropriate entries (first indices being "time"/point index, while second being variables)
X[i, j] value of the jth variable, at the ith timepoint
Use Matrix(ssset) or StateSpaceSet(matrix) to convert. It is assumed that each column of the matrix is one variable. If you have various timeseries vectors x, y, z, ... pass them like StateSpaceSet(x, y, z, ...). You can use columns(dataset) to obtain the reverse, i.e. all columns of the dataset in a tuple.
This document was generated with Documenter.jl version 1.7.0 on Monday 23 September 2024. Using Julia version 1.10.5.
diff --git a/dev/search_index.js b/dev/search_index.js
index 4150453..62f41d0 100644
--- a/dev/search_index.js
+++ b/dev/search_index.js
@@ -1,3 +1,3 @@
var documenterSearchIndex = {"docs":
-[{"location":"networks/#Recurrence-Networks","page":"Recurrence Networks","title":"Recurrence Networks","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"Recurrence matrices can be reinterpreted as adjacency matrices of complex networks embedded in state space, such that each node or vertex of the network corresponds to a point of the timeseries, and the links of the network connect pairs of points that are mutually close the phase space. The relationship between a recurrence matrix R and its corresponding adjacency matrix A is:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"Rij = Aij - deltaij","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"i.e. there is an edge in the associated network between every two neighboring points in the phase space, excluding self-connections (points in the Line Of Identity or main diagonal of R).","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"This definition assumes that A represents an undirected graph, so R must be a symmetric matrix as corresponding to a RecurrenceMatrix or a JointRecurrenceMatrix.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"While RQA characterizes the properties of line structures in the recurrence plots, which consider dynamical aspects (e.g. continuity of recurrences, length of sequences, etc.), the analysis of recurrence networks does not take into account time information, since network properties are independent of the ordering of vertices. On the other hand, recurrence network analysis (RNA) provides information about geometric characteristics of the state space, like homogeneity of the connections, clustering of points, etc. More details about the theoretical framework of RNA can be found in the following papers:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010)\nR.V. Donner et al. \"Complex Network Analysis of Recurrences\", in: Webber, C.L. & Marwan N. (eds.) Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 101-165 (2015).","category":"page"},{"location":"networks/#Creation-and-visualization-of-Recurrence-Networks","page":"Recurrence Networks","title":"Creation and visualization of Recurrence Networks","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"The JuliaGraphs organization provides multiple packages for Julia to create, visualize and analyze complex networks. In particular, the package LightGraphs defines the type SimpleGraph that can be used to represent undirected networks. Such graphs can be created from symmetric recurrence matrices, as in the following example with a Hénon map:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"using RecurrenceAnalysis, DynamicalSystemsBase\nusing Graphs: SimpleGraph\n\n# make trajectory of Henon map\nhenon_rule(x, p, n) = SVector(1.0 - p[1]*x[1]^2 + x[2], p[2]*x[1])\nu0 = zeros(2)\np0 = [1.4, 0.3]\nhenon = DeterministicIteratedMap(henon_rule, u0, p0)\nX, t = trajectory(henon, 200)\n# Cast it into a recurrence network\nR = RecurrenceMatrix(X, 0.25; metric = Chebyshev())\nnetwork = SimpleGraph(R)","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"There are various plotting tools that can be used to visualize such graphs. For instance, the following plot made with the package GraphMakie.jl.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"using GraphMakie, CairoMakie\ngraphplot(network)","category":"page"},{"location":"networks/#Recurrence-Network-measures","page":"Recurrence Networks","title":"Recurrence Network measures","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"LightGraphs has a large set of functions to extract local measures (associated to particular vertices or edges) and global coefficients associated to the whole network. For SimpleGraphs created from recurrence matrices, as the variable network in the previous example, the vertices are labelled with numeric indices following the same ordering as the rows or columns of the given matrix. So for instance degree(network, i) would give the degree of the i-th point of the timeseries (number of connections with other points), whereas degree(network) would give a vector of such measures ordered as the original timeseries.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"As in RQA, we provide a function that computes a selection of commonly used global RNA measures, directly from the recurrence matrix:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"rna","category":"page"},{"location":"networks/#RecurrenceAnalysis.rna","page":"Recurrence Networks","title":"RecurrenceAnalysis.rna","text":"rna(R::AbstractRecurrenceMatrix)\nrna(args...; kwargs...)\n\nCalculate a set of Recurrence Network parameters. The input R can be a symmetric recurrence matrix that is interpreted as the adjacency matrix of an undirected complex network, such that linked vertices are neighboring points in the phase space.\n\nAlternatively, the inputs can be a graph object or any valid inputs to the SimpleGraph constructor of the Graphs package.\n\nReturn\n\nThe returned value is a dictionary that contains the following entries, with the corresponding global network properties[1, 2]:\n\n:density: edge density, approximately equivalent to the global recurrence rate in the phase space.\n:transitivity: network transitivity, which describes the\n\nglobal clustering of points following Barrat's and Weigt's formulation [3].\n\n:averagepath: mean value of the shortest path lengths taken over\n\nall pairs of connected vertices, related to the average separation between points in the phase.\n\n:diameter: maximum value of the shortest path lengths between\n\npairs of connected vertices, related to the phase space diameter.\n\nReferences\n\n[1]: R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025\n\n[2]: R.V. Donner et al., The geometry of chaotic dynamics — a complex network perspective, Eur. Phys. J. B 84, 653–672 (2011) DOI:10.1140/epjb/e2011-10899-1\n\n[3]: A. Barrat & M. Weight, \"On the properties of small-world network models\", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067\n\n\n\n\n\n","category":"function"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"note: Transitivity and global clustering coefficient\nThe concept of clustering coefficient at local level (for individual nodes of the network) is clearly defined as the fraction of connecting nodes that are also connected between them, forming \"triangles\". But at global level it is a source of confusion: the term of \"global clustering coefficient\" was originally used by Watts and Strogatz[1], referred to the average of local clustering coefficient across all the graph's nodes. But Barrat and Weigt proposed an alternative definition[2] that characterizes the effective global dimensionality of the system, giving equal weight to all triangles in the network[3].This second definition is often named with the distinctive term of \"transitivity\", as in the output of rna, whereas the corresponding function of the LightGraphs package is global_clustering_coefficient. The \"global clustering coefficient\" as by Watts and Strogatz could be obtained as mean(local_clustering_coefficient(network)) – with network being a graph object as in the previous example. (The function mean is in the Julia standard library, and can be brought into scope with the command using Statistics.)","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[1]: D.J. Watts & S.H. Strogatz, \"Collective dynamics of 'small-world' networks\", Nature 393(6684), 440–442 (1998) DOI:10.1038%2F30918","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[2]: A. Barrat & M. Weight, \"On the properties of small-world network models\", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[3]: R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025","category":"page"},{"location":"quantification/#Recurrence-Quantification-Analysis","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"A RecurrenceMatrix can be analyzed in several ways to yield information about the dynamics of the trajectory. All these various measures and functions are collectively called \"Recurrence Quantification Analysis\" (RQA).","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"To understand how each measure can be useful, we suggest to see the review articles listed in our documentation strings, namely:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"N. Marwan et al., \"Recurrence plots for the analysis of complex systems\", Phys. Reports 438(5-6), 237-329 (2007).\nN. 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).","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"You can also check the wikipedia page for Recurrence quantification analysis.","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"The functions described in this page all accept a recurrence matrix (x), see RecurrenceMatrix.","category":"page"},{"location":"quantification/#RQA-Measures","page":"Recurrence Quantification Analysis","title":"RQA Measures","text":"","category":"section"},{"location":"quantification/#All-in-one-Bundle","page":"Recurrence Quantification Analysis","title":"All-in-one Bundle","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"In case you need all of the RQA-related functions (see below) and you don't want to write 10 lines of code to compute them all (since they are so many) we provide an all-in-one function that computes all of them and returns a dictionary with the results!","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"rqa","category":"page"},{"location":"quantification/#RecurrenceAnalysis.rqa","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rqa","text":"rqa(R; kwargs...)\n\nCalculate 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.\n\nReturn\n\nThe returned value contains the following entries, which can be retrieved as from a dictionary (e.g. results[:RR], etc.):\n\n:RR: recurrence rate (see recurrencerate)\n:DET: determinsm (see determinism)\n:L: average length of diagonal structures (see dl_average)\n:Lmax: maximum length of diagonal structures (see dl_max)\n:DIV: divergence (see divergence)\n:ENTR: entropy of diagonal structures (see dl_entropy)\n:TREND: trend of recurrences (see trend)\n:LAM: laminarity (see laminarity)\n:TT: trapping time (see trappingtime)\n:Vmax: maximum length of vertical structures (see vl_max)\n:VENTR: entropy of vertical structures (see vl_entropy)\n:MRT: mean recurrence time (see meanrecurrencetime)\n:RTE recurrence time entropy (see rt_entropy)\n:NMPRT: number of the most probable recurrence time (see nmprt)\n\nAll 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.\n\nKeyword Arguments\n\nStandard keyword arguments are the ones accepted by the functions listed below, i.e. theiler, lmin, and border:\n\ntheiler 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).\nlmin 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).\nborder is used to avoid border effects in the calculation of :TREND (cf. trend).\n\nIn 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.\n\nThe 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.\n\nTransitional note on the returned type\n\nIn 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.\n\nIn 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:\n\nrqa(NamedTuple, R...) to obtain the output of the older version (as in 1.3).\nrqa(Dict, R...) to obtain the output of the planned future version.\nrqa(RQA, R...) to obtain the default current output (same as rqa(R...))\nrqa(DT,R...) to obtain the output as DT which is a subtype of AbstractDict (e.g. rqa(OrderedDict,R...) returns an OrderedDict)\n\n\n\n\n\n","category":"function"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"note: Return values for empty histograms\nIt may be the case that for a given recurrence matrix some structures do not exist at all. For example there are recurrence matrices that have no vertical lengths (or no vertical lengths with length less than lmin). In such cases the behavior of our RQA pipeline is the following:Quantities that represent maximum or average values are 0.0.\nQuantities that represent entropies are NaN.","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"See also the [windowed] function for a windowed version of rqa.","category":"page"},{"location":"quantification/#Example","page":"Recurrence Quantification Analysis","title":"Example","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"For example, here are the RQA measures for the same example trajectory we used to make Simple Recurrence Plots","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"using RecurrenceAnalysis, DynamicalSystemsBase\n\n# Create trajectory of Roessler system\n@inbounds function roessler_rule(u, p, t)\n a, b, c = p\n du1 = -u[2]-u[3]\n du2 = u[1] + a*u[2]\n du3 = b + u[3]*(u[1] - c)\n return SVector(du1, du2, du3)\nend\np0 = [0.15, 0.2, 10.0]\nu0 = ones(3)\nro = CoupledODEs(roessler_rule, u0, p0)\nN = 2000; Δt = 0.05\nX, t = trajectory(ro, N*Δt; Δt, Ttr = 10.0)\n\n# Make a recurrence matrix with fixed threshold\nR = RecurrenceMatrix(X, 5.0)\n\n# Compute RQA measures\nrqa(R)","category":"page"},{"location":"quantification/#Classical-RQA-Measures","page":"Recurrence Quantification Analysis","title":"Classical RQA Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"recurrencerate\ndeterminism\ndl_average\ndl_max\ndl_entropy\ndivergence\ntrend","category":"page"},{"location":"quantification/#RecurrenceAnalysis.recurrencerate","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.recurrencerate","text":"recurrencerate(R[; theiler])\n\nCalculate the recurrence rate of the recurrence matrix R.\n\nDescription\n\nThe recurrence rate is calculated as:\n\nRR = frac1S sum R\n\nwhere 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].\n\nFor 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).\n\nHint: 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.\n\nReferences\n\n[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\n\n[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\n\n[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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.determinism","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.determinism","text":"determinism(R[; lmin=2, theiler])\n\nCalculate the determinism of the recurrence matrix R:\n\nDescription\n\nThe determinism is calculated as:\n\nDET = fracsum_l=lminl P(l)sum_l=1l P(l) =\nfracsum_l=lminl P(l)sum R\n\nwhere l stands for the lengths of diagonal lines in the matrix, and P(l) is the number of lines of length equal to l.\n\nlmin 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_average","text":"dl_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_max","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_max","text":"dl_max(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_entropy","text":"dl_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.divergence","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.divergence","text":"divergence(R[; theiler])\n\nCalculate the divergence of the recurrence matrix R (actually the inverse of dl_max).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.trend","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.trend","text":"trend(R[; border=10, theiler])\n\nCalculate the trend of recurrences in the recurrence matrix R.\n\nDescription\n\nThe 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.\n\nIt is calculated as:\n\nTREND = 10^3fracsum_d=tau^tildeNdeltadleft(RRd-langle RRdrangleright)sum_d=tau^tildeNdeltad^2\n\nwhere RRd is the local recurrence rate of the diagonal d, deltad 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 tildeN is the number of the outmost diagonal that is included.\n\nThis parameter is expressed in units of variation recurrence rate every 1000 data points, hence the factor 10^3 in the formula [1].\n\nThe 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).\n\nNote: 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.\n\nReferences\n\n[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\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Extended-RQA-Measures","page":"Recurrence Quantification Analysis","title":"Extended RQA Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"laminarity\ntrappingtime\nvl_average\nvl_max\nvl_entropy","category":"page"},{"location":"quantification/#RecurrenceAnalysis.laminarity","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.laminarity","text":"laminarity(R[; lmin=2, theiler])\n\nCalculate the laminarity of the recurrence matrix R.\n\nDescription\n\nThe laminarity is calculated as:\n\nLAM = fracsum_v=lminv P(l)sum_v=1v P(v) =\nfracsum_v=lminv P(l)sum R\n\nwhere v stands for the lengths of vertical lines in the matrix, and P(v) is the number of lines of length equal to v.\n\nlmin 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.trappingtime","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.trappingtime","text":"trappingtime(R[; lmin=2, theiler])\n\nCalculate 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).\n\nThe trapping time is the average of the vertical line structures and thus equal to vl_average.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_average","text":"vl_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_max","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_max","text":"vl_max(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_entropy","text":"vl_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Recurrence-Time-Measures","page":"Recurrence Quantification Analysis","title":"Recurrence Time Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"meanrecurrencetime\nnmprt\nrt_entropy\nrt_average","category":"page"},{"location":"quantification/#RecurrenceAnalysis.meanrecurrencetime","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.meanrecurrencetime","text":"meanrecurrencetime(R[; lmin=2, theiler])\n\nCalculate 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).\n\nEquivalent to rt_average.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.nmprt","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.nmprt","text":"nmprt(R[; lmin=2, theiler])\n\nCalculate 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).\n\nThis 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].\n\nReferences\n\n[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\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.rt_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rt_entropy","text":"rt_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.rt_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rt_average","text":"rt_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Keyword-table","page":"Recurrence Quantification Analysis","title":"Keyword table","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"Since most of the above functions can be fined tuned with keyword arguments, here is a table summarizing them that could be of use:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"Argument Default Functions Description\ntheiler 0 for CrossRecurrenceMatrix, 1 otherwise. recurrencerate, determinism, *_average, *_max, *_entropy, divergence, trend, laminarity, trappingtime, meanrecurrencetime, nmprt Theiler window: number of diagonals around the LOI excluded from the analysis. The value 0 means that the LOI is included in the analysis. Use 1 to exclude the LOI.\nlmin 2 determinism, *_average, *_max, *_entropy, divergence, laminarity, trappingtime, meanrecurrencetime, nmprt Minimum length of the recurrent structures (diagonal or vertical) considered in the analysis.\nborder 10 trend Number of diagonals excluded from the analysis near the border of the matrix.","category":"page"},{"location":"quantification/#Recurrence-Structures-Histograms","page":"Recurrence Quantification Analysis","title":"Recurrence Structures Histograms","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"The functions that we list in this page internally compute histograms of some recurrence structures, like e.g. the vertical lengths. You can access these values directly with the following function:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"recurrencestructures","category":"page"},{"location":"quantification/#RecurrenceAnalysis.recurrencestructures","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.recurrencestructures","text":"recurrencestructures(x::AbstractRecurrenceMatrix;\n diagonal=true,\n vertical=true,\n recurrencetimes=true,\n kwargs...)\n\nReturn 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.\n\nDescription\n\nEach 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.\n\n\"diagonal\" counts the diagonal lines, i.e. the recurrent trajectories.\n\"vertical\" counts the vertical lines, i.e. the laminar states.\n\"recurrencetimes\" counts the vertical distances between recurrent states, i.e. the recurrence times.\n\nAll 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.\n\n\"Empty\" histograms are represented always as [0].\n\nNotice: 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].\n\nReferences\n\n[1] J. Gao & H. Cai. \"On the structures and quantification of recurrence plots\". Physics Letters A, 270(1-2), 75–87 (2000).\n\n[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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Windowed-application","page":"Recurrence Quantification Analysis","title":"Windowed application","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"windowed","category":"page"},{"location":"quantification/#RecurrenceAnalysis.windowed","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.windowed","text":"windowed(rmat, f, width, step = 1; kwargs...)\n\nA 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...).\n\n\n\n\n\n","category":"function"},{"location":"#RecurrenceAnalysis.jl","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"","category":"section"},{"location":"","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"RecurrenceAnalysis","category":"page"},{"location":"#RecurrenceAnalysis","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis","text":"RecurrenceAnalysis.jl\n\n(Image: docsdev) (Image: docsstable) (Image: CI) (Image: codecov) (Image: Package Downloads)\n\nA Julia package that offers tools for computing Recurrence Plots and exploring them within the framework of Recurrence Quantification Analysis and Recurrence Network Analysis. It can be used as a standalone package, or as part of DynamicalSystems.jl.\n\nTo install it, run import Pkg; Pkg.add(\"RecurrenceAnalysis\").\n\nAll further information is provided in the documentation, which you can either find online or build locally by running the docs/make.jl file.\n\n\n\n\n\n","category":"module"},{"location":"","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"note: References\nWant to learn more about recurrence quantification analysis? Here are some resources:Chapter 9 of Nonlinear Dynamics, Datseris & Parlitz, Springer 2022.\nWebber, C. L., & Marwan, N. (2015). Recurrence Quantification Analysis. (C. L. Webber, & N. Marwan, Eds.). Cham: Springer International Publishing. https://doi.org/10.1007/978-3-319-07155-8\nMarwan, N., Carmen Romano, M., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. Physics Reports, 438(5–6), 237–329. https://doi.org/10.1016/j.physrep.2006.11.001","category":"page"},{"location":"rplots/#Recurrence-Plots","page":"Recurrence Plots","title":"Recurrence Plots","text":"","category":"section"},{"location":"rplots/#Recurrence-Matrices","page":"Recurrence Plots","title":"Recurrence Matrices","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"A Recurrence plot (which refers to the plot of a recurrence matrix) is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the phase space that it was at some previous time.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The central structure used in these recurrences is the (cross-) recurrence matrix:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Ri j = begincases\n1 quad textifquad d(xi yj) le varepsilon\n0 quad textelse\nendcases","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"where d(xi yj) stands for the distance between trajectory x at point i and trajectory y at point j. Both x y can be single timeseries, full trajectories or embedded timeseries (which are also trajectories).","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"If xequiv y then R is called recurrence matrix, otherwise it is called cross-recurrence matrix. There is also the joint-recurrence variant, see below. With RecurrenceAnalysis you can use the following functions to access these matrices","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"RecurrenceMatrix\nCrossRecurrenceMatrix\nJointRecurrenceMatrix","category":"page"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceMatrix","text":"RecurrenceMatrix(x, rthres; metric = Euclidean(), parallel::Bool)\n\nCreate a recurrence matrix from timeseries or trajectory x and with recurrence threshold rthres. x is either a StateSpaceSet for multivariate data or an AbstractVector{<:Real} for timeseries.\n\nThe variable rthres defines how recurrences are estimated. It can be any subtype of AbstractRecurrenceType, and different types can specify recurrences differently. Alternatively, rthres can be a real number, which then becomes an instance of RecurrenceThreshold.\n\nThe keyword metric, if given, must be any subtype of Metric from Distances.jl and defines the metric used to calculate distances for recurrences. By default the Euclidean metric is used, typical alternatives are Chebyshev(), Cityblock().\n\nThe keyword parallel decides if the comptutation should be done in parallel using threads. Defaults to length(x) > 500 && Threads.nthreads() > 1.\n\nDescription\n\nA (cross-)recurrence matrix is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the state space that it was at some previous time.\n\nThe recurrence matrix is a numeric representation of a recurrence plot, described in detail in [Marwan2007] and [Marwan2015]. It represents a a sparse square matrix of Boolean values that quantifies recurrences in the trajectory, i.e., points where the trajectory returns close to itself. Given trajectories x, y, and asumming ε isa Real, the matrix is defined as:\n\nR[i,j] = metric(x[i], y[i]) ≤ ε ? true : false\n\nwith the metric being the distance function. The difference between a RecurrenceMatrix and a CrossRecurrenceMatrix is that in the first case x === y.\n\nObjects of type <:AbstractRecurrenceMatrix are displayed as a recurrenceplot.\n\nSee also: CrossRecurrenceMatrix, JointRecurrenceMatrix and use recurrenceplot to turn the result of these functions into a plottable format.\n\n[Marwan2007]: N. Marwan et al., \"Recurrence plots for the analysis of complex systems\", Phys. Reports 438*(5-6), 237-329 (2007)\n\n[Marwan2015]: N. Marwan & C.L. Webber, Recurrence Quantification Analysis. Theory and Best Practices Springer (2015)\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.CrossRecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.CrossRecurrenceMatrix","text":"CrossRecurrenceMatrix(x, y, rthres; kwargs...)\n\nCreate a cross recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible value for rthres and kwargs.\n\nThe cross recurrence matrix is a bivariate extension of the recurrence matrix. For the time series x, y, of length n and m, respectively, it is a sparse n×m matrix of Boolean values.\n\nNote that cross recurrence matrices are generally not symmetric irrespectively of rthres.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.JointRecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.JointRecurrenceMatrix","text":"JointRecurrenceMatrix(x, y, rthres; kwargs...)\n\nCreate a joint recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible values for rthres and kwargs.\n\nThe joint recurrence matrix considers the recurrences of the trajectories of x and y separately, and looks for points where both recur simultaneously. It is calculated by the element-wise multiplication of the recurrence matrices of x and y. If x and y are of different length, the recurrences are only calculated until the length of the shortest one.\n\nSee RecurrenceMatrix for details, references and keywords.\n\n\n\n\n\nJointRecurrenceMatrix(R1::AbstractRecurrenceMatrix, R2::AbstractRecurrenceMatrix)\n\nEquivalent with R1 .* R2.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#Advanced-recurrences-specification","page":"Recurrence Plots","title":"Advanced recurrences specification","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"AbstractRecurrenceType\nRecurrenceThreshold\nRecurrenceThresholdScaled\nGlobalRecurrenceRate\nLocalRecurrenceRate\nrecurrence_threshold","category":"page"},{"location":"rplots/#RecurrenceAnalysis.AbstractRecurrenceType","page":"Recurrence Plots","title":"RecurrenceAnalysis.AbstractRecurrenceType","text":"AbstractRecurrenceType\n\nSupertype of all recurrence specification types. Instances of subtypes are given to RecurrenceMatrix and similar constructors to specify recurrences. Use recurrence_threshold to extract the numeric distance threshold.\n\nPossible subtypes are:\n\nRecurrenceThreshold(ε::Real): Recurrences are defined as any point with distance ≤ ε from the referrence point.\nRecurrenceThresholdScaled(ratio::Real, scale::Function): Here scale is a function of the distance matrix dm (see distancematrix) that is used to scale the value of the recurrence threshold ε so that ε = ratio*scale(dm). After the new ε is obtained, the method works just like the RecurrenceThreshold. Specialized versions are employed if scale is mean or maximum.\nGlobalRecurrenceRate(q::Real): Here the number of total recurrence rate over the whole matrix is specified to be a quantile q ∈ (0,1) of the distancematrix. In practice this yields (approximately) a ratio q of recurrences out of the total Nx * Ny for input trajectories x, y.\nLocalRecurrenceRate(r::Real): The recurrence threhsold here is point-dependent. It is defined so that each point of x has a fixed number of k = r*N neighbors, with ratio r out of the total possible N. Equivalently, this means that each column of the recurrence matrix will have exactly k true entries. Notice that LocalRecurrenceRate does not guarantee that the resulting recurrence matrix will be symmetric.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceThreshold","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceThreshold","text":"RecurrenceThreshold(ε::Real)\n\nRecurrences are defined as any point with distance ≤ ε from the referrence point. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceThresholdScaled","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceThresholdScaled","text":"RecurrenceThresholdScaled(ratio::Real, scale::Function)\n\nRecurrences are defined as any point with distance ≤ d from the referrence point, where d is a scaled ratio (specified by ratio, scale) of the distance matrix. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.GlobalRecurrenceRate","page":"Recurrence Plots","title":"RecurrenceAnalysis.GlobalRecurrenceRate","text":"GlobalRecurrenceRate(rate::Real)\n\nRecurrences are defined as a constant global recurrence rate. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.LocalRecurrenceRate","page":"Recurrence Plots","title":"RecurrenceAnalysis.LocalRecurrenceRate","text":"LocalRecurrenceRate(rate::Real)\n\nRecurrences are defined as a constant local recurrence rate. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.recurrence_threshold","page":"Recurrence Plots","title":"RecurrenceAnalysis.recurrence_threshold","text":"recurrence_threshold(rt::AbstractRecurrenceType, x [, y] [, metric]) → ε\n\nReturn the calculated distance threshold ε for rt. The output is real, unless rt isa LocalRecurrenceRate, where ε isa Vector.\n\n\n\n\n\n","category":"function"},{"location":"rplots/#Simple-Recurrence-Plots","page":"Recurrence Plots","title":"Simple Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The recurrence matrices are internally stored as sparse matrices with Boolean values. Typically in the literature one does not sees the plots of the matrices (hence \"Recurrence Plots\"). By default, when a Recurrence Matrix is created we \"show\" a mini plot of it which is a text-based scatterplot.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Here is an example recurrence plot/matrix of a full trajectory of the Roessler system:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using RecurrenceAnalysis, DynamicalSystemsBase\n\n# Create trajectory of Roessler system\n@inbounds function roessler_rule(u, p, t)\n a, b, c = p\n du1 = -u[2]-u[3]\n du2 = u[1] + a*u[2]\n du3 = b + u[3]*(u[1] - c)\n return SVector(du1, du2, du3)\nend\np0 = [0.15, 0.2, 10.0]\nu0 = ones(3)\nro = CoupledODEs(roessler_rule, u0, p0)\nN = 2000; Δt = 0.05\nX, t = trajectory(ro, N*Δt; Δt, Ttr = 10.0)\n\n# Make a recurrence matrix with fixed threshold\nR = RecurrenceMatrix(X, 5.0)\nrecurrenceplot(R; ascii = true)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Or make a recurrence matrix with fixed (global) recurrence rate of 10%","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"R = RecurrenceMatrix(X, GlobalRecurrenceRate(0.1))\nrecurrenceplot(R; ascii = true)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"typeof(R)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"summary(R)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The above simple plotting functionality is possible through the package UnicodePlots. The following function creates the plot:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"recurrenceplot","category":"page"},{"location":"rplots/#RecurrenceAnalysis.recurrenceplot","page":"Recurrence Plots","title":"RecurrenceAnalysis.recurrenceplot","text":"recurrenceplot([io,] R; minh = 25, maxh = 0.5, ascii, kwargs...) -> u\n\nCreate a text-based scatterplot representation of a recurrence matrix R to be displayed in io (by default stdout) using UnicodePlots. The matrix spans at minimum minh rows and at maximum maxh*displaysize(io)[1] (i.e. by default half the display). As we always try to plot in equal aspect ratio, if the width of the plot is even less, the minimum height is dictated by the width.\n\nThe keyword ascii::Bool can ensure that all elements of the plot are ASCII characters (true) or Unicode (false).\n\nThe rest of the kwargs are propagated into UnicodePlots.scatterplot.\n\nNotice that the accuracy of this function drops drastically for matrices whose size is significantly bigger than the width and height of the display (assuming each index of the matrix is one character).\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Here is the same plot but using Unicode Braille characters","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"recurrenceplot(R; ascii = false)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"As you can see, the Unicode based plotting doesn't display nicely everywhere. It does display perfectly in e.g. VSCode, which is where it is the default printing type.","category":"page"},{"location":"rplots/#Advanced-Recurrence-Plots","page":"Recurrence Plots","title":"Advanced Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"A text-based plot is cool, fast and simple. But often one needs the full resolution offered by the data of a recurrence matrix.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"There are two more ways to plot a recurrence matrix using RecurrenceAnalysis:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"coordinates\ngrayscale","category":"page"},{"location":"rplots/#RecurrenceAnalysis.coordinates","page":"Recurrence Plots","title":"RecurrenceAnalysis.coordinates","text":"coordinates(R) -> xs, ys\n\nReturn the coordinates of the recurrence points of R (in indices).\n\n\n\n\n\n","category":"function"},{"location":"rplots/#RecurrenceAnalysis.grayscale","page":"Recurrence Plots","title":"RecurrenceAnalysis.grayscale","text":"grayscale(R [, bwcode]; width::Int, height::Int, exactsize=false)\n\nTransform the recurrence matrix R into a full matrix suitable for plotting as a grayscale image. By default it returns a matrix with the same size as R, but switched axes, containing \"black\" values in the cells that represent recurrent points, and \"white\" values in the empty cells and interpolating in-between for cases with both recurrent and empty cells, see below.\n\nThe numeric codes for black and white are given in a 2-element tuple as a second optional argument. Its default value is (0.0, 1.0), i.e. black is coded as 0.0 (no brightness) and white as 1.0 (full brightness). The type of the elements in the tuple defines the type of the returned matrix. This must be taken into account if, for instance, the image is coded as a matrix of integers corresponding to a grayscale; in such case the black and white codes must be given as numbers of the required integer type.\n\nThe keyword arguments width and height can be given to define a custom size of the image. If only one dimension is given, the other is automatically calculated. If both dimensions are given, by default they are adjusted to keep an aspect proportional to the original matrix, such that the returned matrix fits into a matrix of the given dimensions. This automatic adjustment can be disabled by passing the keyword argument exactsize=true.\n\nIf the image has different dimensions than R, the cells of R are distributed in a grid with the size of the image, and a gray level between white and black is calculated for each element of the grid, proportional to the number of recurrent points contained in it. The levels of gray are coded as numbers of the same type as the black and white codes.\n\nIt is advised to use width, height arguments for large matrices otherwise plots using functions like e.g. heatmap could be misleading.\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"For example, here is the representation of the above R from the Roessler system using both plotting approaches:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using CairoMakie\nfig = Figure(resolution = (1000,500))\n\nax = Axis(fig[1,1])\nxs, ys = coordinates(R)\nscatter!(ax, xs, ys; color = :black, markersize = 1)\nax.limits = ((1, size(R, 1)), (1, size(R, 2)));\nax.aspect = 1\n\nax2 = Axis(fig[1,2]; aspect = 1)\nRg = grayscale(R)\nheatmap!(ax2, Rg; colormap = :grays)\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"and here is exactly the same process, but using a delay embedded trajectory instead","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using DelayEmbeddings\n\ny = X[:, 2]\nτ = estimate_delay(y, \"mi_min\")\nm = embed(y, 3, τ)\nE = RecurrenceMatrix(m, 5.0; metric = \"euclidean\")\n\nxs, ys = coordinates(E)\nfig, ax = scatter(xs, ys; markersize = 1)\nax.aspect = 1\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"which justifies why recurrence plots are so fitting to be used in embedded timeseries.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"warning: Careful when using Recurrence Plots\nIt is easy when using grayscale to not change the width/height parameters. The width and height are important when in grayscale when the matrix size exceeds the display size! Most plotting libraries may resample arbitrarily or simply limit the displayed pixels, so one needs to be extra careful.Besides graphical problems there are also other potential pitfalls dealing with the conceptual understanding and use of recurrence plots. All of these are summarized in the following paper which we suggest users to take a look at:N. Marwan, How to avoid potential pitfalls in recurrence plot based data analysis, Int. J. of Bifurcations and Chaos (arXiv).","category":"page"},{"location":"rplots/#Skeletonized-Recurrence-Plots","page":"Recurrence Plots","title":"Skeletonized Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The finite size of a recurrence plot can cause border effects in the recurrence quantification-measures rqa. Also the sampling rate of the data and the chosen recurrence threshold selection method (fixed, fixedrate, FAN) plays a crucial role. They can cause the thickening of diagonal lines in the recurrence matrix. Both problems lead to biased line-based RQA-quantifiers and is discussed in:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"K.H. Kraemer & N. Marwan, Border effect corrections for diagonal line based recurrence quantification analysis measures, Phys. Lett. A 2019.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"skeletonize","category":"page"},{"location":"rplots/#RecurrenceAnalysis.skeletonize","page":"Recurrence Plots","title":"RecurrenceAnalysis.skeletonize","text":"skeletonize(R) → R_skel\n\nSkeletonize the RecurrenceMatrix R by using the algorithm proposed by Kraemer & Marwan [Kraemer2019]. This function returns R_skel, a recurrence matrix, which only consists of diagonal lines of \"thickness\" one.\n\n[Kraemer2019]: Kraemer, K.H., Marwan, N. (2019). Border effect corrections for diagonal line based recurrence quantification analysis measures. Physics Letters A 383(34).\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Consider, e.g. a skeletonized version of a simple sinusoidal:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using RecurrenceAnalysis, DelayEmbeddings, CairoMakie\n\ndata = sin.(2*π .* (0:400)./ 60)\nY = embed(data, 3, 15)\n\nR = RecurrenceMatrix(Y, GlobalRecurrenceRate(0.25))\nR_skel = skeletonize(R)\n\nfig = Figure(resolution = (1000,600))\nax = Axis(fig[1,1]; title = \"RP of monochromatic signal\")\nheatmap!(ax, grayscale(R); colormap = :grays)\n\nax = Axis(fig[1,2]; title = \"skeletonized RP\")\nheatmap!(ax, grayscale(R_skel); colormap = :grays)\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"This way spurious diagonal lines get removed from the recurrence matrix, which would otherwise effect the quantification based on these lines.","category":"page"},{"location":"rplots/#Distance-matrix","page":"Recurrence Plots","title":"Distance matrix","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The distance function used in RecurrenceMatrix and co. can be specified either as any Metric instance from Distances. In addition, the following function returns a matrix with the cross-distances across all points in one or two trajectories:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"distancematrix","category":"page"},{"location":"rplots/#RecurrenceAnalysis.distancematrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.distancematrix","text":"distancematrix(x [, y = x], metric = \"euclidean\")\n\nCreate a matrix with the distances between each pair of points of the time series x and y using metric.\n\nThe time series x and y can be AbstractDatasets or vectors or matrices with data points in rows. The data point dimensions (or number of columns) must be the same for x and y. The returned value is a n×m matrix, with n being the length (or number of rows) of x, and m the length of y.\n\nThe metric can be any of the Metrics defined in the Distances package and defaults to Euclidean().\n\n\n\n\n\n","category":"function"},{"location":"rplots/#StateSpaceSet-reference","page":"Recurrence Plots","title":"StateSpaceSet reference","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"StateSpaceSet","category":"page"},{"location":"rplots/#StateSpaceSets.StateSpaceSet","page":"Recurrence Plots","title":"StateSpaceSets.StateSpaceSet","text":"StateSpaceSet{D, T} <: AbstractStateSpaceSet{D,T}\n\nA dedicated interface for sets in a state space. It is an ordered container of equally-sized points of length D. Each point is represented by SVector{D, T}. The data are a standard Julia Vector{SVector}, and can be obtained with vec(ssset::StateSpaceSet). Typically the order of points in the set is the time direction, but it doesn't have to be.\n\nWhen indexed with 1 index, StateSpaceSet is like a vector of points. When indexed with 2 indices it behaves like a matrix that has each of the columns be the timeseries of each of the variables. When iterated over, it iterates over its contained points. See description of indexing below for more.\n\nStateSpaceSet also supports almost all sensible vector operations like append!, push!, hcat, eachrow, among others.\n\nDescription of indexing\n\nIn the following let i, j be integers, typeof(X) <: AbstractStateSpaceSet and v1, v2 be <: AbstractVector{Int} (v1, v2 could also be ranges, and for performance benefits make v2 an SVector{Int}).\n\nX[i] == X[i, :] gives the ith point (returns an SVector)\nX[v1] == X[v1, :], returns a StateSpaceSet with the points in those indices.\nX[:, j] gives the jth variable timeseries (or collection), as Vector\nX[v1, v2], X[:, v2] returns a StateSpaceSet with the appropriate entries (first indices being \"time\"/point index, while second being variables)\nX[i, j] value of the jth variable, at the ith timepoint\n\nUse Matrix(ssset) or StateSpaceSet(matrix) to convert. It is assumed that each column of the matrix is one variable. If you have various timeseries vectors x, y, z, ... pass them like StateSpaceSet(x, y, z, ...). You can use columns(dataset) to obtain the reverse, i.e. all columns of the dataset in a tuple.\n\n\n\n\n\n","category":"type"}]
+[{"location":"networks/#Recurrence-Networks","page":"Recurrence Networks","title":"Recurrence Networks","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"Recurrence matrices can be reinterpreted as adjacency matrices of complex networks embedded in state space, such that each node or vertex of the network corresponds to a point of the timeseries, and the links of the network connect pairs of points that are mutually close the phase space. The relationship between a recurrence matrix R and its corresponding adjacency matrix A is:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"Rij = Aij - deltaij","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"i.e. there is an edge in the associated network between every two neighboring points in the phase space, excluding self-connections (points in the Line Of Identity or main diagonal of R).","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"This definition assumes that A represents an undirected graph, so R must be a symmetric matrix as corresponding to a RecurrenceMatrix or a JointRecurrenceMatrix.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"While RQA characterizes the properties of line structures in the recurrence plots, which consider dynamical aspects (e.g. continuity of recurrences, length of sequences, etc.), the analysis of recurrence networks does not take into account time information, since network properties are independent of the ordering of vertices. On the other hand, recurrence network analysis (RNA) provides information about geometric characteristics of the state space, like homogeneity of the connections, clustering of points, etc. More details about the theoretical framework of RNA can be found in the following papers:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010)\nR.V. Donner et al. \"Complex Network Analysis of Recurrences\", in: Webber, C.L. & Marwan N. (eds.) Recurrence Quantification Analysis. Theory and Best Practices, Springer, pp. 101-165 (2015).","category":"page"},{"location":"networks/#Creation-and-visualization-of-Recurrence-Networks","page":"Recurrence Networks","title":"Creation and visualization of Recurrence Networks","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"The JuliaGraphs organization provides multiple packages for Julia to create, visualize and analyze complex networks. In particular, the package LightGraphs defines the type SimpleGraph that can be used to represent undirected networks. Such graphs can be created from symmetric recurrence matrices, as in the following example with a Hénon map:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"using RecurrenceAnalysis, DynamicalSystemsBase\nusing Graphs: SimpleGraph\n\n# make trajectory of Henon map\nhenon_rule(x, p, n) = SVector(1.0 - p[1]*x[1]^2 + x[2], p[2]*x[1])\nu0 = zeros(2)\np0 = [1.4, 0.3]\nhenon = DeterministicIteratedMap(henon_rule, u0, p0)\nX, t = trajectory(henon, 200)\n# Cast it into a recurrence network\nR = RecurrenceMatrix(X, 0.25; metric = Chebyshev())\nnetwork = SimpleGraph(R)","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"There are various plotting tools that can be used to visualize such graphs. For instance, the following plot made with the package GraphMakie.jl.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"using GraphMakie, CairoMakie\ngraphplot(network)","category":"page"},{"location":"networks/#Recurrence-Network-measures","page":"Recurrence Networks","title":"Recurrence Network measures","text":"","category":"section"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"LightGraphs has a large set of functions to extract local measures (associated to particular vertices or edges) and global coefficients associated to the whole network. For SimpleGraphs created from recurrence matrices, as the variable network in the previous example, the vertices are labelled with numeric indices following the same ordering as the rows or columns of the given matrix. So for instance degree(network, i) would give the degree of the i-th point of the timeseries (number of connections with other points), whereas degree(network) would give a vector of such measures ordered as the original timeseries.","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"As in RQA, we provide a function that computes a selection of commonly used global RNA measures, directly from the recurrence matrix:","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"rna","category":"page"},{"location":"networks/#RecurrenceAnalysis.rna","page":"Recurrence Networks","title":"RecurrenceAnalysis.rna","text":"rna(R::AbstractRecurrenceMatrix)\nrna(args...; kwargs...)\n\nCalculate a set of Recurrence Network parameters. The input R can be a symmetric recurrence matrix that is interpreted as the adjacency matrix of an undirected complex network, such that linked vertices are neighboring points in the phase space.\n\nAlternatively, the inputs can be a graph object or any valid inputs to the SimpleGraph constructor of the Graphs package.\n\nReturn\n\nThe returned value is a dictionary that contains the following entries, with the corresponding global network properties[1, 2]:\n\n:density: edge density, approximately equivalent to the global recurrence rate in the phase space.\n:transitivity: network transitivity, which describes the\n\nglobal clustering of points following Barrat's and Weigt's formulation [3].\n\n:averagepath: mean value of the shortest path lengths taken over\n\nall pairs of connected vertices, related to the average separation between points in the phase.\n\n:diameter: maximum value of the shortest path lengths between\n\npairs of connected vertices, related to the phase space diameter.\n\nReferences\n\n[1]: R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025\n\n[2]: R.V. Donner et al., The geometry of chaotic dynamics — a complex network perspective, Eur. Phys. J. B 84, 653–672 (2011) DOI:10.1140/epjb/e2011-10899-1\n\n[3]: A. Barrat & M. Weight, \"On the properties of small-world network models\", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067\n\n\n\n\n\n","category":"function"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"note: Transitivity and global clustering coefficient\nThe concept of clustering coefficient at local level (for individual nodes of the network) is clearly defined as the fraction of connecting nodes that are also connected between them, forming \"triangles\". But at global level it is a source of confusion: the term of \"global clustering coefficient\" was originally used by Watts and Strogatz[1], referred to the average of local clustering coefficient across all the graph's nodes. But Barrat and Weigt proposed an alternative definition[2] that characterizes the effective global dimensionality of the system, giving equal weight to all triangles in the network[3].This second definition is often named with the distinctive term of \"transitivity\", as in the output of rna, whereas the corresponding function of the LightGraphs package is global_clustering_coefficient. The \"global clustering coefficient\" as by Watts and Strogatz could be obtained as mean(local_clustering_coefficient(network)) – with network being a graph object as in the previous example. (The function mean is in the Julia standard library, and can be brought into scope with the command using Statistics.)","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[1]: D.J. Watts & S.H. Strogatz, \"Collective dynamics of 'small-world' networks\", Nature 393(6684), 440–442 (1998) DOI:10.1038%2F30918","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[2]: A. Barrat & M. Weight, \"On the properties of small-world network models\", The European Physical Journal B 13, 547–560 (2000) DOI:10.1007/s100510050067","category":"page"},{"location":"networks/","page":"Recurrence Networks","title":"Recurrence Networks","text":"[3]: R.V. Donner et al. \"Recurrence networks — a novel paradigm for nonlinear time series analysis\", New Journal of Physics 12, 033025 (2010) DOI:10.1088/1367-2630/12/3/033025","category":"page"},{"location":"quantification/#Recurrence-Quantification-Analysis","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"A RecurrenceMatrix can be analyzed in several ways to yield information about the dynamics of the trajectory. All these various measures and functions are collectively called \"Recurrence Quantification Analysis\" (RQA).","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"To understand how each measure can be useful, we suggest to see the review articles listed in our documentation strings, namely:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"N. Marwan et al., \"Recurrence plots for the analysis of complex systems\", Phys. Reports 438(5-6), 237-329 (2007).\nN. 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).","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"You can also check the wikipedia page for Recurrence quantification analysis.","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"The functions described in this page all accept a recurrence matrix (x), see RecurrenceMatrix.","category":"page"},{"location":"quantification/#RQA-Measures","page":"Recurrence Quantification Analysis","title":"RQA Measures","text":"","category":"section"},{"location":"quantification/#All-in-one-Bundle","page":"Recurrence Quantification Analysis","title":"All-in-one Bundle","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"In case you need all of the RQA-related functions (see below) and you don't want to write 10 lines of code to compute them all (since they are so many) we provide an all-in-one function that computes all of them and returns a dictionary with the results!","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"rqa","category":"page"},{"location":"quantification/#RecurrenceAnalysis.rqa","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rqa","text":"rqa(R; kwargs...)\n\nCalculate 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.\n\nReturn\n\nThe returned value contains the following entries, which can be retrieved as from a dictionary (e.g. results[:RR], etc.):\n\n:RR: recurrence rate (see recurrencerate)\n:DET: determinsm (see determinism)\n:L: average length of diagonal structures (see dl_average)\n:Lmax: maximum length of diagonal structures (see dl_max)\n:DIV: divergence (see divergence)\n:ENTR: entropy of diagonal structures (see dl_entropy)\n:TREND: trend of recurrences (see trend)\n:LAM: laminarity (see laminarity)\n:TT: trapping time (see trappingtime)\n:Vmax: maximum length of vertical structures (see vl_max)\n:VENTR: entropy of vertical structures (see vl_entropy)\n:MRT: mean recurrence time (see meanrecurrencetime)\n:RTE recurrence time entropy (see rt_entropy)\n:NMPRT: number of the most probable recurrence time (see nmprt)\n\nAll 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.\n\nKeyword Arguments\n\nStandard keyword arguments are the ones accepted by the functions listed below, i.e. theiler, lmin, and border:\n\ntheiler 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).\nlmin 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).\nborder is used to avoid border effects in the calculation of :TREND (cf. trend).\n\nIn 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.\n\nThe 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.\n\nTransitional note on the returned type\n\nIn 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.\n\nIn 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:\n\nrqa(NamedTuple, R...) to obtain the output of the older version (as in 1.3).\nrqa(Dict, R...) to obtain the output of the planned future version.\nrqa(RQA, R...) to obtain the default current output (same as rqa(R...))\nrqa(DT,R...) to obtain the output as DT which is a subtype of AbstractDict (e.g. rqa(OrderedDict,R...) returns an OrderedDict)\n\n\n\n\n\n","category":"function"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"note: Return values for empty histograms\nIt may be the case that for a given recurrence matrix some structures do not exist at all. For example there are recurrence matrices that have no vertical lengths (or no vertical lengths with length less than lmin). In such cases the behavior of our RQA pipeline is the following:Quantities that represent maximum or average values are 0.0.\nQuantities that represent entropies are NaN.","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"See also the [windowed] function for a windowed version of rqa.","category":"page"},{"location":"quantification/#Example","page":"Recurrence Quantification Analysis","title":"Example","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"For example, here are the RQA measures for the same example trajectory we used to make Simple Recurrence Plots","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"using RecurrenceAnalysis, DynamicalSystemsBase\n\n# Create trajectory of Roessler system\n@inbounds function roessler_rule(u, p, t)\n a, b, c = p\n du1 = -u[2]-u[3]\n du2 = u[1] + a*u[2]\n du3 = b + u[3]*(u[1] - c)\n return SVector(du1, du2, du3)\nend\np0 = [0.15, 0.2, 10.0]\nu0 = ones(3)\nro = CoupledODEs(roessler_rule, u0, p0)\nN = 2000; Δt = 0.05\nX, t = trajectory(ro, N*Δt; Δt, Ttr = 10.0)\n\n# Make a recurrence matrix with fixed threshold\nR = RecurrenceMatrix(X, 5.0)\n\n# Compute RQA measures\nrqa(R)","category":"page"},{"location":"quantification/#Classical-RQA-Measures","page":"Recurrence Quantification Analysis","title":"Classical RQA Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"recurrencerate\ndeterminism\ndl_average\ndl_max\ndl_entropy\ndivergence\ntrend","category":"page"},{"location":"quantification/#RecurrenceAnalysis.recurrencerate","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.recurrencerate","text":"recurrencerate(R[; theiler])\n\nCalculate the recurrence rate of the recurrence matrix R.\n\nDescription\n\nThe recurrence rate is calculated as:\n\nRR = frac1S sum R\n\nwhere 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].\n\nFor 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).\n\nHint: 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.\n\nReferences\n\n[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\n\n[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\n\n[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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.determinism","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.determinism","text":"determinism(R[; lmin=2, theiler])\n\nCalculate the determinism of the recurrence matrix R:\n\nDescription\n\nThe determinism is calculated as:\n\nDET = fracsum_l=lminl P(l)sum_l=1l P(l) =\nfracsum_l=lminl P(l)sum R\n\nwhere l stands for the lengths of diagonal lines in the matrix, and P(l) is the number of lines of length equal to l.\n\nlmin 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_average","text":"dl_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_max","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_max","text":"dl_max(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.dl_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.dl_entropy","text":"dl_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.divergence","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.divergence","text":"divergence(R[; theiler])\n\nCalculate the divergence of the recurrence matrix R (actually the inverse of dl_max).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.trend","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.trend","text":"trend(R[; border=10, theiler])\n\nCalculate the trend of recurrences in the recurrence matrix R.\n\nDescription\n\nThe 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.\n\nIt is calculated as:\n\nTREND = 10^3fracsum_d=tau^tildeNdeltadleft(RRd-langle RRdrangleright)sum_d=tau^tildeNdeltad^2\n\nwhere RRd is the local recurrence rate of the diagonal d, deltad 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 tildeN is the number of the outmost diagonal that is included.\n\nThis parameter is expressed in units of variation recurrence rate every 1000 data points, hence the factor 10^3 in the formula [1].\n\nThe 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).\n\nNote: 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.\n\nReferences\n\n[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\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Extended-RQA-Measures","page":"Recurrence Quantification Analysis","title":"Extended RQA Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"laminarity\ntrappingtime\nvl_average\nvl_max\nvl_entropy","category":"page"},{"location":"quantification/#RecurrenceAnalysis.laminarity","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.laminarity","text":"laminarity(R[; lmin=2, theiler])\n\nCalculate the laminarity of the recurrence matrix R.\n\nDescription\n\nThe laminarity is calculated as:\n\nLAM = fracsum_v=lminv P(l)sum_v=1v P(v) =\nfracsum_v=lminv P(l)sum R\n\nwhere v stands for the lengths of vertical lines in the matrix, and P(v) is the number of lines of length equal to v.\n\nlmin 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.trappingtime","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.trappingtime","text":"trappingtime(R[; lmin=2, theiler])\n\nCalculate 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).\n\nThe trapping time is the average of the vertical line structures and thus equal to vl_average.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_average","text":"vl_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_max","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_max","text":"vl_max(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.vl_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.vl_entropy","text":"vl_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Recurrence-Time-Measures","page":"Recurrence Quantification Analysis","title":"Recurrence Time Measures","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"meanrecurrencetime\nnmprt\nrt_entropy\nrt_average","category":"page"},{"location":"quantification/#RecurrenceAnalysis.meanrecurrencetime","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.meanrecurrencetime","text":"meanrecurrencetime(R[; lmin=2, theiler])\n\nCalculate 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).\n\nEquivalent to rt_average.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.nmprt","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.nmprt","text":"nmprt(R[; lmin=2, theiler])\n\nCalculate 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).\n\nThis 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].\n\nReferences\n\n[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\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.rt_entropy","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rt_entropy","text":"rt_entropy(R[; lmin=2, theiler])\n\nCalculate 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).\n\nNotes: 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.\n\n\n\n\n\n","category":"function"},{"location":"quantification/#RecurrenceAnalysis.rt_average","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.rt_average","text":"rt_average(R[; lmin=2, theiler])\n\nCalculate 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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Keyword-table","page":"Recurrence Quantification Analysis","title":"Keyword table","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"Since most of the above functions can be fined tuned with keyword arguments, here is a table summarizing them that could be of use:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"Argument Default Functions Description\ntheiler 0 for CrossRecurrenceMatrix, 1 otherwise. recurrencerate, determinism, *_average, *_max, *_entropy, divergence, trend, laminarity, trappingtime, meanrecurrencetime, nmprt Theiler window: number of diagonals around the LOI excluded from the analysis. The value 0 means that the LOI is included in the analysis. Use 1 to exclude the LOI.\nlmin 2 determinism, *_average, *_max, *_entropy, divergence, laminarity, trappingtime, meanrecurrencetime, nmprt Minimum length of the recurrent structures (diagonal or vertical) considered in the analysis.\nborder 10 trend Number of diagonals excluded from the analysis near the border of the matrix.","category":"page"},{"location":"quantification/#Recurrence-Structures-Histograms","page":"Recurrence Quantification Analysis","title":"Recurrence Structures Histograms","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"The functions that we list in this page internally compute histograms of some recurrence structures, like e.g. the vertical lengths. You can access these values directly with the following function:","category":"page"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"recurrencestructures","category":"page"},{"location":"quantification/#RecurrenceAnalysis.recurrencestructures","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.recurrencestructures","text":"recurrencestructures(x::AbstractRecurrenceMatrix;\n diagonal=true,\n vertical=true,\n recurrencetimes=true,\n kwargs...)\n\nReturn 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.\n\nDescription\n\nEach 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.\n\n\"diagonal\" counts the diagonal lines, i.e. the recurrent trajectories.\n\"vertical\" counts the vertical lines, i.e. the laminar states.\n\"recurrencetimes\" counts the vertical distances between recurrent states, i.e. the recurrence times.\n\nAll 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.\n\n\"Empty\" histograms are represented always as [0].\n\nNotice: 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].\n\nReferences\n\n[1] J. Gao & H. Cai. \"On the structures and quantification of recurrence plots\". Physics Letters A, 270(1-2), 75–87 (2000).\n\n[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).\n\n\n\n\n\n","category":"function"},{"location":"quantification/#Windowed-application","page":"Recurrence Quantification Analysis","title":"Windowed application","text":"","category":"section"},{"location":"quantification/","page":"Recurrence Quantification Analysis","title":"Recurrence Quantification Analysis","text":"windowed","category":"page"},{"location":"quantification/#RecurrenceAnalysis.windowed","page":"Recurrence Quantification Analysis","title":"RecurrenceAnalysis.windowed","text":"windowed(rmat, f, width, step = 1; kwargs...)\n\nA 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...).\n\n\n\n\n\n","category":"function"},{"location":"#RecurrenceAnalysis.jl","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"","category":"section"},{"location":"","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"RecurrenceAnalysis","category":"page"},{"location":"#RecurrenceAnalysis","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis","text":"RecurrenceAnalysis.jl\n\n(Image: docsdev) (Image: docsstable) (Image: CI) (Image: codecov) (Image: Package Downloads)\n\nA Julia package that offers tools for computing Recurrence Plots and exploring them within the framework of Recurrence Quantification Analysis and Recurrence Network Analysis. It can be used as a standalone package, or as part of DynamicalSystems.jl.\n\nTo install it, run import Pkg; Pkg.add(\"RecurrenceAnalysis\").\n\nAll further information is provided in the documentation, which you can either find online or build locally by running the docs/make.jl file.\n\n\n\n\n\n","category":"module"},{"location":"","page":"RecurrenceAnalysis.jl","title":"RecurrenceAnalysis.jl","text":"note: References\nWant to learn more about recurrence quantification analysis? Here are some resources:Chapter 9 of Nonlinear Dynamics, Datseris & Parlitz, Springer 2022.\nWebber, C. L., & Marwan, N. (2015). Recurrence Quantification Analysis. (C. L. Webber, & N. Marwan, Eds.). Cham: Springer International Publishing. https://doi.org/10.1007/978-3-319-07155-8\nMarwan, N., Carmen Romano, M., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. Physics Reports, 438(5–6), 237–329. https://doi.org/10.1016/j.physrep.2006.11.001","category":"page"},{"location":"rplots/#Recurrence-Plots","page":"Recurrence Plots","title":"Recurrence Plots","text":"","category":"section"},{"location":"rplots/#Recurrence-Matrices","page":"Recurrence Plots","title":"Recurrence Matrices","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"A Recurrence plot (which refers to the plot of a recurrence matrix) is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the phase space that it was at some previous time.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The central structure used in these recurrences is the (cross-) recurrence matrix:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Ri j = begincases\n1 quad textifquad d(xi yj) le varepsilon\n0 quad textelse\nendcases","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"where d(xi yj) stands for the distance between trajectory x at point i and trajectory y at point j. Both x y can be single timeseries, full trajectories or embedded timeseries (which are also trajectories).","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"If xequiv y then R is called recurrence matrix, otherwise it is called cross-recurrence matrix. There is also the joint-recurrence variant, see below. With RecurrenceAnalysis you can use the following functions to access these matrices","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"RecurrenceMatrix\nCrossRecurrenceMatrix\nJointRecurrenceMatrix","category":"page"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceMatrix","text":"RecurrenceMatrix(x, rthres; metric = Euclidean(), parallel::Bool)\n\nCreate a recurrence matrix from timeseries or trajectory x and with recurrence threshold rthres. x is either a StateSpaceSet for multivariate data or an AbstractVector{<:Real} for timeseries.\n\nThe variable rthres defines how recurrences are estimated. It can be any subtype of AbstractRecurrenceType, and different types can specify recurrences differently. Alternatively, rthres can be a real number, which then becomes an instance of RecurrenceThreshold.\n\nThe keyword metric, if given, must be any subtype of Metric from Distances.jl and defines the metric used to calculate distances for recurrences. By default the Euclidean metric is used, typical alternatives are Chebyshev(), Cityblock().\n\nThe keyword parallel decides if the comptutation should be done in parallel using threads. Defaults to length(x) > 500 && Threads.nthreads() > 1.\n\nDescription\n\nA (cross-)recurrence matrix is a way to quantify recurrences that occur in a trajectory. A recurrence happens when a trajectory visits the same neighborhood on the state space that it was at some previous time.\n\nThe recurrence matrix is a numeric representation of a recurrence plot, described in detail in [Marwan2007] and [Marwan2015]. It represents a a sparse square matrix of Boolean values that quantifies recurrences in the trajectory, i.e., points where the trajectory returns close to itself. Given trajectories x, y, and asumming ε isa Real, the matrix is defined as:\n\nR[i,j] = metric(x[i], y[i]) ≤ ε ? true : false\n\nwith the metric being the distance function. The difference between a RecurrenceMatrix and a CrossRecurrenceMatrix is that in the first case x === y.\n\nObjects of type <:AbstractRecurrenceMatrix are displayed as a recurrenceplot.\n\nSee also: CrossRecurrenceMatrix, JointRecurrenceMatrix and use recurrenceplot to turn the result of these functions into a plottable format.\n\n[Marwan2007]: N. Marwan et al., \"Recurrence plots for the analysis of complex systems\", Phys. Reports 438*(5-6), 237-329 (2007)\n\n[Marwan2015]: N. Marwan & C.L. Webber, Recurrence Quantification Analysis. Theory and Best Practices Springer (2015)\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.CrossRecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.CrossRecurrenceMatrix","text":"CrossRecurrenceMatrix(x, y, rthres; kwargs...)\n\nCreate a cross recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible value for rthres and kwargs.\n\nThe cross recurrence matrix is a bivariate extension of the recurrence matrix. For the time series x, y, of length n and m, respectively, it is a sparse n×m matrix of Boolean values.\n\nNote that cross recurrence matrices are generally not symmetric irrespectively of rthres.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.JointRecurrenceMatrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.JointRecurrenceMatrix","text":"JointRecurrenceMatrix(x, y, rthres; kwargs...)\n\nCreate a joint recurrence matrix from trajectories x and y. See RecurrenceMatrix for possible values for rthres and kwargs.\n\nThe joint recurrence matrix considers the recurrences of the trajectories of x and y separately, and looks for points where both recur simultaneously. It is calculated by the element-wise multiplication of the recurrence matrices of x and y. If x and y are of different length, the recurrences are only calculated until the length of the shortest one.\n\nSee RecurrenceMatrix for details, references and keywords.\n\n\n\n\n\nJointRecurrenceMatrix(R1::AbstractRecurrenceMatrix, R2::AbstractRecurrenceMatrix)\n\nEquivalent with R1 .* R2.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#Advanced-recurrences-specification","page":"Recurrence Plots","title":"Advanced recurrences specification","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"AbstractRecurrenceType\nRecurrenceThreshold\nRecurrenceThresholdScaled\nGlobalRecurrenceRate\nLocalRecurrenceRate\nrecurrence_threshold","category":"page"},{"location":"rplots/#RecurrenceAnalysis.AbstractRecurrenceType","page":"Recurrence Plots","title":"RecurrenceAnalysis.AbstractRecurrenceType","text":"AbstractRecurrenceType\n\nSupertype of all recurrence specification types. Instances of subtypes are given to RecurrenceMatrix and similar constructors to specify recurrences. Use recurrence_threshold to extract the numeric distance threshold.\n\nPossible subtypes are:\n\nRecurrenceThreshold(ε::Real): Recurrences are defined as any point with distance ≤ ε from the referrence point.\nRecurrenceThresholdScaled(ratio::Real, scale::Function): Here scale is a function of the distance matrix dm (see distancematrix) that is used to scale the value of the recurrence threshold ε so that ε = ratio*scale(dm). After the new ε is obtained, the method works just like the RecurrenceThreshold. Specialized versions are employed if scale is mean or maximum.\nGlobalRecurrenceRate(q::Real): Here the number of total recurrence rate over the whole matrix is specified to be a quantile q ∈ (0,1) of the distancematrix. In practice this yields (approximately) a ratio q of recurrences out of the total Nx * Ny for input trajectories x, y.\nLocalRecurrenceRate(r::Real): The recurrence threhsold here is point-dependent. It is defined so that each point of x has a fixed number of k = r*N neighbors, with ratio r out of the total possible N. Equivalently, this means that each column of the recurrence matrix will have exactly k true entries. Notice that LocalRecurrenceRate does not guarantee that the resulting recurrence matrix will be symmetric.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceThreshold","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceThreshold","text":"RecurrenceThreshold(ε::Real)\n\nRecurrences are defined as any point with distance ≤ ε from the referrence point. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.RecurrenceThresholdScaled","page":"Recurrence Plots","title":"RecurrenceAnalysis.RecurrenceThresholdScaled","text":"RecurrenceThresholdScaled(ratio::Real, scale::Function)\n\nRecurrences are defined as any point with distance ≤ d from the referrence point, where d is a scaled ratio (specified by ratio, scale) of the distance matrix. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.GlobalRecurrenceRate","page":"Recurrence Plots","title":"RecurrenceAnalysis.GlobalRecurrenceRate","text":"GlobalRecurrenceRate(rate::Real)\n\nRecurrences are defined as a constant global recurrence rate. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.LocalRecurrenceRate","page":"Recurrence Plots","title":"RecurrenceAnalysis.LocalRecurrenceRate","text":"LocalRecurrenceRate(rate::Real)\n\nRecurrences are defined as a constant local recurrence rate. See AbstractRecurrenceType for more.\n\n\n\n\n\n","category":"type"},{"location":"rplots/#RecurrenceAnalysis.recurrence_threshold","page":"Recurrence Plots","title":"RecurrenceAnalysis.recurrence_threshold","text":"recurrence_threshold(rt::AbstractRecurrenceType, x [, y] [, metric]) → ε\n\nReturn the calculated distance threshold ε for rt. The output is real, unless rt isa LocalRecurrenceRate, where ε isa Vector.\n\n\n\n\n\n","category":"function"},{"location":"rplots/#Simple-Recurrence-Plots","page":"Recurrence Plots","title":"Simple Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The recurrence matrices are internally stored as sparse matrices with Boolean values. Typically in the literature one does not sees the plots of the matrices (hence \"Recurrence Plots\"). By default, when a Recurrence Matrix is created we \"show\" a mini plot of it which is a text-based scatterplot.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Here is an example recurrence plot/matrix of a full trajectory of the Roessler system:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using RecurrenceAnalysis, DynamicalSystemsBase\n\n# Create trajectory of Roessler system\n@inbounds function roessler_rule(u, p, t)\n a, b, c = p\n du1 = -u[2]-u[3]\n du2 = u[1] + a*u[2]\n du3 = b + u[3]*(u[1] - c)\n return SVector(du1, du2, du3)\nend\np0 = [0.15, 0.2, 10.0]\nu0 = ones(3)\nro = CoupledODEs(roessler_rule, u0, p0)\nN = 2000; Δt = 0.05\nX, t = trajectory(ro, N*Δt; Δt, Ttr = 10.0)\n\n# Make a recurrence matrix with fixed threshold\nR = RecurrenceMatrix(X, 5.0)\nrecurrenceplot(R; ascii = true)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Or make a recurrence matrix with fixed (global) recurrence rate of 10%","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"R = RecurrenceMatrix(X, GlobalRecurrenceRate(0.1))\nrecurrenceplot(R; ascii = true)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"typeof(R)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"summary(R)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The above simple plotting functionality is possible through the package UnicodePlots. The following function creates the plot:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"recurrenceplot","category":"page"},{"location":"rplots/#RecurrenceAnalysis.recurrenceplot","page":"Recurrence Plots","title":"RecurrenceAnalysis.recurrenceplot","text":"recurrenceplot([io,] R; minh = 25, maxh = 0.5, ascii, kwargs...) -> u\n\nCreate a text-based scatterplot representation of a recurrence matrix R to be displayed in io (by default stdout) using UnicodePlots. The matrix spans at minimum minh rows and at maximum maxh*displaysize(io)[1] (i.e. by default half the display). As we always try to plot in equal aspect ratio, if the width of the plot is even less, the minimum height is dictated by the width.\n\nThe keyword ascii::Bool can ensure that all elements of the plot are ASCII characters (true) or Unicode (false).\n\nThe rest of the kwargs are propagated into UnicodePlots.scatterplot.\n\nNotice that the accuracy of this function drops drastically for matrices whose size is significantly bigger than the width and height of the display (assuming each index of the matrix is one character).\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Here is the same plot but using Unicode Braille characters","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"recurrenceplot(R; ascii = false)","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"As you can see, the Unicode based plotting doesn't display nicely everywhere. It does display perfectly in e.g. VSCode, which is where it is the default printing type.","category":"page"},{"location":"rplots/#Advanced-Recurrence-Plots","page":"Recurrence Plots","title":"Advanced Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"A text-based plot is cool, fast and simple. But often one needs the full resolution offered by the data of a recurrence matrix.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"There are two more ways to plot a recurrence matrix using RecurrenceAnalysis:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"coordinates\ngrayscale","category":"page"},{"location":"rplots/#RecurrenceAnalysis.coordinates","page":"Recurrence Plots","title":"RecurrenceAnalysis.coordinates","text":"coordinates(R) -> xs, ys\n\nReturn the coordinates of the recurrence points of R (in indices).\n\n\n\n\n\n","category":"function"},{"location":"rplots/#RecurrenceAnalysis.grayscale","page":"Recurrence Plots","title":"RecurrenceAnalysis.grayscale","text":"grayscale(R [, bwcode]; width::Int, height::Int, exactsize=false)\n\nTransform the recurrence matrix R into a full matrix suitable for plotting as a grayscale image. By default it returns a matrix with the same size as R, but switched axes, containing \"black\" values in the cells that represent recurrent points, and \"white\" values in the empty cells and interpolating in-between for cases with both recurrent and empty cells, see below.\n\nThe numeric codes for black and white are given in a 2-element tuple as a second optional argument. Its default value is (0.0, 1.0), i.e. black is coded as 0.0 (no brightness) and white as 1.0 (full brightness). The type of the elements in the tuple defines the type of the returned matrix. This must be taken into account if, for instance, the image is coded as a matrix of integers corresponding to a grayscale; in such case the black and white codes must be given as numbers of the required integer type.\n\nThe keyword arguments width and height can be given to define a custom size of the image. If only one dimension is given, the other is automatically calculated. If both dimensions are given, by default they are adjusted to keep an aspect proportional to the original matrix, such that the returned matrix fits into a matrix of the given dimensions. This automatic adjustment can be disabled by passing the keyword argument exactsize=true.\n\nIf the image has different dimensions than R, the cells of R are distributed in a grid with the size of the image, and a gray level between white and black is calculated for each element of the grid, proportional to the number of recurrent points contained in it. The levels of gray are coded as numbers of the same type as the black and white codes.\n\nIt is advised to use width, height arguments for large matrices otherwise plots using functions like e.g. heatmap could be misleading.\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"For example, here is the representation of the above R from the Roessler system using both plotting approaches:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using CairoMakie\nfig = Figure(resolution = (1000,500))\n\nax = Axis(fig[1,1])\nxs, ys = coordinates(R)\nscatter!(ax, xs, ys; color = :black, markersize = 1)\nax.limits = ((1, size(R, 1)), (1, size(R, 2)));\nax.aspect = 1\n\nax2 = Axis(fig[1,2]; aspect = 1)\nRg = grayscale(R)\nheatmap!(ax2, Rg; colormap = :grays)\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"and here is exactly the same process, but using a delay embedded trajectory instead","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using DelayEmbeddings\n\ny = X[:, 2]\nτ = estimate_delay(y, \"mi_min\")\nm = embed(y, 3, τ)\nE = RecurrenceMatrix(m, 5.0; metric = \"euclidean\")\n\nxs, ys = coordinates(E)\nfig, ax = scatter(xs, ys; markersize = 1)\nax.aspect = 1\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"which justifies why recurrence plots are so fitting to be used in embedded timeseries.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"warning: Careful when using Recurrence Plots\nIt is easy when using grayscale to not change the width/height parameters. The width and height are important when in grayscale when the matrix size exceeds the display size! Most plotting libraries may resample arbitrarily or simply limit the displayed pixels, so one needs to be extra careful.Besides graphical problems there are also other potential pitfalls dealing with the conceptual understanding and use of recurrence plots. All of these are summarized in the following paper which we suggest users to take a look at:N. Marwan, How to avoid potential pitfalls in recurrence plot based data analysis, Int. J. of Bifurcations and Chaos (arXiv).","category":"page"},{"location":"rplots/#Skeletonized-Recurrence-Plots","page":"Recurrence Plots","title":"Skeletonized Recurrence Plots","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The finite size of a recurrence plot can cause border effects in the recurrence quantification-measures rqa. Also the sampling rate of the data and the chosen recurrence threshold selection method (fixed, fixedrate, FAN) plays a crucial role. They can cause the thickening of diagonal lines in the recurrence matrix. Both problems lead to biased line-based RQA-quantifiers and is discussed in:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"K.H. Kraemer & N. Marwan, Border effect corrections for diagonal line based recurrence quantification analysis measures, Phys. Lett. A 2019.","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"skeletonize","category":"page"},{"location":"rplots/#RecurrenceAnalysis.skeletonize","page":"Recurrence Plots","title":"RecurrenceAnalysis.skeletonize","text":"skeletonize(R) → R_skel\n\nSkeletonize the RecurrenceMatrix R by using the algorithm proposed by Kraemer & Marwan [Kraemer2019]. This function returns R_skel, a recurrence matrix, which only consists of diagonal lines of \"thickness\" one.\n\n[Kraemer2019]: Kraemer, K.H., Marwan, N. (2019). Border effect corrections for diagonal line based recurrence quantification analysis measures. Physics Letters A 383(34).\n\n\n\n\n\n","category":"function"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"Consider, e.g. a skeletonized version of a simple sinusoidal:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"using RecurrenceAnalysis, DelayEmbeddings, CairoMakie\n\ndata = sin.(2*π .* (0:400)./ 60)\nY = embed(data, 3, 15)\n\nR = RecurrenceMatrix(Y, GlobalRecurrenceRate(0.25))\nR_skel = skeletonize(R)\n\nfig = Figure(resolution = (1000,600))\nax = Axis(fig[1,1]; title = \"RP of monochromatic signal\")\nheatmap!(ax, grayscale(R); colormap = :grays)\n\nax = Axis(fig[1,2]; title = \"skeletonized RP\")\nheatmap!(ax, grayscale(R_skel); colormap = :grays)\nfig","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"This way spurious diagonal lines get removed from the recurrence matrix, which would otherwise effect the quantification based on these lines.","category":"page"},{"location":"rplots/#Distance-matrix","page":"Recurrence Plots","title":"Distance matrix","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"The distance function used in RecurrenceMatrix and co. can be specified either as any Metric instance from Distances. In addition, the following function returns a matrix with the cross-distances across all points in one or two trajectories:","category":"page"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"distancematrix","category":"page"},{"location":"rplots/#RecurrenceAnalysis.distancematrix","page":"Recurrence Plots","title":"RecurrenceAnalysis.distancematrix","text":"distancematrix(x [, y = x], metric = \"euclidean\")\n\nCreate a matrix with the distances between each pair of points of the time series x and y using metric.\n\nThe time series x and y can be AbstractStateSpaceSets or vectors or matrices with data points in rows. The data point dimensions (or number of columns) must be the same for x and y. The returned value is a n×m matrix, with n being the length (or number of rows) of x, and m the length of y.\n\nThe metric can be any of the Metrics defined in the Distances package and defaults to Euclidean().\n\n\n\n\n\n","category":"function"},{"location":"rplots/#StateSpaceSet-reference","page":"Recurrence Plots","title":"StateSpaceSet reference","text":"","category":"section"},{"location":"rplots/","page":"Recurrence Plots","title":"Recurrence Plots","text":"StateSpaceSet","category":"page"},{"location":"rplots/#StateSpaceSets.StateSpaceSet","page":"Recurrence Plots","title":"StateSpaceSets.StateSpaceSet","text":"StateSpaceSet{D, T, V} <: AbstractVector{V}\n\nA dedicated interface for sets in a state space. It is an ordered container of equally-sized points of length D, with element type T, represented by a vector of type V. Typically V is SVector{D,T} or Vector{T} and the data are always stored internally as Vector{V}.\n\nThe underlying Vector{V} can be obtained by vec(ssset), although this is almost never necessary because StateSpaceSet subtypes AbstractVector and extends its interface. StateSpaceSet also supports almost all sensible vector operations like append!, push!, hcat, eachrow, among others. When iterated over, it iterates over its contained points.\n\nConstruction\n\nConstructing a StateSpaceSet is done in three ways:\n\nBy giving in each individual columns of the state space set as Vector{<:Real}: StateSpaceSet(x, y, z, ...).\nBy giving in a matrix whose rows are the state space points: StateSpaceSet(m).\nBy giving in directly a vector of vectors (state space points): StateSpaceSet(v_of_v).\n\nAll constructors allow for the keyword container which sets the type of V (the type of inner vectors). At the moment options are only SVector, MVector, or Vector, and by default SVector is used.\n\nDescription of indexing\n\nWhen indexed with 1 index, StateSpaceSet behaves exactly like its encapsulated vector. i.e., a vector of vectors (state space points). When indexed with 2 indices it behaves like a matrix where each row is a point.\n\nIn the following let i, j be integers, typeof(X) <: AbstractStateSpaceSet and v1, v2 be <: AbstractVector{Int} (v1, v2 could also be ranges, and for performance benefits make v2 an SVector{Int}).\n\nX[i] == X[i, :] gives the ith point (returns an SVector)\nX[v1] == X[v1, :], returns a StateSpaceSet with the points in those indices.\nX[:, j] gives the jth variable timeseries (or collection), as Vector\nX[v1, v2], X[:, v2] returns a StateSpaceSet with the appropriate entries (first indices being \"time\"/point index, while second being variables)\nX[i, j] value of the jth variable, at the ith timepoint\n\nUse Matrix(ssset) or StateSpaceSet(matrix) to convert. It is assumed that each column of the matrix is one variable. If you have various timeseries vectors x, y, z, ... pass them like StateSpaceSet(x, y, z, ...). You can use columns(dataset) to obtain the reverse, i.e. all columns of the dataset in a tuple.\n\n\n\n\n\n","category":"type"}]
}
