EntropyHub Julia - v0.1.1a

Update of EnofEn to include Xrange as optional argument and corrections to text in PermEn and PhasEn.

CITATION.bib

@@ -1,6 +1,12 @@
 @misc{EntropyHub.jl,
-	author  = {Matthew W. Flood},
-	title   = {EntropyHub: an open-source toolkit for entropic time series analysis},
-	url     = {https://www.EntropyHub.xyz},
+	title   = {EntropyHub: An Open-source Toolkit for Entropic Time Series Analysis},
+	author  = {Flood, Matthew W. and Grimm, Bernd},
+	journal = {PLoS ONE},
+	volume  = {16},
+	number  = {11},
+	pages   = {e0259448},
 	year    = {2021},
-}
+	publisher = {Public Library of Science},
+	doi     = {10.1371/journal.pone.0259448},
+	url     = {https://doi.org/10.1371/journal.pone.0259448},
+	}

Project.toml

@@ -1,7 +1,7 @@
 name = "EntropyHub"
 uuid = "3938faea-3bfa-4bc3-8092-0c6746ff9af1"
 authors = ["Matthew W. Flood <[email protected]>"]
-version = "0.1.1"
+version = "0.1.1a"
 
 [deps]
 Clustering = "aaaa29a8-35af-508c-8bc3-b662a17a0fe5"
@@ -20,7 +20,6 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
 
 [compat]
-julia = "1.5"
 Clustering = "0.14.2"
 Combinatorics = "1.0.2"
 DSP = "0.6.8"
@@ -31,6 +30,7 @@ HTTP = "0.8.19"
 Plots = "1.10.3"
 StatsBase = "0.33.2"
 StatsFuns = "0.9.6"
+julia = "1.5"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -137,12 +137,12 @@ Dispersion Entropy                            		  |	DispEn
 Symbolic Dynamic Entropy                          	  |	SyDyEn
 Increment Entropy                                 	  |	IncrEn
 Cosine Similarity Entropy                         	  |	CoSiEn
-Phase Entropy                                         |	PhasEn
-Slope Entropy                                      	  |	SlopEn
+Phase Entropy                                        |	PhasEn
+Slope Entropy                                        |	SlopEn
 Bubble Entropy                                		  |	BubbEn
-Gridded Distribution Entropy                          |	GridEn
-Entropy of Entropy                            	      |	EnofEn
-Attention Entropy                                     |	AttnEn
+Gridded Distribution Entropy                         |	GridEn
+Entropy of Entropy                            	     |	EnofEn
+Attention Entropy                                    |	AttnEn
 
 _______________________________________________________________________
 
@@ -156,7 +156,7 @@ Cross Fuzzy Entropy                                   |	XFuzzEn
 Cross Permutation Entropy                             |	XPermEn
 Cross Conditional Entropy                             |	XCondEn
 Cross Distribution Entropy                            |	XDistEn
-Cross Spectral Entropy                          	  |	XSpecEn
+Cross Spectral Entropy                          	   |	XSpecEn
 Cross Kolmogorov Entropy                              |	XK2En
 
 _______________________________________________________________________
@@ -165,9 +165,11 @@ _______________________________________________________________________
 
 Entropy Type   |  Function Name 
 --|--
-Bi-Dimensional Sample Entropy                         |	SampEn2D
-Bi-Dimensional Fuzzy Entropy                          |	FuzzEn2D
-Bi-Dimensional Distribution Entropy                   |	DistEn2D
+Bidimensional Sample Entropy                         |	SampEn2D
+Bidimensional Fuzzy Entropy                          |	FuzzEn2D
+Bidimensional Distribution Entropy                   |	DistEn2D
+Bidimensional Dispersion Entropy                     |	DispEn2D
+
 
 _________________________________________________________________________
 
@@ -178,7 +180,7 @@ Entropy Type   |  Function Name
 Multiscale Entropy                                    | MSEn
 Composite/Refined-Composite Multiscale Entropy        | cMSEn
 Refined Multiscale Entropy                            | rMSEn
-Hierarchical Multiscale Entropy                 | hMSEn
+Hierarchical Multiscale Entropy                       | hMSEn
 
 _________________________________________________________________________
 
@@ -187,7 +189,7 @@ Entropy Type   |  Function Name
 --|--
 Multiscale Cross-Entropy                              |   XMSEn
 Composite/Refined-Composite Multiscale Cross-Entropy  |   cXMSEn
-Refined Multiscale Cross-Entropy                            |   rXMSEn
+Refined Multiscale Cross-Entropy                      |   rXMSEn
 Hierarchical Multiscale Cross-Entropy                 |   hXMSEn
 
 
@@ -199,9 +201,11 @@ EntropyHub is licensed under the Apache License (Version 2.0) and is free to
 use by all on condition that the following reference be included on any outputs
 realized using the software:
 
-        Matthew W. Flood and Bernd Grimm, 
+        Matthew W. Flood and Bernd Grimm (2021), 
         EntropyHub: An Open-Source Toolkit for Entropic Time Series Analysis,
-        2021 www.EntropyHub.xyz
+        PLoS ONE 16(11):e0259448
+        DOI:   10.1371/journal.pone.0259448
+        www.EntropyHub.xyz
 
 __________________________________________________________________
 
@@ -229,8 +233,10 @@ If you find this package useful, please consider starring it on GitHub,
 MatLab File Exchange, PyPI or Julia Packages as this helps us to gauge user 
 satisfaction.
 
-If you have any questions about the package or identify any issues, 
-please do not hesitate to contact us at:    [email protected]
+If you have any questions about the package, please do not hesitate to contact us at: [email protected]
+If you identify any bugs, please contact us at: [email protected]
+If you need any help installing or using the toolkit, please contact us at: [email protected]
+
 
 
 ***Thank you*** for using EntropyHub.

src/EntropyHub.jl

@@ -244,11 +244,12 @@ Cross Spectral Entropy                                |	XSpecEn
 Cross Kolmogorov Entropy                              |	XK2En
 	
 _________________________________________________________________________
-Bi-Dimensional Entropies                              |	Function Name
-______________________________________________________|__________________
-Bi-Dimensional Sample Entropy                         |	SampEn2D
-Bi-Dimensional Fuzzy Entropy                          |	FuzzEn2D
-Bi-Dimensional Distribution Entropy                   |	DistEn2D
+Bidimensional Entropies                              |	Function Name
+_____________________________________________________|__________________
+Bidimensional Sample Entropy                         |	SampEn2D
+Bidimensional Fuzzy Entropy                          |	FuzzEn2D
+Bidimensional Distribution Entropy                   |	DistEn2D
+Bidimensional Dispersion Entropy                     |	DispEn2D
 	
 _________________________________________________________________________
 Multiscale Entropy Functions                          | Function Name
@@ -307,9 +308,11 @@ Multiscale Cross-Conditional Entropy                  |
   include the following citation with the appropriate version number,
   as well as original articles upon which functions are derived:
 
-  Matthew W. Flood, 
+  Matthew W. Flood and Bernd Grimm (2021), 
   "EntropyHub - An open source toolkit for entropic time series analysis"
-  2021, https://github.com/MattWillFlood/EntropyHub
+  PLoS ONE 16(11):e0295448, 
+  DOI:  10.1371/journal.pone.0259448
+  https://www.EntropyHub.xyz
 
   © Copyright 2021 Matthew W. Flood, EntropyHub
 

src/_EnofEn.jl

@@ -1,23 +1,26 @@
 module _EnofEn
 export EnofEn
-using StatsBase: Histogram, fit
+using StatsBase: countmap, Histogram, fit
     """
-        EoE, AvEn = EnofEn(Sig) 
+        EoE, AvEn, S2 = EnofEn(Sig) 
 
-    Returns the entropy of entropy (`EoE`) and the average Shannon entropy 
-    across all windows (`AvEn`) estimated from the data sequence (`Sig`) using
+    Returns the entropy of entropy (`EoE`), the average Shannon entropy (`AvEn`), and
+    the number of levels (`S2`) across all windows estimated from the data sequence (`Sig`) using
     the default parameters: 
-    window length (samples) = 10, slices (s1,s2) = [10 5], logarithm = natural
+    window length (samples) = 10, slices = 10, logarithm = natural, 
+    heartbeat interval range (xmin, xmax) = (min(Sig), max(Sig))
 
-        EoE, AvEn = EnofEn(Sig::AbstractArray{T,1} where T<:Real; tau::Int=10, S::Tuple{Int,Int}=(10,5), Logx::Real=exp(1))
+
+        EoE, AvEn, S2 = EnofEn(Sig::AbstractArray{T,1} where T<:Real; tau::Int=10, S::Int=10, Xrange::Tuple{Real,REal}, Logx::Real=exp(1))
 
     Returns the entropy of entropy (`EoE`) estimated from the data sequence 
     (`Sig`)  using the specified 'keyword' arguments:
 
     # Arguments:
-    `tau`   - Window length, an integer > 1 \n
-    `S`     - Number of slices (s1,s2), a two-element tuple of integers > 2 \n
-    `Logx`  - Logarithm base, a positive scalar  \n
+    `tau`    - Window length, an integer > 1 \n
+    `S`      - Number of slices (s1,s2), a two-element tuple of integers > 2 \n
+    `Xrange` - The min and max heartbeat interval, a two-element tuple where X[1] <= X[2]\n
+    `Logx`   - Logarithm base, a positive scalar  \n
 
     # See also `SampEn`, `MSEn`, `ApEn`
 
@@ -29,19 +32,21 @@ using StatsBase: Histogram, fit
             19.10 (2017): 550.
 
     """
-    function EnofEn(Sig::AbstractArray{T,1} where T<:Real; tau::Int=10, 
-            S::Tuple{Int,Int}=(10,5), Logx::Real=exp(1))
+    function EnofEn(Sig::AbstractArray{T,1} where T<:Real; tau::Int=10, S::Int=10,
+                        Xrange::Tuple{Real,Real}=(minimum(Sig),maximum(Sig)), Logx::Real=exp(1))
 
     N = size(Sig,1)
     (N > 10) ? nothing :  error("Sig:   must be a numeric vector")
-    (tau > 1) ? nothing : error("tau:   must be an integer > 0")
-    (minimum(S)>2) ? nothing : error("S:      must be a 2-element vector of integers > 2")
+    (tau > 1 && tau < length(Sig)) ? nothing : error("tau:   must be an integer > 1")
+    (S > 1) ? nothing : error("S:  must be an integer > 1")
+    (length(Xrange)==2 && (Xrange[1]<=Xrange[2])) ? nothing : error("Xrange:   must be a two-element numeric tuple where Xrange[1]<Xrange[2]")
     (Logx>0) ? nothing :  error("Logx:     must be a positive number > 0")
 
     Wn = Int(floor(N/tau))
     Wj = transpose(reshape(Sig[1:Wn*tau],tau,Wn))
     Yj = zeros(Wn)
-    Edges = collect(range(minimum(Sig),maximum(Sig),length=(S[1]+1)))
+    #Edges = collect(range(minimum(Sig),maximum(Sig),length=(S[1]+1)))
+    Edges = collect(range(Xrange[1],Xrange[2],length=(S+1)))
     Edges[1] -= .1;  Edges[end] += .1
     for n = 1:Wn
         Temp = fit(Histogram,Wj[n,:],Edges).weights/tau
@@ -50,16 +55,18 @@ using StatsBase: Histogram, fit
     end
 
     AvEn = sum(Yj)/Wn
-    Edges = collect(range(minimum(Yj),maximum(Yj),length=(S[2]+1)))
-    Edges[1] -= .1;  Edges[end] += .1
-    Pjl = fit(Histogram,Yj,Edges).weights/Wn
-    Pjl = Pjl[Pjl.>0]
+    #Edges = collect(range(minimum(Yj),maximum(Yj),length=(S[2]+1)))
+    #Edges[1] -= .1;  Edges[end] += .1
+    #Pjl = fit(Histogram,Yj,Edges).weights/Wn
+    #Pjl = Pjl[Pjl.>0]
+    Pjl = collect(values(countmap(round.(Yj,digits=12))))./Wn    
+    S2 = length(Pjl)
     if round(sum(Pjl),digits=5) != 1
         @warn("Possible error estimating probabilities")
     end
 
     EoE = -sum(Pjl.*log.(Logx, Pjl))
-    return EoE, AvEn
+    return EoE, AvEn, S2
 
     end
 end

src/_PermEn.jl

@@ -11,6 +11,7 @@ using Statistics: std, var, mean
     parameters: embedding dimension = 2, time delay = 1, logarithm = base 2, 
     normalisation = w.r.t #symbols (`m`-1)
     Note: using the standard PermEn estimation, `Perm` = 0 when `m` = 1.
+    Note: It is recommeneded that signal length > 5m! (see [8] and Amigo et al., Europhys. Lett. 83:60005, 2008)
 
         Perm, Pnorm, cPE = PermEn(Sig, m)
 

src/_PhasEn.jl

@@ -16,12 +16,14 @@ using Random: randperm
    
     # Arguments:
     `K`     - Angular partitions (coarse graining), an integer > 1  \n
+                *Note: Division of partitions begins along the positive x-axis. As this point is somewhat arbitrary, it is
+                 recommended to use even-numbered (preferably multiples of 4) partitions for sake of symmetry. \n
     `tau`   - Time Delay, a positive integer    \n
     `Logx`  - Logarithm base, a positive scalar \n 
     `Norm`  - Normalisation of `Phas` value:    \n
               [false]  no normalisation
               [true]   normalises w.r.t. the number of partitions Log(`K`)
-    `Plotx` - When `Plotx` == true, returns Poicaré plot (default: false)  \n
+    `Plotx` - When `Plotx` == true, returns Poincaré plot (default: false)  \n
  
     # See also `SampEn`, `ApEn`, `GridEn`, `MSEn`, `SlopEn`, `CoSiEn`, `BubbEn`