Auto stash before merge of "main" and "origin/main"

MattWillFlood · Mar 24, 2024 · 337cf8c · 337cf8c
1 parent 617c4e0
commit 337cf8c
Show file tree

Hide file tree

Showing 109 changed files with 1,220 additions and 565 deletions.
diff --git a/docs/EHupdates.rst b/docs/EHupdates.rst
@@ -14,11 +14,68 @@ Latest Updates
 ..............................................................
 
 
-January 2024
+March 2024
 ############
 
-**New announcements coming soon! :)**
-
+Version 1.0 is here!
+====================
+
+| EntropyHub is continuously growing to incorporate the lastest developments in the scientific literature.
+| This new major release (v1.0) reflects that with many new functions and features to provide you with a versatile environment that makes complex entropy methods easy to implement.
+| The following list summarizes some of the main updates available in v1.0.
+
+    **+ New entropy methods**      
+        | Two new base entropy functions (and their multiscale versions) have been added:   
+        | + `Diversity Entropy <https://ieeexplore.ieee.org/document/9194995>`_      
+        | + `Range Entropy <https://www.mdpi.com/1099-4300/20/12/962>`_
+
+    **+ New fuzzy membership functions**  
+        | Several new fuzzy membership functions have been added to FuzzEn, XFuzzEn and FuzzEn2D to provide more options for mapping the degree of similarity between embedding vectors.
+        | These include *trapezoidal*, *triangular* and *gaussian*, among others.
+        | Further info on these membership functions can be found `here. <https://hal.science/hal-02267711/document>`_
+
+    **+ Phase Permutation Entropy**
+        | A new variant - '*phase*' permutation entropy - has been added to PermEn.   
+        | This method employs a hilbert transformation of the data sequence, based on the methods outlined `here. <https://doi.org/10.1016/j.physa.2020.125686>`_
+
+    **+ Cross-Entropy with different length sequences**
+        | EntropyHub v1.0 now allows for cross-entropy (and multiscale cross-entropy) estimation with different length signals (*except XCondEn and XPermEn*).
+        | As a result, the new cross-entropy functions require a separate input for each sequence (Sig1, Sig2).
+
+    **+ Refined-Composite Multiscale Fuzzy Entropy**
+        | In addition to the refined-composite multiscale sample entropy that was available in earlier versions, now one can estimate the refined-composite multiscale fuzzy entropy based on the method outlined `here. <https://link.springer.com/article/10.1007/s11517-017-1647-5>`_
+        | What's more, refined-composite multicale cross-fuzzy entropy is also available, and both can be estimated using any of the fuzzy membership functions in FuzzEn or XFuzzEn.
+
+    **+ Generalized Multiscale Entropy**
+        | Generaized multiscale entropy and generalized multiscale cross-entropy can now be estimated. Just choose the '*generalized*' as the graining procedure in MSEn or XMSEn. 
+
+    **+ Variance of sample entropy estimate**
+        | Based on the `method outlined by Lake et al., <https://journals.physiology.org/doi/epdf/10.1152/ajpregu.00069.2002>`_ it is now possible to obtain a measure of the variance in the sample entropy estimate.
+        | This is achieved by approximating the number of overlapping embedding vectors.
+        | To do so, just set the parameter '*Vcp*'==true in SampEn and XSampEn, but note that doing so requires *a lot* of computer memory.
+
+Several little bugs and inconsistencies have also been fixed in this release. We want to thank all of you who have identified and alerted us to these bugs. 
+Most of these bugs have been noted via the `GitHub issues portal <https://github.com/MattWillFlood/EntropyHub/issues>`_.
+
+    **Bug fixes**
+        | - The DispEn2D function in python has now fixed `this issue <https://github.com/MattWillFlood/EntropyHub/issues/8>`_.
+        | - The type hint for FuzzEn in python has been updated `as requested <https://github.com/MattWillFlood/EntropyHub/issues/1>`_.
+        | - `Compatbility issues with EntropyHub.jl <https://github.com/MattWillFlood/EntropyHub.jl/issues/3>`_ are now resolved.
+        | - A bug in the K2En python function led to incorrect entropy estimates for data sequences with many equal values. This has been corrected.
+    
+    **Other Changes**
+        | - The *'equal'* method for discretizing data in DispEn and DispEn2D has been updated to be consistent across Python, MatLab and Julia.
+        |   This is unlikely to have impacted any users previously.
+        | - The zeroth dimension (m=0) estimate of ApEn and XApEn has been changed to -phi(1).
+        | - The default radius threshold distance for XApEn, XSampEn and XK2En has been changed to use the *pooled* standard deviation [i.e. 0.2*SDpooled(X,Y)].
+    
+
+More to come!
+=============
+
+| We are currently adding several new elements to EntropyHub that we hope will benefit many users. However, this is a time-consuming effort.
+| Keep checking in here to find out more in the future!
+| Thanks for all your support so far :)
 
 ..............................................................
 

