Skip to content

DOC: Fix and improve docstrings across entropy, fractal, and utils modules #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
raphaelvallat merged 3 commits into from
Mar 6, 2026
Merged

DOC: Fix and improve docstrings across entropy, fractal, and utils modules #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
64e7a5c
Fix broken Returns in app_entropy
raphaelvallat Mar 6, 2026
5993605
Improve documentation
raphaelvallat Mar 6, 2026
440b207
Update doc
raphaelvallat Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 17 additions & 14 deletions docs/build/html/_modules/antropy/entropy.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>

<span class="sd"> The permutation entropy of a signal :math:`x` is defined as:</span>

<span class="sd"> .. math:: H = -\\sum p(\\pi)\\log_2(\\pi)</span>
<span class="sd"> .. math:: H = -\\sum p(\\pi)\\log_2 p(\\pi)</span>

<span class="sd"> where the sum runs over all :math:`n!` permutations :math:`\\pi` of order</span>
<span class="sd"> :math:`n`. This is the information contained in comparing :math:`n`</span>
Expand Down Expand Up @@ -514,10 +514,12 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> * ``&#39;welch&#39;`` : Welch periodogram (:py:func:`scipy.signal.welch`)</span>
<span class="sd"> nperseg : int or None</span>
<span class="sd"> Length of each FFT segment for Welch method.</span>
<span class="sd"> If None (default), uses scipy default of 256 samples.</span>
<span class="sd"> If None (default), uses scipy&#39;s default (256 samples, or the length</span>
<span class="sd"> of the signal if shorter).</span>
<span class="sd"> normalize : bool</span>
<span class="sd"> If True, divide by log2(psd.size) to normalize the spectral entropy</span>
<span class="sd"> between 0 and 1. Otherwise, return the spectral entropy in bit.</span>
<span class="sd"> If True, divide by log2(number of frequency bins) to normalize the</span>
<span class="sd"> spectral entropy between 0 and 1. Otherwise, return the spectral</span>
<span class="sd"> entropy in bit.</span>
<span class="sd"> axis : int</span>
<span class="sd"> The axis along which the entropy is calculated. Default is -1 (last).</span>

Expand Down Expand Up @@ -629,8 +631,8 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> delay : int</span>
<span class="sd"> Time delay (lag). Default is 1.</span>
<span class="sd"> normalize : bool</span>
<span class="sd"> If True, divide by log2(order!) to normalize the entropy between 0</span>
<span class="sd"> and 1. Otherwise, return the permutation entropy in bit.</span>
<span class="sd"> If True, divide by log2(order) to normalize the entropy between 0</span>
<span class="sd"> and 1. Otherwise, return the SVD entropy in bit.</span>

<span class="sd"> Returns</span>
<span class="sd"> -------</span>
Expand Down Expand Up @@ -836,6 +838,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> :py:class:`sklearn.neighbors.KDTree`. Default is to use the</span>
<span class="sd"> `Chebyshev &lt;https://en.wikipedia.org/wiki/Chebyshev_distance&gt;`_</span>
<span class="sd"> distance.</span>

<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> ae : float</span>
Expand Down Expand Up @@ -962,8 +965,8 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> :math:`C(m + 1, r)` is the number of embedded vectors of length</span>
<span class="sd"> :math:`m + 1` having a</span>
<span class="sd"> `Chebyshev distance &lt;https://en.wikipedia.org/wiki/Chebyshev_distance&gt;`_</span>
<span class="sd"> inferior to :math:`r` and :math:`C(m, r)` is the number of embedded</span>
<span class="sd"> vectors of length :math:`m` having a Chebyshev distance inferior to</span>
<span class="sd"> less than :math:`r` and :math:`C(m, r)` is the number of embedded</span>
<span class="sd"> vectors of length :math:`m` having a Chebyshev distance less than</span>
<span class="sd"> :math:`r`.</span>

