Change return value of rqa to named Tuple (#61)

* Change return value of rqa to named Tuple

This should be faster than using a Dict.

* Change docstring of rqa

rqa now returns a NamedTuple with symbols and not a dictionary with
string keys.

* Change return type of windowed rqa to NamedTuple

To be consistent with the change of the return type of rqa this needed
to change.
Also changes the retrieval of the local rqa values, because the are not
in a dict anymore.
Changes local rqa_dict variable to rqa_tuple to reflect the type.

* Use :key to get values from the rqa return

This is needed because now rqa returns a NamedTuple instead of a dict.

Author: felixcremer

src/rqa.jl

@@ -346,27 +346,27 @@ Using this function is much more efficient than calling all individual functions
 one by one.
 
 ## Return
-The returned value is a dictionary with the following keys:
-
-* "RR": recurrence rate (see [`recurrencerate`](@ref))
-* "DET": determinsm (see [`determinism`](@ref))
-* "L": average length of diagonal structures (see [`dl_average`](@ref))
-* "Lmax": maximum length of diagonal structures (see [`dl_max`](@ref))
-* "DIV": divergence (see [`divergence`](@ref))
-* "ENTR": entropy of diagonal structures (see [`dl_entropy`](@ref))
-* "TREND": trend of recurrences (see [`trend`](@ref))
-* "LAM": laminarity (see [`laminarity`](@ref))
-* "TT": trapping time (see [`trappingtime`](@ref))
-* "Vmax": maximum length of vertical structures (see [`vl_max`](@ref))
-* "VENTR": entropy of vertical structures (see [`vl_entropy`](@ref))
-* "MRT": mean recurrence time (see [`meanrecurrencetime`](@ref))
-* "RTE" recurrence time entropy (see [`rt_entropy`](@ref))
-* "NMPRT": number of the most probable recurrence time (see [`nmprt`](@ref))
+The returned value is a NamedTuple with the following entries:
+
+* ´RR´: recurrence rate (see [`recurrencerate`](@ref))
+* ´DET´: determinsm (see [`determinism`](@ref))
+* ´L´: average length of diagonal structures (see [`dl_average`](@ref))
+* ´Lmax´: maximum length of diagonal structures (see [`dl_max`](@ref))
+* ´DIV´: divergence (see [`divergence`](@ref))
+* ´ENTR´: entropy of diagonal structures (see [`dl_entropy`](@ref))
+* ´TREND´: trend of recurrences (see [`trend`](@ref))
+* ´LAM´: laminarity (see [`laminarity`](@ref))
+* ´TT´: trapping time (see [`trappingtime`](@ref))
+* ´Vmax´: maximum length of vertical structures (see [`vl_max`](@ref))
+* ´VENTR´: entropy of vertical structures (see [`vl_entropy`](@ref))
+* ´MRT´: mean recurrence time (see [`meanrecurrencetime`](@ref))
+* ´RTE´ recurrence time entropy (see [`rt_entropy`](@ref))
+* ´NMPRT´: number of the most probable recurrence time (see [`nmprt`](@ref))
 
 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")
+(´L´, ´Lmax´, ´TT´, ´Vmax´, ´MRT´)
+are returned as `0.0` but their respective entropies (´ENTR´, ´VENTR´, ´RTE´)
 are returned as `NaN`.
 
 ## Keyword Arguments
@@ -388,7 +388,7 @@ i.e. `theiler`, `lmin`, and `border`:
   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"
+* `border` is used to avoid border effects in the calculation of ´TREND´
   (cf. [`trend`](@ref)).
 
 In addition `theilerdiag`, `lmindiag` may be used to
@@ -399,7 +399,7 @@ 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
+to diagonal structures (´RR´, ´DET´, ´L´, ´Lmax´, ´DIV´ and ´ENTR´), which makes
 this function slightly faster.
 """
 function rqa(x; onlydiagonal=false, kwargs...)
@@ -410,33 +410,33 @@ function rqa(x; onlydiagonal=false, kwargs...)
     dhist = diagonalhistogram(x; kw_d...)
     rr_d = recurrencerate(x; kw_d...)
     if onlydiagonal
-        return Dict("RR"  => recurrencerate(x; kwargs...),
-        "DET"  => _determinism(dhist, rr_d*_rrdenominator(x; kw_d...)),
-        "L"    => _dl_average(dhist),
-        "Lmax" => _dl_max(dhist),
-        "DIV"  => 1.0/_dl_max(dhist),
-        "ENTR"  => _dl_entropy(dhist)
+        return (RR  = recurrencerate(x; kwargs...),
+        DET   = _determinism(dhist, rr_d*_rrdenominator(x; kw_d...)),
+        L     = _dl_average(dhist),
+        Lmax  = _dl_max(dhist),
+        DIV   = 1.0/_dl_max(dhist),
+        ENTR  = _dl_entropy(dhist)
         )
    else
         kw_v = Dict(kwargs)
         haskey(kw_v, :theilervert) && (kw_v[:theiler] = kw_v[:theilervert])
         haskey(kw_v, :lminvert) && (kw_v[:lmin] = kw_v[:lminvert])
         vhist, rthist = verticalhistograms(x; kw_v...)
         rr_v = recurrencerate(x; kw_v...)
-        return Dict("RR"  => recurrencerate(x; kwargs...),
-            "DET"  => _determinism(dhist, rr_d*_rrdenominator(x; kw_v...)),
-            "L"    => _dl_average(dhist),
-            "Lmax" => _dl_max(dhist),
-            "DIV"  => 1.0/_dl_max(dhist),
-            "ENTR"  => _dl_entropy(dhist),
-            "TREND" => trend(x; kw_d...),
-            "LAM"  => _laminarity(vhist, rr_v*_rrdenominator(x; kw_v...)),
-            "TT"   => _vl_average(vhist),
-            "Vmax" => _vl_max(vhist),
-            "VENTR" => _vl_entropy(vhist),
-            "MRT"  => _rt_average(rthist),
-            "RTE" => _rt_entropy(rthist),
-            "NMPRT" => maximum(rthist)
+        return (RR  = recurrencerate(x; kwargs...),
+            DET  = _determinism(dhist, rr_d*_rrdenominator(x; kw_v...)),
+            L    = _dl_average(dhist),
+            Lmax = _dl_max(dhist),
+            DIV  = 1.0/_dl_max(dhist),
+            ENTR  = _dl_entropy(dhist),
+            TREND = trend(x; kw_d...),
+            LAM  = _laminarity(vhist, rr_v*_rrdenominator(x; kw_v...)),
+            TT   = _vl_average(vhist),
+            Vmax = _vl_max(vhist),
+            VENTR = _vl_entropy(vhist),
+            MRT  = _rt_average(rthist),
+            RTE = _rt_entropy(rthist),
+            NMPRT = maximum(rthist)
         )
     end
 end

src/windowed.jl

@@ -152,29 +152,30 @@ macro windowed(ex, options...)
                 local nw = size($x,1) - $(dict_op[:width])
                 local ni = div(nw, s)+1 # number of items
                 local mtype = typeof($x)
-                local rqa_dict = Dict(
-                    "RR"   => zeros(Float64,ni),
-                    "DET"  => zeros(Float64,ni),
-                    "L"    => zeros(Float64,ni),
-                    "Lmax" => zeros(Int,ni),
-                    "DIV"  => zeros(Float64,ni),
-                    "ENTR"  => zeros(Float64,ni),
-                    "TREND"  => zeros(Float64,ni),
-                    "LAM"  => zeros(Float64,ni),
-                    "TT"   => zeros(Float64,ni),
-                    "Vmax" => zeros(Int,ni),
-                    "VENTR" => zeros(Float64,ni),
-                    "MRT"  => zeros(Float64,ni),
-                    "RTE"  => zeros(Float64,ni),
-                    "NMPRT" => zeros(Int,ni)
+                local rqa_tuple = (
+                    RR   = zeros(Float64,ni),
+                    DET  = zeros(Float64,ni),
+                    L    = zeros(Float64,ni),
+                    Lmax = zeros(Int,ni),
+                    DIV  = zeros(Float64,ni),
+                    ENTR  = zeros(Float64,ni),
+                    TREND  = zeros(Float64,ni),
+                    LAM  = zeros(Float64,ni),
+                    TT   = zeros(Float64,ni),
+                    Vmax = zeros(Int,ni),
+                    VENTR = zeros(Float64,ni),
+                    MRT  = zeros(Float64,ni),
+                    RTE  = zeros(Float64,ni),
+                    NMPRT = zeros(Int,ni)
                 )
                 for i=1:ni
                     local rqa_i = $ex
-                    for (k,v) in rqa_i
-                        rqa_dict[k][i] = v
+                    #@show rqa_i
+                    for k in keys(rqa_i)
+                        rqa_tuple[k][i] = rqa_i[k]
                     end
                 end
-                rqa_dict
+                rqa_tuple
             end
             return esc(ret_ex)
         end

test/dynamicalsystems.jl

@@ -11,19 +11,19 @@ rng = Random.seed!(194)
 #     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
-#     
+#
 trajectories = Dict(
     "Sine wave" => RA.Dataset(map(x->[sin.(x) cos.(x)], StepRangeLen(0.0,0.2,200))),
     "White noise" => RA.Dataset(randn!(zeros(200,2))),
     "Hénon (chaotic)" => trajectory(Systems.henon(a=1.4, b=0.3), 199, Ttr=1000),
     "Hénon (periodic)" => trajectory(Systems.henon(a=1.054, b=0.3), 199, Ttr=1000)
     )
-embed_params = Dict(       #(m, τ) 
+embed_params = Dict(       #(m, τ)
     "Sine wave"   => (9, 7),
     "White noise" => (1, 1),
     "Hénon (chaotic)" => (3, 1),
     "Hénon (periodic)" => (3, 1))
-rqa_threshold = Dict( 
+rqa_threshold = Dict(
     "Sine wave"   => 0.15,
     "White noise" => 0.15,
     "Hénon (chaotic)" => 0.15,
@@ -36,7 +36,7 @@ dict_keys = ["Sine wave","White noise","Hénon (chaotic)","Hénon (periodic)"]
     y = data[1:100,2]
     xe = embed(x, embed_params[k]...)
     ye = embed(y, embed_params[k]...)
-    
+
     # Distance and recurrence matrices
     ε = rqa_threshold[k]
     dmat = distancematrix(xe, ye)
@@ -59,28 +59,27 @@ dict_keys = ["Sine wave","White noise","Hénon (chaotic)","Hénon (periodic)"]
     # Fixed rate for recurrence matrix
     crmat_fixed = CrossRecurrenceMatrix(xe, ye, 0.05; fixedrate=true)
     @test .04 < recurrencerate(crmat_fixed) < .06
-    
+
     # Recurrence plot
     crp = recurrenceplot(crmat, width=125)
     szplot = size(crp)
     szmat  = size(crmat)
     @test szplot[1] ≈ szplot[2]*szmat[2]/szmat[1] atol = 1
-    
+
     # RQA
     rqapar = rqa(rmat, theiler=1, lmin=3, border=20)
     rqadiag = rqa(rmat, theiler=1, lmin=3, border=20, onlydiagonal=true)
     for p in keys(rqadiag)
         @test rqapar[p]==rqadiag[p]
     end
-    
+
     # Windowed RQA
     rmatw = @windowed RecurrenceMatrix(xe, ε, metric=RecurrenceAnalysis.Chebyshev()) 50
     crmatw = @windowed(CrossRecurrenceMatrix(xe, ye, ε),30)
     @windowed jrmatw = JointRecurrenceMatrix(xe, ye, ε) 30
     @test jrmatw[3 .+ (1:30), 3 .+ (1:30)] == jrmat[3 .+ (1:30), 3 .+ (1:30)]
     @windowed(rrw = recurrencerate(rmatw), width=50, step=40)
     @windowed rqaw = rqa(rmatw) width=50 step=40
-    @test rqaw["RR"] == rrw
+    @test rqaw[:RR] == rrw
 
 end
-

test/smallmatrix.jl

@@ -22,7 +22,7 @@ rmat = CrossRecurrenceMatrix(sparse(i,j,trues(length(i))))
 #  7 · x x · · o · · x · x
 #  8 · x · · · · o · · · ·
 #  9 · · · · x · · · o o ·
-#  A · · x · x x · · · o · 
+#  A · · x · x x · · · o ·
 #
 ###
 
@@ -36,19 +36,19 @@ rmat = CrossRecurrenceMatrix(sparse(i,j,trues(length(i))))
             @test histograms[k] == true_histograms[k]
         end
         rqa_params = rqa(rmat, theiler=0, lmin=1, border=1)
-        @test rqa_params["RR"] == 33/110
-        @test rqa_params["DET"] == 1.0
-        @test rqa_params["L"] == 33/20
-        @test rqa_params["Lmax"] == 5
-        @test rqa_params["DIV"] == 0.2
-        @test rqa_params["ENTR"] ≈ 0.996 atol=0.001
-        @test rqa_params["TREND"] ≈ -0.0338 atol=0.0001
-        @test rqa_params["LAM"] == 1.0
-        @test rqa_params["TT"] == 33/23
-        @test rqa_params["Vmax"] == 3
-        @test rqa_params["MRT"] == 33/12
-        @test rqa_params["RTE"] ≈ 1.286 atol=0.001
-        @test rqa_params["NMPRT"] == 4
+        @test rqa_params[:RR] == 33/110
+        @test rqa_params[:DET] == 1.0
+        @test rqa_params[:L] == 33/20
+        @test rqa_params[:Lmax] == 5
+        @test rqa_params[:DIV] == 0.2
+        @test rqa_params[:ENTR] ≈ 0.996 atol=0.001
+        @test rqa_params[:TREND] ≈ -0.0338 atol=0.0001
+        @test rqa_params[:LAM] == 1.0
+        @test rqa_params[:TT] == 33/23
+        @test rqa_params[:Vmax] == 3
+        @test rqa_params[:MRT] == 33/12
+        @test rqa_params[:RTE] ≈ 1.286 atol=0.001
+        @test rqa_params[:NMPRT] == 4
     end
     @testset "With Theiler window" begin
         histograms = recurrencestructures(rmat, theiler=2)
@@ -59,19 +59,19 @@ rmat = CrossRecurrenceMatrix(sparse(i,j,trues(length(i))))
             @test histograms[k] == true_histograms[k]
         end
         rqa_params = rqa(rmat, theiler=2, lmin=1, border=1)
-        @test rqa_params["RR"] == 22/110
-        @test rqa_params["DET"] == 1.0
-        @test rqa_params["L"] == 22/14
-        @test rqa_params["Lmax"] == 5
-        @test rqa_params["DIV"] == 0.2
-        @test rqa_params["ENTR"] ≈ 0.830 atol=0.001
-        @test rqa_params["TREND"] ≈ -0.0122 atol=0.0001
-        @test rqa_params["LAM"] == 1.0
-        @test rqa_params["TT"] == 22/15
-        @test rqa_params["Vmax"] == 3
-        @test rqa_params["MRT"] == 24/6
-        @test rqa_params["RTE"] ≈ 1.011 atol=0.001
-        @test rqa_params["NMPRT"] == 3
+        @test rqa_params[:RR] == 22/110
+        @test rqa_params[:DET] == 1.0
+        @test rqa_params[:L] == 22/14
+        @test rqa_params[:Lmax] == 5
+        @test rqa_params[:DIV] == 0.2
+        @test rqa_params[:ENTR] ≈ 0.830 atol=0.001
+        @test rqa_params[:TREND] ≈ -0.0122 atol=0.0001
+        @test rqa_params[:LAM] == 1.0
+        @test rqa_params[:TT] == 22/15
+        @test rqa_params[:Vmax] == 3
+        @test rqa_params[:MRT] == 24/6
+        @test rqa_params[:RTE] ≈ 1.011 atol=0.001
+        @test rqa_params[:NMPRT] == 3
     end
     @testset "With minimum line" begin
         histograms = recurrencestructures(rmat, lmin=2)
@@ -82,19 +82,19 @@ rmat = CrossRecurrenceMatrix(sparse(i,j,trues(length(i))))
             @test histograms[k] == true_histograms[k]
         end
         rqa_params = rqa(rmat, theiler=0, lmin=2, border=1)
-        @test rqa_params["RR"] == 33/110
-        @test rqa_params["DET"] == 22/33
-        @test rqa_params["L"] == 22/9
-        @test rqa_params["Lmax"] == 5
-        @test rqa_params["DIV"] == 0.2
-        @test rqa_params["ENTR"] ≈ 0.684 atol=0.001
-        @test rqa_params["TREND"] ≈ -0.0338 atol=0.0001
-        @test rqa_params["LAM"] == 18/33
-        @test rqa_params["TT"] == 18/8
-        @test rqa_params["Vmax"] == 3
-        @test rqa_params["MRT"] == 33/12
-        @test rqa_params["RTE"] ≈ 1.286 atol=0.001
-        @test rqa_params["NMPRT"] == 4
+        @test rqa_params[:RR] == 33/110
+        @test rqa_params[:DET] == 22/33
+        @test rqa_params[:L] == 22/9
+        @test rqa_params[:Lmax] == 5
+        @test rqa_params[:DIV] == 0.2
+        @test rqa_params[:ENTR] ≈ 0.684 atol=0.001
+        @test rqa_params[:TREND] ≈ -0.0338 atol=0.0001
+        @test rqa_params[:LAM] == 18/33
+        @test rqa_params[:TT] == 18/8
+        @test rqa_params[:Vmax] == 3
+        @test rqa_params[:MRT] == 33/12
+        @test rqa_params[:RTE] ≈ 1.286 atol=0.001
+        @test rqa_params[:NMPRT] == 4
     end
     @testset "Theiler and minimum line" begin
         histograms = recurrencestructures(rmat, theiler=2, lmin=2)
@@ -105,20 +105,18 @@ rmat = CrossRecurrenceMatrix(sparse(i,j,trues(length(i))))
             @test histograms[k] == true_histograms[k]
         end
         rqa_params = rqa(rmat, theiler=2, lmin=2, border=1)
-        @test rqa_params["RR"] == 22/110
-        @test rqa_params["DET"] == 13/22
-        @test rqa_params["L"] == 13/5
-        @test rqa_params["Lmax"] == 5
-        @test rqa_params["DIV"] == 0.2
-        @test rqa_params["ENTR"] ≈ 0.500 atol=0.001
-        @test rqa_params["TREND"] ≈ -0.0122 atol=0.0001
-        @test rqa_params["LAM"] == 12/22
-        @test rqa_params["TT"] == 12/5
-        @test rqa_params["Vmax"] == 3
-        @test rqa_params["MRT"] == 24/6
-        @test rqa_params["RTE"] ≈ 1.011 atol=0.001
-        @test rqa_params["NMPRT"] == 3
+        @test rqa_params[:RR] == 22/110
+        @test rqa_params[:DET] == 13/22
+        @test rqa_params[:L] == 13/5
+        @test rqa_params[:Lmax] == 5
+        @test rqa_params[:DIV] == 0.2
+        @test rqa_params[:ENTR] ≈ 0.500 atol=0.001
+        @test rqa_params[:TREND] ≈ -0.0122 atol=0.0001
+        @test rqa_params[:LAM] == 12/22
+        @test rqa_params[:TT] == 12/5
+        @test rqa_params[:Vmax] == 3
+        @test rqa_params[:MRT] == 24/6
+        @test rqa_params[:RTE] ≈ 1.011 atol=0.001
+        @test rqa_params[:NMPRT] == 3
     end
 end
-
-