diff --git a/docs/Home.rst b/docs/Home.rst
@@ -9,7 +9,7 @@
 EntropyHub 
 **********
 
-An open-source toolkit for entropic time series analysis
+An open-source toolkit for entropic data analysis
 ########################################################
 
 .. image:: ./_images/EntropyHub_Profiler.png
@@ -32,30 +32,22 @@ An open-source toolkit for entropic time series analysis
 * `Take part in our user survey <https://forms.gle/QxwUQASUh3bVhpfN9>`_
 
 
-Welcome
-#######
-
-Welcome to EntropyHub!
-
-This toolkit provides a wide range of functions to calculate different entropy statistics.
+Welcome!
+########
 
-There is an ever-growing range of information-theoretic and dynamical systems entropy measures presented in the scientific literature. 
-Although many functions for estimating these entropies can be found in various corners of the internet, 
-there is currently no toolkit to perform entropic time-series analysis in MatLab, Python and Julia, all with an extensive documentation and consistent syntax.
-
-The goal of EntropyHub is to integrate the many established entropy methods in one open-source package.
+| This toolkit provides a wide range of functions to calculate different entropy statistics.
+| There is an ever-growing range of information-theoretic and dynamical systems entropy measures presented in the scientific literature. 
+| The goal of EntropyHub is to integrate the many established entropy methods in one open-source package.
 
+.........................................................................................................
 
 About
 #####
 
 Information and uncertainty can be regarded as two sides of the same coin: 
 the more uncertainty there is, the more information we gain by removing that uncertainty.
-In the context of information and probability theory, **Entropy** quantifies that uncertainty. 
+In the context of dynamical systems and information theory, **Entropy** quantifies that uncertainty. 
 
-The concept of entropy has its origins in `classical physics <http://www.scholarpedia.org/article/Entropy>`_ under the second law of thermodynamics, 
-a law `considered to underpin our fundamental understanding <https://www.penguin.co.uk/books/301539/the-order-of-time/9780141984964.html>`_
-of `time in physics <https://en.wikipedia.org/wiki/Time_in_physics>`_. 
 In the context of nonlinear dynamics, entropy is central in quantifying the degree of uncertainty or information gain, and is therefore widely used
 to explain complex nonlinear behaviour in real-world systems.
 Attempting to analyse the analog world around us requires that we measure time in discrete steps, but doing so compromises 
@@ -68,33 +60,29 @@ To overcome this, we have developed EntropyHub - an open-source toolkit designed
 The goal of EntropyHub is to provide a comprehensive set of functions with a simple and consistent syntax that allows the user to augment parameters at the command 
 line, enabling a range from basic to advanced entropy methods to be implemented with ease.
 
-**It is important to clarify that the entropy functions herein described estimate entropy in the context of nonlinear dynamics, probability theory and information theory, and not thermodynamic or other entropies from classical physics.**
+.. note::
 
-.........................................................................................................
+    It is important to clarify that the entropy functions herein described estimate entropy in the context of nonlinear dynamics, probability theory and information theory, and not thermodynamic or other entropies from classical physics.
 
+.........................................................................................................
 
 Documentation & Help 
 ####################
 
