The permutation entropy of a signal :math:`x` is defined as:
- .. math:: H = -\\sum p(\\pi)\\log_2(\\pi)
+ .. math:: H = -\\sum p(\\pi)\\log_2 p(\\pi)
where the sum runs over all :math:`n!` permutations :math:`\\pi` of order
:math:`n`. This is the information contained in comparing :math:`n`
@@ -514,10 +514,12 @@ Source code for antropy.entropy
* ``'welch'`` : Welch periodogram (:py:func:`scipy.signal.welch`)
nperseg : int or None
Length of each FFT segment for Welch method.
- If None (default), uses scipy default of 256 samples.
+ If None (default), uses scipy's default (256 samples, or the length
+ of the signal if shorter).
normalize : bool
- If True, divide by log2(psd.size) to normalize the spectral entropy
- between 0 and 1. Otherwise, return the spectral entropy in bit.
+ If True, divide by log2(number of frequency bins) to normalize the
+ spectral entropy between 0 and 1. Otherwise, return the spectral
+ entropy in bit.
axis : int
The axis along which the entropy is calculated. Default is -1 (last).
@@ -629,8 +631,8 @@ Source code for antropy.entropy
delay : int
Time delay (lag). Default is 1.
normalize : bool
- If True, divide by log2(order!) to normalize the entropy between 0
- and 1. Otherwise, return the permutation entropy in bit.
+ If True, divide by log2(order) to normalize the entropy between 0
+ and 1. Otherwise, return the SVD entropy in bit.
Returns
-------
@@ -836,6 +838,7 @@ Source code for antropy.entropy
:py:class:`sklearn.neighbors.KDTree`. Default is to use the
`Chebyshev <https://en.wikipedia.org/wiki/Chebyshev_distance>`_
distance.
+
Returns
-------
ae : float
@@ -962,8 +965,8 @@ Source code for antropy.entropy
:math:`C(m + 1, r)` is the number of embedded vectors of length
:math:`m + 1` having a
`Chebyshev distance <https://en.wikipedia.org/wiki/Chebyshev_distance>`_
- inferior to :math:`r` and :math:`C(m, r)` is the number of embedded
- vectors of length :math:`m` having a Chebyshev distance inferior to
+ less than :math:`r` and :math:`C(m, r)` is the number of embedded
+ vectors of length :math:`m` having a Chebyshev distance less than
:math:`r`.
Note that if ``metric == 'chebyshev'`` and ``len(x) < 5000`` points,
@@ -1096,14 +1099,14 @@ Source code for antropy.entropy
[docs]
def lziv_complexity(sequence, normalize=False):
"""
- Lempel-Ziv (LZ) complexity of (binary) sequence.
+ Lempel-Ziv (LZ) complexity of a sequence.
.. versionadded:: 0.1.1
Parameters
----------
sequence : str or array
- A sequence of character, e.g. ``'1001111011000010'``,
+ A sequence of characters, e.g. ``'1001111011000010'``,
``[0, 1, 0, 1, 1]``, or ``'Hello World!'``.
normalize : bool
If ``True``, returns the normalized LZ (see Notes).
@@ -1119,7 +1122,7 @@ Source code for antropy.entropy
Notes
-----
LZ complexity is defined as the number of different substrings encountered
- as the sequence is viewed from begining to the end.
+ as the sequence is viewed from beginning to the end.
Although the raw LZ is an important complexity indicator, it is heavily
influenced by sequence length (longer sequence will result in higher LZ).
@@ -1220,7 +1223,7 @@ Source code for antropy.entropy
def num_zerocross(x, normalize=False, axis=-1):
"""Number of zero-crossings.
- .. versionadded: 0.1.3
+ .. versionadded:: 0.1.3
Parameters
----------
@@ -1309,7 +1312,7 @@ Source code for antropy.entropy
def hjorth_params(x, axis=-1):
"""Calculate Hjorth mobility and complexity on given axis.
- .. versionadded: 0.1.3
+ .. versionadded:: 0.1.3
Parameters
----------
@@ -1327,7 +1330,7 @@ Source code for antropy.entropy
-----
Hjorth Parameters are indicators of statistical properties used in signal
processing in the time domain introduced by Bo Hjorth in 1970. The
- parameters are activity, mobility, and complexity. EntroPy only returns the
+ parameters are activity, mobility, and complexity. AntroPy only returns the
mobility and complexity parameters, since activity is simply the variance
of :math:`x`, which can be computed easily with :py:func:`numpy.var`.
diff --git a/docs/build/html/_modules/antropy/fractal.html b/docs/build/html/_modules/antropy/fractal.html
index d35ecf1..2243613 100644
--- a/docs/build/html/_modules/antropy/fractal.html
+++ b/docs/build/html/_modules/antropy/fractal.html
@@ -603,6 +603,25 @@ Source code for antropy.fractal
Notes
-----
+ For each interval :math:`k` from 1 to ``kmax``, :math:`k` sub-series are
+ constructed from the signal :math:`x` of length :math:`N`. Letting
+ :math:`N_m = \\lfloor (N-m)/k \\rfloor`, the normalised length for each
+ sub-series starting at :math:`m` is:
+
+ .. math::
+
+ 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}|
+
+ and the average length across all :math:`k` sub-series is:
+
+ .. math:: L(k) = \\frac{1}{k} \\sum_{m=1}^{k} L_m(k)
+
+ The fractal dimension is then estimated as the slope of the linear
+ regression of :math:`\\log L(k)` against :math:`\\log(1/k)`:
+
+ .. math:: \\text{FD} = \\frac{d \\log L(k)}{d \\log(1/k)}
+
Original code from the `mne-features <https://mne.tools/mne-features/>`_
package by Jean-Baptiste Schiratti and Alexandre Gramfort.
@@ -614,6 +633,13 @@ Source code for antropy.fractal
basis of the fractal theory." Physica D: Nonlinear Phenomena 31.2
(1988): 277-283.
+ 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.
+
+ Paivinen, N. et al. (2005). Epileptic seizure detection: A nonlinear
+ viewpoint. Computer methods and programs in biomedicine, 79(2), 151-159.
+
Examples
--------
>>> import numpy as np
@@ -712,14 +738,14 @@ Source code for antropy.fractal
Returns
-------
alpha : float
- the estimate alpha (:math:`\\alpha`) for the Hurst parameter.
+ The estimated scaling exponent :math:`\\alpha` (related to the Hurst
+ parameter).
- :math:`\\alpha < 1`` indicates a
- stationary process similar to fractional Gaussian noise with
- :math:`H = \\alpha`.
+ :math:`\\alpha < 1` indicates a stationary process similar to
+ fractional Gaussian noise with :math:`H = \\alpha`.
- :math:`\\alpha > 1`` indicates a non-stationary process similar to
- fractional Brownian motion with :math:`H = \\alpha - 1`
+ :math:`\\alpha > 1` indicates a non-stationary process similar to
+ fractional Brownian motion with :math:`H = \\alpha - 1`.
Notes
-----
@@ -737,16 +763,16 @@ Source code for antropy.fractal
where :math:`\\text{std}(X, k)` is the standard deviation of the process
:math:`X` calculated over windows of size :math:`k`. In this equation,
:math:`H` is called the Hurst parameter, which behaves indeed very similar
- to the Hurst exponant.
+ to the Hurst exponent.
For more details, please refer to the excellent documentation of the
`nolds <https://cschoel.github.io/nolds/>`_
Python package by Christopher Scholzel, from which this function is taken:
https://cschoel.github.io/nolds/nolds.html#detrended-fluctuation-analysis
- 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
+ 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.
The code is a faster (Numba) adaptation of the original code by Christopher
diff --git a/docs/build/html/generated/antropy.app_entropy.html b/docs/build/html/generated/antropy.app_entropy.html
index 0993567..8e7e07c 100644
--- a/docs/build/html/generated/antropy.app_entropy.html
+++ b/docs/build/html/generated/antropy.app_entropy.html
@@ -373,8 +373,10 @@ antropy.app_entropyChebyshev
distance.
-Returns
-——-
+
+
+Returns:
+
- aefloat
Approximate Entropy.
diff --git a/docs/build/html/generated/antropy.detrended_fluctuation.html b/docs/build/html/generated/antropy.detrended_fluctuation.html
index 17898ba..0a4bb3d 100644
--- a/docs/build/html/generated/antropy.detrended_fluctuation.html
+++ b/docs/build/html/generated/antropy.detrended_fluctuation.html
@@ -367,12 +367,12 @@ antropy.detrended_fluctuationReturns:
-- alphafloat
the estimate alpha (\(\alpha\)) for the Hurst parameter.
-\(\alpha < 1`\) indicates a
-stationary process similar to fractional Gaussian noise with
-\(H = \alpha\).
-\(\alpha > 1`\) indicates a non-stationary process similar to
-fractional Brownian motion with \(H = \alpha - 1\)
+- alphafloat
The estimated scaling exponent \(\alpha\) (related to the Hurst
+parameter).
+\(\alpha < 1\) indicates a stationary process similar to
+fractional Gaussian noise with \(H = \alpha\).
+\(\alpha > 1\) indicates a non-stationary process similar to
+fractional Brownian motion with \(H = \alpha - 1\).
antropy.detrended_fluctuation\(\text{std}(X, k)\) is the standard deviation of the process
\(X\) calculated over windows of size \(k\). In this equation,
\(H\) is called the Hurst parameter, which behaves indeed very similar
-to the Hurst exponant.
+to the Hurst exponent.
For more details, please refer to the excellent documentation of the
nolds
Python package by Christopher Scholzel, from which this function is taken:
https://cschoel.github.io/nolds/nolds.html#detrended-fluctuation-analysis
-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
+
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.
The code is a faster (Numba) adaptation of the original code by Christopher
Scholzel.
diff --git a/docs/build/html/generated/antropy.higuchi_fd.html b/docs/build/html/generated/antropy.higuchi_fd.html
index 366e435..e63d6c9 100644
--- a/docs/build/html/generated/antropy.higuchi_fd.html
+++ b/docs/build/html/generated/antropy.higuchi_fd.html
@@ -46,6 +46,7 @@
+
@@ -374,6 +375,20 @@ antropy.higuchi_fdNotes
+For each interval \(k\) from 1 to kmax, \(k\) sub-series are
+constructed from the signal \(x\) of length \(N\). Letting
+\(N_m = \lfloor (N-m)/k \rfloor\), the normalised length for each
+sub-series starting at \(m\) is:
+
+\[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}|\]
+and the average length across all \(k\) sub-series is:
+
+\[L(k) = \frac{1}{k} \sum_{m=1}^{k} L_m(k)\]
+The fractal dimension is then estimated as the slope of the linear
+regression of \(\log L(k)\) against \(\log(1/k)\):
+
+\[\text{FD} = \frac{d \log L(k)}{d \log(1/k)}\]
Original code from the mne-features
package by Jean-Baptiste Schiratti and Alexandre Gramfort.
This function uses Numba to speed up the computation.
@@ -381,6 +396,11 @@ antropy.higuchi_fdExamples
>>> import numpy as np
>>> import antropy as ant
diff --git a/docs/build/html/generated/antropy.hjorth_params.html b/docs/build/html/generated/antropy.hjorth_params.html
index a2d6c53..a7ad371 100644
--- a/docs/build/html/generated/antropy.hjorth_params.html
+++ b/docs/build/html/generated/antropy.hjorth_params.html
@@ -358,6 +358,9 @@ antropy.hjorth_params
antropy.hjorth_params(x, axis=-1)[source]#
Calculate Hjorth mobility and complexity on given axis.
+
+Added in version 0.1.3.
+
- Parameters:
@@ -377,7 +380,7 @@ antropy.hjorth_paramsNotes
Hjorth Parameters are indicators of statistical properties used in signal
processing in the time domain introduced by Bo Hjorth in 1970. The
-parameters are activity, mobility, and complexity. EntroPy only returns the
+parameters are activity, mobility, and complexity. AntroPy only returns the
mobility and complexity parameters, since activity is simply the variance
of \(x\), which can be computed easily with numpy.var().
The mobility parameter represents the mean frequency or the proportion
diff --git a/docs/build/html/generated/antropy.lziv_complexity.html b/docs/build/html/generated/antropy.lziv_complexity.html
index 6e8c47b..3c58a05 100644
--- a/docs/build/html/generated/antropy.lziv_complexity.html
+++ b/docs/build/html/generated/antropy.lziv_complexity.html
@@ -357,14 +357,14 @@
antropy.lziv_complexity
-
antropy.lziv_complexity(sequence, normalize=False)[source]#
-Lempel-Ziv (LZ) complexity of (binary) sequence.
+Lempel-Ziv (LZ) complexity of a sequence.
Added in version 0.1.1.
- Parameters:
-- sequencestr or array
A sequence of character, e.g. '1001111011000010',
+
- sequencestr or array
A sequence of characters, e.g. '1001111011000010',
[0, 1, 0, 1, 1], or 'Hello World!'.
- normalizebool
If True, returns the normalized LZ (see Notes).
@@ -383,7 +383,7 @@ antropy.lziv_complexity
Notes
LZ complexity is defined as the number of different substrings encountered
-as the sequence is viewed from begining to the end.
+as the sequence is viewed from beginning to the end.
Although the raw LZ is an important complexity indicator, it is heavily
influenced by sequence length (longer sequence will result in higher LZ).
Zhang and colleagues (2009) have therefore proposed the normalized LZ,
diff --git a/docs/build/html/generated/antropy.num_zerocross.html b/docs/build/html/generated/antropy.num_zerocross.html
index e8d4afe..b39b621 100644
--- a/docs/build/html/generated/antropy.num_zerocross.html
+++ b/docs/build/html/generated/antropy.num_zerocross.html
@@ -357,6 +357,9 @@
antropy.num_zerocross
antropy.num_zerocross(x, normalize=False, axis=-1)[source]#
Number of zero-crossings.
+
+Added in version 0.1.3.
+
- Parameters:
diff --git a/docs/build/html/generated/antropy.perm_entropy.html b/docs/build/html/generated/antropy.perm_entropy.html
index 8a92ab6..542a113 100644
--- a/docs/build/html/generated/antropy.perm_entropy.html
+++ b/docs/build/html/generated/antropy.perm_entropy.html
@@ -386,7 +386,7 @@ antropy.perm_entropy
The permutation entropy of a signal \(x\) is defined as:
-\[H = -\sum p(\pi)\log_2(\pi)\]
+\[H = -\sum p(\pi)\log_2 p(\pi)\]
where the sum runs over all \(n!\) permutations \(\pi\) of order
\(n\). This is the information contained in comparing \(n\)
consecutive values of the time series. It is clear that
diff --git a/docs/build/html/generated/antropy.sample_entropy.html b/docs/build/html/generated/antropy.sample_entropy.html
index 0793981..5ec2da8 100644
--- a/docs/build/html/generated/antropy.sample_entropy.html
+++ b/docs/build/html/generated/antropy.sample_entropy.html
@@ -396,8 +396,8 @@
antropy.sample_entropy\(C(m + 1, r)\) is the number of embedded vectors of length
\(m + 1\) having a
Chebyshev distance
-inferior to \(r\) and \(C(m, r)\) is the number of embedded
-vectors of length \(m\) having a Chebyshev distance inferior to
+less than \(r\) and \(C(m, r)\) is the number of embedded
+vectors of length \(m\) having a Chebyshev distance less than
\(r\).
Note that if metric == 'chebyshev' and len(x) < 5000 points,
then the sample entropy is computed using a fast custom Numba script.
diff --git a/docs/build/html/generated/antropy.spectral_entropy.html b/docs/build/html/generated/antropy.spectral_entropy.html
index 4be4323..0943f93 100644
--- a/docs/build/html/generated/antropy.spectral_entropy.html
+++ b/docs/build/html/generated/antropy.spectral_entropy.html
@@ -372,10 +372,12 @@
antropy.spectral_entropyint or NoneLength of each FFT segment for Welch method.
-If None (default), uses scipy default of 256 samples.
+If None (default), uses scipy’s default (256 samples, or the length
+of the signal if shorter).
normalizebool If True, divide by log2(psd.size) to normalize the spectral entropy
-between 0 and 1. Otherwise, return the spectral entropy in bit.
+normalizebool If True, divide by log2(number of frequency bins) to normalize the
+spectral entropy between 0 and 1. Otherwise, return the spectral
+entropy in bit.
axisint The axis along which the entropy is calculated. Default is -1 (last).
antropy.svd_entropyintTime delay (lag). Default is 1.
normalizebool If True, divide by log2(order!) to normalize the entropy between 0
-and 1. Otherwise, return the permutation entropy in bit.
+normalizebool If True, divide by log2(order) to normalize the entropy between 0
+and 1. Otherwise, return the SVD entropy in bit.
`_
distance.
+
Returns
-------
ae : float
@@ -599,8 +602,8 @@ def sample_entropy(x, order=2, tolerance=None, metric="chebyshev"):
:math:`C(m + 1, r)` is the number of embedded vectors of length
:math:`m + 1` having a
`Chebyshev distance `_
- inferior to :math:`r` and :math:`C(m, r)` is the number of embedded
- vectors of length :math:`m` having a Chebyshev distance inferior to
+ less than :math:`r` and :math:`C(m, r)` is the number of embedded
+ vectors of length :math:`m` having a Chebyshev distance less than
:math:`r`.
Note that if ``metric == 'chebyshev'`` and ``len(x) < 5000`` points,
@@ -730,14 +733,14 @@ def _lz_complexity(binary_string):
def lziv_complexity(sequence, normalize=False):
"""
- Lempel-Ziv (LZ) complexity of (binary) sequence.
+ Lempel-Ziv (LZ) complexity of a sequence.
.. versionadded:: 0.1.1
Parameters
----------
sequence : str or array
- A sequence of character, e.g. ``'1001111011000010'``,
+ A sequence of characters, e.g. ``'1001111011000010'``,
``[0, 1, 0, 1, 1]``, or ``'Hello World!'``.
normalize : bool
If ``True``, returns the normalized LZ (see Notes).
@@ -753,7 +756,7 @@ def lziv_complexity(sequence, normalize=False):
Notes
-----
LZ complexity is defined as the number of different substrings encountered
- as the sequence is viewed from begining to the end.
+ as the sequence is viewed from beginning to the end.
Although the raw LZ is an important complexity indicator, it is heavily
influenced by sequence length (longer sequence will result in higher LZ).
@@ -851,7 +854,7 @@ def lziv_complexity(sequence, normalize=False):
def num_zerocross(x, normalize=False, axis=-1):
"""Number of zero-crossings.
- .. versionadded: 0.1.3
+ .. versionadded:: 0.1.3
Parameters
----------
@@ -937,7 +940,7 @@ def num_zerocross(x, normalize=False, axis=-1):
def hjorth_params(x, axis=-1):
"""Calculate Hjorth mobility and complexity on given axis.
- .. versionadded: 0.1.3
+ .. versionadded:: 0.1.3
Parameters
----------
@@ -955,7 +958,7 @@ def hjorth_params(x, axis=-1):
-----
Hjorth Parameters are indicators of statistical properties used in signal
processing in the time domain introduced by Bo Hjorth in 1970. The
- parameters are activity, mobility, and complexity. EntroPy only returns the
+ parameters are activity, mobility, and complexity. AntroPy only returns the
mobility and complexity parameters, since activity is simply the variance
of :math:`x`, which can be computed easily with :py:func:`numpy.var`.
diff --git a/src/antropy/fractal.py b/src/antropy/fractal.py
index 8cd6e99..67e14e9 100644
--- a/src/antropy/fractal.py
+++ b/src/antropy/fractal.py
@@ -246,6 +246,25 @@ def higuchi_fd(x, kmax=10):
Notes
-----
+ For each interval :math:`k` from 1 to ``kmax``, :math:`k` sub-series are
+ constructed from the signal :math:`x` of length :math:`N`. Letting
+ :math:`N_m = \\lfloor (N-m)/k \\rfloor`, the normalised length for each
+ sub-series starting at :math:`m` is:
+
+ .. math::
+
+ 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}|
+
+ and the average length across all :math:`k` sub-series is:
+
+ .. math:: L(k) = \\frac{1}{k} \\sum_{m=1}^{k} L_m(k)
+
+ The fractal dimension is then estimated as the slope of the linear
+ regression of :math:`\\log L(k)` against :math:`\\log(1/k)`:
+
+ .. math:: \\text{FD} = \\frac{d \\log L(k)}{d \\log(1/k)}
+
Original code from the `mne-features