<span class="sd"> Note that if ``metric == &#39;chebyshev&#39;`` and ``len(x) &lt; 5000`` points,</span>
Expand Down Expand Up @@ -1096,14 +1099,14 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<a class="viewcode-back" href="../../generated/antropy.lziv_complexity.html#antropy.lziv_complexity">[docs]</a>
<span class="k">def</span><span class="w"> </span><span class="nf">lziv_complexity</span><span class="p">(</span><span class="n">sequence</span><span class="p">,</span> <span class="n">normalize</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Lempel-Ziv (LZ) complexity of (binary) sequence.</span>
<span class="sd"> Lempel-Ziv (LZ) complexity of a sequence.</span>

<span class="sd"> .. versionadded:: 0.1.1</span>

<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> sequence : str or array</span>
<span class="sd"> A sequence of character, e.g. ``&#39;1001111011000010&#39;``,</span>
<span class="sd"> A sequence of characters, e.g. ``&#39;1001111011000010&#39;``,</span>
<span class="sd"> ``[0, 1, 0, 1, 1]``, or ``&#39;Hello World!&#39;``.</span>
<span class="sd"> normalize : bool</span>
<span class="sd"> If ``True``, returns the normalized LZ (see Notes).</span>
Expand All @@ -1119,7 +1122,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> Notes</span>
<span class="sd"> -----</span>
<span class="sd"> LZ complexity is defined as the number of different substrings encountered</span>
<span class="sd"> as the sequence is viewed from begining to the end.</span>
<span class="sd"> as the sequence is viewed from beginning to the end.</span>

<span class="sd"> Although the raw LZ is an important complexity indicator, it is heavily</span>
<span class="sd"> influenced by sequence length (longer sequence will result in higher LZ).</span>
Expand Down Expand Up @@ -1220,7 +1223,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="k">def</span><span class="w"> </span><span class="nf">num_zerocross</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">normalize</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Number of zero-crossings.</span>

<span class="sd"> .. versionadded: 0.1.3</span>
<span class="sd"> .. versionadded:: 0.1.3</span>

<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
Expand Down Expand Up @@ -1309,7 +1312,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="k">def</span><span class="w"> </span><span class="nf">hjorth_params</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Calculate Hjorth mobility and complexity on given axis.</span>

<span class="sd"> .. versionadded: 0.1.3</span>
<span class="sd"> .. versionadded:: 0.1.3</span>

<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
Expand All @@ -1327,7 +1330,7 @@ <h1>Source code for antropy.entropy</h1><div class="highlight"><pre>
<span class="sd"> -----</span>
<span class="sd"> Hjorth Parameters are indicators of statistical properties used in signal</span>
<span class="sd"> processing in the time domain introduced by Bo Hjorth in 1970. The</span>
<span class="sd"> parameters are activity, mobility, and complexity. EntroPy only returns the</span>
<span class="sd"> parameters are activity, mobility, and complexity. AntroPy only returns the</span>
<span class="sd"> mobility and complexity parameters, since activity is simply the variance</span>
<span class="sd"> of :math:`x`, which can be computed easily with :py:func:`numpy.var`.</span>

Expand Down
46 changes: 36 additions & 10 deletions docs/build/html/_modules/antropy/fractal.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -603,6 +603,25 @@ <h1>Source code for antropy.fractal</h1><div class="highlight"><pre>

<span class="sd"> Notes</span>
<span class="sd"> -----</span>
<span class="sd"> For each interval :math:`k` from 1 to ``kmax``, :math:`k` sub-series are</span>
<span class="sd"> constructed from the signal :math:`x` of length :math:`N`. Letting</span>
<span class="sd"> :math:`N_m = \\lfloor (N-m)/k \\rfloor`, the normalised length for each</span>
<span class="sd"> sub-series starting at :math:`m` is:</span>

<span class="sd"> .. math::</span>

<span class="sd"> L_m(k) = \\frac{N-1}{k^2 \\cdot N_m}</span>
<span class="sd"> \\sum_{j=1}^{N_m - 1} |x_{m+jk} - x_{m+(j-1)k}|</span>

<span class="sd"> and the average length across all :math:`k` sub-series is:</span>

<span class="sd"> .. math:: L(k) = \\frac{1}{k} \\sum_{m=1}^{k} L_m(k)</span>

<span class="sd"> The fractal dimension is then estimated as the slope of the linear</span>
<span class="sd"> regression of :math:`\\log L(k)` against :math:`\\log(1/k)`:</span>

<span class="sd"> .. math:: \\text{FD} = \\frac{d \\log L(k)}{d \\log(1/k)}</span>

<span class="sd"> Original code from the `mne-features &lt;https://mne.tools/mne-features/&gt;`_</span>
<span class="sd"> package by Jean-Baptiste Schiratti and Alexandre Gramfort.</span>

Expand All @@ -614,6 +633,13 @@ <h1>Source code for antropy.fractal</h1><div class="highlight"><pre>
<span class="sd"> basis of the fractal theory.&quot; Physica D: Nonlinear Phenomena 31.2</span>
<span class="sd"> (1988): 277-283.</span>

<span class="sd"> Esteller, R. et al. (2001). A comparison of waveform fractal dimension</span>
<span class="sd"> algorithms. IEEE Transactions on Circuits and Systems I: Fundamental</span>
<span class="sd"> Theory and Applications, 48(2), 177-183.</span>

<span class="sd"> Paivinen, N. et al. (2005). Epileptic seizure detection: A nonlinear</span>
<span class="sd"> viewpoint. Computer methods and programs in biomedicine, 79(2), 151-159.</span>

<span class="sd"> Examples</span>
<span class="sd"> --------</span>
<span class="sd"> &gt;&gt;&gt; import numpy as np</span>
Expand Down Expand Up @@ -712,14 +738,14 @@ <h1>Source code for antropy.fractal</h1><div class="highlight"><pre>
<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> alpha : float</span>
<span class="sd"> the estimate alpha (:math:`\\alpha`) for the Hurst parameter.</span>
<span class="sd"> The estimated scaling exponent :math:`\\alpha` (related to the Hurst</span>
<span class="sd"> parameter).</span>

<span class="sd"> :math:`\\alpha &lt; 1`` indicates a</span>
<span class="sd"> stationary process similar to fractional Gaussian noise with</span>
<span class="sd"> :math:`H = \\alpha`.</span>
<span class="sd"> :math:`\\alpha &lt; 1` indicates a stationary process similar to</span>
<span class="sd"> fractional Gaussian noise with :math:`H = \\alpha`.</span>

<span class="sd"> :math:`\\alpha &gt; 1`` indicates a non-stationary process similar to</span>
<span class="sd"> fractional Brownian motion with :math:`H = \\alpha - 1`</span>
<span class="sd"> :math:`\\alpha &gt; 1` indicates a non-stationary process similar to</span>
<span class="sd"> fractional Brownian motion with :math:`H = \\alpha - 1`.</span>

<span class="sd"> Notes</span>
<span class="sd"> -----</span>
Expand All @@ -737,16 +763,16 @@ <h1>Source code for antropy.fractal</h1><div class="highlight"><pre>
<span class="sd"> where :math:`\\text{std}(X, k)` is the standard deviation of the process</span>
<span class="sd"> :math:`X` calculated over windows of size :math:`k`. In this equation,</span>
<span class="sd"> :math:`H` is called the Hurst parameter, which behaves indeed very similar</span>
<span class="sd"> to the Hurst exponant.</span>
<span class="sd"> to the Hurst exponent.</span>

<span class="sd"> For more details, please refer to the excellent documentation of the</span>
<span class="sd"> `nolds &lt;https://cschoel.github.io/nolds/&gt;`_</span>
<span class="sd"> Python package by Christopher Scholzel, from which this function is taken:</span>
<span class="sd"> https://cschoel.github.io/nolds/nolds.html#detrended-fluctuation-analysis</span>

<span class="sd"> Note that the default subseries size is set to</span>
<span class="sd"> entropy.utils._log_n(4, 0.1 * len(x), 1.2)). The current implementation</span>
<span class="sd"> does not allow to manually specify the subseries size or use overlapping</span>
<span class="sd"> Note that the subseries sizes range from 4 to 10% of the signal length,</span>
<span class="sd"> spaced geometrically by a factor of 1.2. The current implementation does</span>
<span class="sd"> not allow to manually specify the subseries sizes or use overlapping</span>
<span class="sd"> windows.</span>