-The `EntropyHub Guide <https://github.com/MattWillFlood/EntropyHub/blob/main/EntropyHub%20Guide.pdf>`_ is a .pdf booklet written to help you use the toolkit effectively 
-(available for :download:`download here <./_static/EntropyHubGuide.pdf>`).
-
-In this guide you will find descriptions of function syntax, examples of function use, and references to the source literature of each function.
-
-*The MatLab version of the toolkit has a comprehensive help section which can be accessed through the help browser.*
-
+| The `EntropyHub Guide <https://github.com/MattWillFlood/EntropyHub/blob/main/EntropyHub%20Guide.pdf>`_ is a .pdf booklet written to help you use the toolkit effectively (available for :download:`download here <./_static/EntropyHubGuide.pdf>`).
+| In this guide you will find descriptions of function syntax, examples of function use, and references to the source literature of each function.
+| *The MatLab version of the toolkit has a comprehensive help section which can be accessed through the MatLab help browser under* **Supplementary Software**.
 
 .........................................................................................................
 
-
 Citation and Licensing
 ######################
 
 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 scientific outputs
 realized using the software:
 
-        | **Matthew W. Flood and Bernd Grimm,**     
+        | **Matthew W. Flood**     
         | **EntropyHub: An Open-Source Toolkit for Entropic Time Series Analysis,**    
         | **PLoS One 16(11):e0259448 (2021),** 
         | **DOI: 10.1371/journal.pone.0259448**    
@@ -104,7 +92,7 @@ realized using the software:
 __________________________________________________________________
 
 
-        © Copyright 2021 Matthew W. Flood, EntropyHub
+        © Copyright 2024 Matthew W. Flood, EntropyHub
 
         Licensed under the Apache License, Version 2.0 (the "License");
         you may not use this file except in compliance with the License.

diff --git a/docs/_build/doctrees/EHupdates.doctree b/docs/_build/doctrees/EHupdates.doctree
diff --git a/docs/_build/doctrees/Home.doctree b/docs/_build/doctrees/Home.doctree
diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle
diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree
diff --git a/docs/_build/doctrees/julia/EHjulia.doctree b/docs/_build/doctrees/julia/EHjulia.doctree
diff --git a/docs/_build/doctrees/julia/jlexamples.doctree b/docs/_build/doctrees/julia/jlexamples.doctree
diff --git a/docs/_build/doctrees/matlab/Functions/matBase.doctree b/docs/_build/doctrees/matlab/Functions/matBase.doctree
diff --git a/docs/_build/doctrees/matlab/Functions/matBidimensional.doctree b/docs/_build/doctrees/matlab/Functions/matBidimensional.doctree
diff --git a/docs/_build/doctrees/matlab/Functions/matCross.doctree b/docs/_build/doctrees/matlab/Functions/matCross.doctree
diff --git a/docs/_build/doctrees/matlab/Functions/matMultiscale.doctree b/docs/_build/doctrees/matlab/Functions/matMultiscale.doctree
diff --git a/docs/_build/doctrees/matlab/Functions/matMultiscaleCross.doctree b/docs/_build/doctrees/matlab/Functions/matMultiscaleCross.doctree
diff --git a/docs/_build/doctrees/matlab/matAPI.doctree b/docs/_build/doctrees/matlab/matAPI.doctree
diff --git a/docs/_build/doctrees/matlab/matexamples.doctree b/docs/_build/doctrees/matlab/matexamples.doctree
diff --git a/docs/_build/doctrees/python/Functions/Base.doctree b/docs/_build/doctrees/python/Functions/Base.doctree
diff --git a/docs/_build/doctrees/python/Functions/Bidimensional.doctree b/docs/_build/doctrees/python/Functions/Bidimensional.doctree
diff --git a/docs/_build/doctrees/python/Functions/Cross.doctree b/docs/_build/doctrees/python/Functions/Cross.doctree
diff --git a/docs/_build/doctrees/python/Functions/Multiscale.doctree b/docs/_build/doctrees/python/Functions/Multiscale.doctree
diff --git a/docs/_build/doctrees/python/Functions/MultiscaleCross.doctree b/docs/_build/doctrees/python/Functions/MultiscaleCross.doctree
diff --git a/docs/_build/doctrees/python/pyAPI.doctree b/docs/_build/doctrees/python/pyAPI.doctree
diff --git a/docs/_build/doctrees/python/pyexamples.doctree b/docs/_build/doctrees/python/pyexamples.doctree
diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: fcb175b2998db6b15323ea5f97d34dc3
+config: a08dde90a3c13e8b0243414d25c4c8a4
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_build/html/EHupdates.html b/docs/_build/html/EHupdates.html
@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Latest Updates &mdash; EntropyHub 0.2 documentation</title>
+  <title>Latest Updates &mdash; EntropyHub 1.0 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -161,9 +161,87 @@ <h1>Latest Updates<a class="headerlink" href="#latest-updates" title="Permalink
 <div class="toctree-wrapper compound">
 </div>
 <hr class="docutils" />
