doc updates for histogram stuff (#44)

* doc updates for histogram stuff

* add VENTR to @windowed

* don't test nightly

Author: Datseris

.travis.yml

@@ -4,7 +4,7 @@ os:
   - linux
 julia:
   - 1.0
-  - nightly
+  # - nightly
 branches:
   - only:
     - master

appveyor.yml

@@ -1,7 +1,7 @@
 environment:
   matrix:
   - julia_version: 1
-  - julia_version: nightly
+  # - julia_version: nightly
 
 platform:
   - x86 # 32-bit

src/histograms.jl

@@ -15,9 +15,9 @@ end
 # from the indices of rows and columns/diagonals of the matrix
 # `theiler` is used for histograms of vertical structures
 # `distances` is used to simplify calculations of the distances are not wanted
-function _linehistograms(rows::T, cols::T, lmin::Integer=1, theiler::Integer=0, 
+function _linehistograms(rows::T, cols::T, lmin::Integer=1, theiler::Integer=0,
      distances::Bool=true) where {T<:AbstractVector{Int}}
-    
+
     # check bounds
     n = length(rows)
     if length(cols) != n
@@ -61,7 +61,7 @@ function _linehistograms(rows::T, cols::T, lmin::Integer=1, theiler::Integer=0,
                             halfline = div(current_vert, 2)
                                 if dist != 0
                                     nbins_d = extendhistogram!(bins_d, nbins_d, dist+halfline)
-                                end                        
+                                end
                             # update the distance
                             dist = r-rprev+halfline-1
                         else
@@ -161,10 +161,11 @@ rt_histogram(x; kwargs...) = verticalhistograms(x; kwargs...)[2]
                              vertical=true,
                              recurrencetimes=true,
                              kwargs...)
-    
-Histograms of the recurrence structures contained in the recurrence matrix `x`.
 
-## Description:
+Return a dictionary with the
+histograms of the recurrence structures contained in the recurrence matrix `x`.
+
+## Description
 
 Returns a dictionary with the keys `"diagonal"`, `"vertical"` or
 `"recurrencetimes"`, depending on what keyword arguments are given as `true`.
@@ -181,15 +182,17 @@ All the points of the matrix are counted by default. Extra keyword arguments can
 be passed to rule out the lines shorter than a minimum length or around the main
 diagonal. See the arguments of the function [`rqa`](@ref) for further details.
 
-## References:
+"Empty" histograms are represented always as `[0]`.
+
+## References
 
 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).
 """
 function recurrencestructures(x::ARM;
     diagonal=true, vertical=true, recurrencetimes=true, lmin=1, theiler=0, kwargs...)
-    
+
     # Parse arguments for diagonal and vertical structures
     histograms = Dict{String,Vector{Int}}()
     if diagonal
@@ -208,4 +211,3 @@ function recurrencestructures(x::ARM;
     end
     return histograms
 end
-

src/rqa.jl

@@ -80,7 +80,7 @@ end
 @deprecate rqaentropy dl_entropy
 
 """
-    determinism(x::AbstractRecurrenceMatrix; lmin=2, theiler=0)
+    determinism(x; lmin=2, theiler=0)
 
 Calculate the determinism of the recurrence matrix `x`, ruling out
 the points within the Theiler window of size `theiler` and diagonals shorter
@@ -151,7 +151,7 @@ end
     laminarity(x; lmin=2, theiler=0)
 
 Calculate the laminarity of the recurrence matrix `x`, ruling out the
-points within the Theiler window of size `theiler` and diagonals shorter
+points within the Theiler window of size `theiler` and lines shorter
 than `lmin`.
 """
 function laminarity(x::ARM; kwargs...)
@@ -165,7 +165,7 @@ _laminarity(vert_hist::Vector{<:Integer}, npoints) = _determinism(vert_hist, npo
     trappingtime(x; lmin=2, theiler=0)
 
 Calculate the trapping time of the recurrence matrix `x`, ruling out the
-points within the Theiler window of size `theiler` and diagonals shorter
+points within the Theiler window of size `theiler` and lines shorter
 than `lmin`.
 
 The trapping time is the average of the vertical line structures and thus equal
@@ -182,7 +182,7 @@ trappingtime(x::ARM; kwargs...) = vl_average(x; kwargs...)
     meanrecurrencetime(x; lmin=2, theiler=0)
 
 Calculate the mean recurrence time of the recurrence matrix `x`, ruling out the
-points within the Theiler window of size `theiler` and diagonals shorter
+points within the Theiler window of size `theiler` and lines shorter
 than `lmin`.
 
 Equivalent to [`rt_average`](@ref).
@@ -194,7 +194,7 @@ meanrecurrencetime(x::ARM; kwargs...) = rt_average(x; kwargs...)
     nmprt(x; lmin=2, theiler=0)
 
 Calculate the number of the most probable recurrence time (NMPRT), ruling out the
-points within the Theiler window of size `theiler` and diagonals shorter
+points within the Theiler window of size `theiler` and lines shorter
 than `lmin`.
 """
 nmprt(x::ARM; kwargs) = maximum(verticalhistograms(x; kwargs...)[2])
@@ -229,10 +229,17 @@ The returned value is a dictionary with the following keys:
 * "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))
 
+Notice that 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`.
+
 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").
@@ -268,6 +275,7 @@ function rqa(x; onlydiagonal=false, kwargs...)
             "LAM"  => _laminarity(vhist, rr_v*length(x)),
             "TT"   => _vl_average(vhist),
             "Vmax" => _vl_max(vhist),
+            "VENTR" => _vl_entropy(vhist),
             "MRT"  => _rt_average(rthist),
             "RTE" => _rt_entropy(rthist),
             "NMPRT" => maximum(rthist)

src/windowed.jl

@@ -26,11 +26,11 @@ const rqa_types = Dict(
 
 """
     ij_block_rmat(x, y, bsize, dindex, vargs...; kwargs...)
-    
+
 Return the indices of the rows and columns of the nonzero values of a
 block-diagonal cross-recurrence matrix.
 
-If `m` is the cross-recurrence matrix of `x` and `y` (created with the 
+If `m` is the cross-recurrence matrix of `x` and `y` (created with the
 positional and keyword arguments `vargs` and `kwargs`), the indices returned by
 this function are limited to the "block-diagonal" indicated by
 `dindex ∈ {-1,0,1}`, as in the following graphical representation
@@ -163,6 +163,7 @@ macro windowed(ex, options...)
                     "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)