<span class="sd"> The code is a faster (Numba) adaptation of the original code by Christopher</span>
Expand Down
6 changes: 4 additions & 2 deletions docs/build/html/generated/antropy.app_entropy.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -373,8 +373,10 @@ <h1>antropy.app_entropy<a class="headerlink" href="#antropy-app-entropy" title="
<a class="reference external" href="https://en.wikipedia.org/wiki/Chebyshev_distance">Chebyshev</a>
distance.</p>
</dd>
<dt><strong>Returns</strong></dt><dd></dd>
<dt><strong>——-</strong></dt><dd></dd>
</dl>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><dl class="simple">
<dt><strong>ae</strong><span class="classifier">float</span></dt><dd><p>Approximate Entropy.</p>
</dd>
</dl>
Expand Down
20 changes: 10 additions & 10 deletions docs/build/html/generated/antropy.detrended_fluctuation.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,12 +367,12 @@ <h1>antropy.detrended_fluctuation<a class="headerlink" href="#antropy-detrended-
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><dl>
<dt><strong>alpha</strong><span class="classifier">float</span></dt><dd><p>the estimate alpha (<span class="math notranslate nohighlight">\(\alpha\)</span>) for the Hurst parameter.</p>
<p><span class="math notranslate nohighlight">\(\alpha &lt; 1`\)</span> indicates a
stationary process similar to fractional Gaussian noise with
<span class="math notranslate nohighlight">\(H = \alpha\)</span>.</p>
<p><span class="math notranslate nohighlight">\(\alpha &gt; 1`\)</span> indicates a non-stationary process similar to
fractional Brownian motion with <span class="math notranslate nohighlight">\(H = \alpha - 1\)</span></p>
<dt><strong>alpha</strong><span class="classifier">float</span></dt><dd><p>The estimated scaling exponent <span class="math notranslate nohighlight">\(\alpha\)</span> (related to the Hurst
parameter).</p>
<p><span class="math notranslate nohighlight">\(\alpha &lt; 1\)</span> indicates a stationary process similar to
fractional Gaussian noise with <span class="math notranslate nohighlight">\(H = \alpha\)</span>.</p>
<p><span class="math notranslate nohighlight">\(\alpha &gt; 1\)</span> indicates a non-stationary process similar to
fractional Brownian motion with <span class="math notranslate nohighlight">\(H = \alpha - 1\)</span>.</p>
</dd>
</dl>
</dd>
Expand All @@ -389,14 +389,14 @@ <h1>antropy.detrended_fluctuation<a class="headerlink" href="#antropy-detrended-
<p>where <span class="math notranslate nohighlight">\(\text{std}(X, k)\)</span> is the standard deviation of the process
<span class="math notranslate nohighlight">\(X\)</span> calculated over windows of size <span class="math notranslate nohighlight">\(k\)</span>. In this equation,
<span class="math notranslate nohighlight">\(H\)</span> is called the Hurst parameter, which behaves indeed very similar
to the Hurst exponant.</p>
to the Hurst exponent.</p>
<p>For more details, please refer to the excellent documentation of the
<a class="reference external" href="https://cschoel.github.io/nolds/">nolds</a>
Python package by Christopher Scholzel, from which this function is taken:
<a class="reference external" href="https://cschoel.github.io/nolds/nolds.html#detrended-fluctuation-analysis">https://cschoel.github.io/nolds/nolds.html#detrended-fluctuation-analysis</a></p>
<p>Note that the default subseries size is set to
entropy.utils._log_n(4, 0.1 * len(x), 1.2)). The current implementation
does not allow to manually specify the subseries size or use overlapping
<p>Note that the subseries sizes range from 4 to 10% of the signal length,
spaced geometrically by a factor of 1.2. The current implementation does
not allow to manually specify the subseries sizes or use overlapping
windows.</p>
<p>The code is a faster (Numba) adaptation of the original code by Christopher
Scholzel.</p>
Expand Down
20 changes: 20 additions & 0 deletions docs/build/html/generated/antropy.higuchi_fd.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=fd10adb8"></script>
<script src="../_static/design-tabs.js?v=f930bc37"></script>
<script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'generated/antropy.higuchi_fd';</script>
<link rel="icon" href="../_static/antropy.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
Expand Down Expand Up @@ -374,13 +375,32 @@ <h1>antropy.higuchi_fd<a class="headerlink" href="#antropy-higuchi-fd" title="Li
</dd>
</dl>
<p class="rubric">Notes</p>
<p>For each interval <span class="math notranslate nohighlight">\(k\)</span> from 1 to <code class="docutils literal notranslate"><span class="pre">kmax</span></code>, <span class="math notranslate nohighlight">\(k\)</span> sub-series are
constructed from the signal <span class="math notranslate nohighlight">\(x\)</span> of length <span class="math notranslate nohighlight">\(N\)</span>. Letting
<span class="math notranslate nohighlight">\(N_m = \lfloor (N-m)/k \rfloor\)</span>, the normalised length for each
sub-series starting at <span class="math notranslate nohighlight">\(m\)</span> is:</p>
<div class="math notranslate nohighlight">
\[L_m(k) = \frac{N-1}{k^2 \cdot N_m}
\sum_{j=1}^{N_m - 1} |x_{m+jk} - x_{m+(j-1)k}|\]</div>
<p>and the average length across all <span class="math notranslate nohighlight">\(k\)</span> sub-series is:</p>
<div class="math notranslate nohighlight">
\[L(k) = \frac{1}{k} \sum_{m=1}^{k} L_m(k)\]</div>
<p>The fractal dimension is then estimated as the slope of the linear
regression of <span class="math notranslate nohighlight">\(\log L(k)\)</span> against <span class="math notranslate nohighlight">\(\log(1/k)\)</span>:</p>
<div class="math notranslate nohighlight">
\[\text{FD} = \frac{d \log L(k)}{d \log(1/k)}\]</div>
<p>Original code from the <a class="reference external" href="https://mne.tools/mne-features/">mne-features</a>
package by Jean-Baptiste Schiratti and Alexandre Gramfort.</p>
<p>This function uses Numba to speed up the computation.</p>
<p class="rubric">References</p>
<p>Higuchi, Tomoyuki. “Approach to an irregular time series on the
basis of the fractal theory.” Physica D: Nonlinear Phenomena 31.2
(1988): 277-283.</p>
<p>Esteller, R. et al. (2001). A comparison of waveform fractal dimension
algorithms. IEEE Transactions on Circuits and Systems I: Fundamental
Theory and Applications, 48(2), 177-183.</p>
<p>Paivinen, N. et al. (2005). Epileptic seizure detection: A nonlinear
viewpoint. Computer methods and programs in biomedicine, 79(2), 151-159.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">antropy</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">ant</span>
Expand Down
Loading