-<section id="january-2024">
-<h2>January 2024<a class="headerlink" href="#january-2024" title="Permalink to this heading"></a></h2>
-<p><strong>New announcements coming soon! :)</strong></p>
+<section id="march-2024">
+<h2>March 2024<a class="headerlink" href="#march-2024" title="Permalink to this heading"></a></h2>
+<section id="version-1-0-is-here">
+<h3>Version 1.0 is here!<a class="headerlink" href="#version-1-0-is-here" title="Permalink to this heading"></a></h3>
+<div class="line-block">
+<div class="line">EntropyHub is continuously growing to incorporate the lastest developments in the scientific literature.</div>
+<div class="line">This new major release (v1.0) reflects that with many new functions and features to provide you with a versatile environment that makes complex entropy methods easy to implement.</div>
+<div class="line">The following list summarizes some of the main updates available in v1.0.</div>
+</div>
+<blockquote>
+<div><dl>
+<dt><strong>+ New entropy methods</strong></dt><dd><div class="line-block">
+<div class="line">Two new base entropy functions (and their multiscale versions) have been added:</div>
+<div class="line">+ <a class="reference external" href="https://ieeexplore.ieee.org/document/9194995">Diversity Entropy</a></div>
+<div class="line">+ <a class="reference external" href="https://www.mdpi.com/1099-4300/20/12/962">Range Entropy</a></div>
+</div>
+</dd>
+<dt><strong>+ New fuzzy membership functions</strong></dt><dd><div class="line-block">
+<div class="line">Several new fuzzy membership functions have been added to FuzzEn, XFuzzEn and FuzzEn2D to provide more options for mapping the degree of similarity between embedding vectors.</div>
+<div class="line">These include <em>trapezoidal</em>, <em>triangular</em> and <em>gaussian</em>, among others.</div>
+<div class="line">Further info on these membership functions can be found <a class="reference external" href="https://hal.science/hal-02267711/document">here.</a></div>
+</div>
+</dd>
+<dt><strong>+ Phase Permutation Entropy</strong></dt><dd><div class="line-block">
+<div class="line">A new variant - ‘<em>phase</em>’ permutation entropy - has been added to PermEn.</div>
+<div class="line">This method employs a hilbert transformation of the data sequence, based on the methods outlined <a class="reference external" href="https://doi.org/10.1016/j.physa.2020.125686">here.</a></div>
+</div>
+</dd>
+<dt><strong>+ Cross-Entropy with different length sequences</strong></dt><dd><div class="line-block">
+<div class="line">EntropyHub v1.0 now allows for cross-entropy (and multiscale cross-entropy) estimation with different length signals (<em>except XCondEn and XPermEn</em>).</div>
+<div class="line">As a result, the new cross-entropy functions require a separate input for each sequence (Sig1, Sig2).</div>
+</div>
+</dd>
+<dt><strong>+ Refined-Composite Multiscale Fuzzy Entropy</strong></dt><dd><div class="line-block">
+<div class="line">In addition to the refined-composite multiscale sample entropy that was available in earlier versions, now one can estimate the refined-composite multiscale fuzzy entropy based on the method outlined <a class="reference external" href="https://link.springer.com/article/10.1007/s11517-017-1647-5">here.</a></div>
+<div class="line">What’s more, refined-composite multicale cross-fuzzy entropy is also available, and both can be estimated using any of the fuzzy membership functions in FuzzEn or XFuzzEn.</div>
+</div>
+</dd>
+<dt><strong>+ Generalized Multiscale Entropy</strong></dt><dd><div class="line-block">
+<div class="line">Generaized multiscale entropy and generalized multiscale cross-entropy can now be estimated. Just choose the ‘<em>generalized</em>’ as the graining procedure in MSEn or XMSEn.</div>
+</div>
+</dd>
+<dt><strong>+ Variance of sample entropy estimate</strong></dt><dd><div class="line-block">
+<div class="line">Based on the <a class="reference external" href="https://journals.physiology.org/doi/epdf/10.1152/ajpregu.00069.2002">method outlined by Lake et al.,</a> it is now possible to obtain a measure of the variance in the sample entropy estimate.</div>
+<div class="line">This is achieved by approximating the number of overlapping embedding vectors.</div>
+<div class="line">To do so, just set the parameter ‘<em>Vcp</em>’==true in SampEn and XSampEn, but note that doing so requires <em>a lot</em> of computer memory.</div>
+</div>
+</dd>
+</dl>
+</div></blockquote>
+<p>Several little bugs and inconsistencies have also been fixed in this release. We want to thank all of you who have identified and alerted us to these bugs.
+Most of these bugs have been noted via the <a class="reference external" href="https://github.com/MattWillFlood/EntropyHub/issues">GitHub issues portal</a>.</p>
+<blockquote>
+<div><dl>
+<dt><strong>Bug fixes</strong></dt><dd><div class="line-block">
+<div class="line">- The DispEn2D function in python has now fixed <a class="reference external" href="https://github.com/MattWillFlood/EntropyHub/issues/8">this issue</a>.</div>
+<div class="line">- The type hint for FuzzEn in python has been updated <a class="reference external" href="https://github.com/MattWillFlood/EntropyHub/issues/1">as requested</a>.</div>
+<div class="line">- <a class="reference external" href="https://github.com/MattWillFlood/EntropyHub.jl/issues/3">Compatbility issues with EntropyHub.jl</a> are now resolved.</div>
+<div class="line">- A bug in the K2En python function led to incorrect entropy estimates for data sequences with many equal values. This has been corrected.</div>
+</div>
+</dd>
+<dt><strong>Other Changes</strong></dt><dd><div class="line-block">
+<div class="line">- The <em>‘equal’</em> method for discretizing data in DispEn and DispEn2D has been updated to be consistent across Python, MatLab and Julia.</div>
+<div class="line-block">
+<div class="line">This is unlikely to have impacted any users previously.</div>
+</div>
+<div class="line">- The zeroth dimension (m=0) estimate of ApEn and XApEn has been changed to -phi(1).</div>
+<div class="line">- The default radius threshold distance for XApEn, XSampEn and XK2En has been changed to use the <em>pooled</em> standard deviation [i.e. 0.2*SDpooled(X,Y)].</div>
+</div>
+</dd>
+</dl>
+</div></blockquote>
+</section>
+<section id="more-to-come">
+<h3>More to come!<a class="headerlink" href="#more-to-come" title="Permalink to this heading"></a></h3>
+<div class="line-block">
+<div class="line">We are currently adding several new elements to EntropyHub that we hope will benefit many users. However, this is a time-consuming effort.</div>
+<div class="line">Keep checking in here to find out more in the future!</div>
+<div class="line">Thanks for all your support so far :)</div>
+</div>
+</section>
 </section>
 <hr class="docutils" />
 <section id="november-2022">
@@ -266,7 +344,7 @@ <h2>June 2021<a class="headerlink" href="#june-2021" title="Permalink to this he
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2023, Matthew W. Flood.</p>
+    <p>&#169; Copyright 2024, Matthew W. Flood.</p>
   </div>