antropy.perm_entropy

antropy.perm_entropy(x, order=3, delay=1, normalize=False)

Permutation Entropy.

Parameters:

xlist or np.array

One-dimensional time series of shape (n_times,), or a two-dimensional array of shape (n_epochs, n_times). 2D input is only supported for order=3 or order=4.

orderint

Order of permutation entropy. Default is 3.

delayint, list, np.ndarray or range

Time delay (lag). Default is 1. If multiple values are passed (e.g. [1, 2, 3]), AntroPy will calculate the average permutation entropy across all these delays.

normalizebool

If True, divide by log2(order!) to normalize the entropy between 0 and 1. Otherwise, return the permutation entropy in bits.

Returns:

pefloat or np.array

Permutation entropy. Returns a scalar for 1D input, or an array of shape (n_epochs,) for 2D input.

Notes

The permutation entropy is a complexity measure for time-series first introduced by Bandt and Pompe in 2002.

The permutation entropy of a signal \(x\) is defined as:

\[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 \(0 ≤ H (n) ≤ \log_2(n!)\) where the lower bound is attained for an increasing or decreasing sequence of values, and the upper bound for a completely random system where all \(n!\) possible permutations appear with the same probability.

The embedded matrix \(Y\) is created by:

\[y(i)=[x_i,x_{i+\text{delay}}, ...,x_{i+(\text{order}-1) * \text{delay}}]\]

\[Y=[y(1),y(2),...,y(N-(\text{order}-1))*\text{delay})]^T\]

For order ∈ {3, 4}, a fast vectorised path based on lookup tables is used instead of argsort, giving a 1.5–5× speed-up for 1D input and 2–6× for 2D input. Higher orders fall back to a standard argsort implementation (1D only).

References

Bandt, Christoph, and Bernd Pompe. “Permutation entropy: a natural complexity measure for time series.” Physical review letters 88.17 (2002): 174102.

Examples

Permutation entropy with order 2:

>>> import numpy as np
>>> import antropy as ant
>>> x = [4, 7, 9, 10, 6, 11, 3]
>>> # Returns a value in bits, between 0 and log2(factorial(order))
>>> print(f"{ant.perm_entropy(x, order=2):.4f}")
0.9183

Normalized permutation entropy with order 3:

>>> # Returns a value between 0 and 1.
>>> print(f"{ant.perm_entropy(x, normalize=True):.4f}")
0.5888

Average across multiple delays:

>>> rng = np.random.default_rng(seed=42)
>>> x = rng.random(1000)
>>> print(f"{ant.perm_entropy(x, delay=[1, 2, 3], normalize=True):.4f}")
0.9996

Pure sine wave (low entropy):

>>> x = np.sin(2 * np.pi * 1 * np.arange(3000) / 100)
>>> print(f"{ant.perm_entropy(x, normalize=True):.4f}")
0.4441

Linearly-increasing time-series (minimum entropy):

>>> x = np.arange(1000)
>>> print(f"{ant.perm_entropy(x, normalize=True):.4f}")
0.0000

2D input — vectorized permutation entropy (only supported for order=3 or order=4):

>>> rng = np.random.default_rng(seed=42)
>>> x2d = rng.random((4, 1000))
>>> pe = ant.perm_entropy(x2d, order=3, normalize=True)
>>> pe.shape
(4,)
>>> print(np.round(pe, 4))
[0.9997 0.9991 0.9988 0.9988]