complexeva

Complexity measures for 1D time series, implemented with NumPy, SciPy and Numba.

install

pip install complexeva

Requires Python 3.14 or later.

example

import numpy as np
import complexeva

x = np.random.default_rng(0).standard_normal(2000)  # white noise

complexeva.hfd(x)                          # about 2.0
complexeva.lempel_ziv(x, normalize=True)   # about 1.0
complexeva.compression_complexity(x)       # about 0.96
complexeva.lyapunov_exponent(x)            # largest Lyapunov exponent

measures

All functions take a 1D array. The new entropy and DFA functions require finite, real values. Sample entropy uses a strict distance threshold: a constant series has NaN at its default zero tolerance, or 0 with a positive tolerance. DFA returns NaN for a constant series; its default scales require at least 58 samples. Report the template/delay/tolerance or fitted window sizes with results. The new measures are checked against antropy/nolds, which are not runtime or test dependencies. Results changed in 0.3.0; see CHANGELOG.md.

how it is fast

Loops run in Numba-compiled kernels (plain Python is 100–400× slower), and each measure uses a cheaper exact algorithm, so results agree with 0.3.0 to rounding.

Each cell is the other package's median time (A) or peak heap (B) divided by complexeva's, after compilation, on one thread (Apple M4 Max, Python 3.14; antropy 0.2.3, nolds 0.6.3, neurokit2 0.2.13, EntropyHub 2.0, pyentrp 2.3.0, ordpy 1.2.3, fathon 1.4.0). complexeva is faster in every cell. Lempel–Ziv uses more heap than antropy, about 32 bytes per sample, in exchange for linear time.

Sample entropy: a dual k-d tree skips or counts whole box pairs (N = 1e5: 8.8 s → 0.14 s).

Permutation entropy: one pass counts Lehmer codes in a fixed histogram (N = 1e5: 55 ms → 0.12 ms).

Lempel–Ziv: a suffix automaton takes one step per symbol (N = 1e6: 51 ms; antropy 132 s), at about 32 bytes per sample.

Lyapunov exponent: a sorted scan skips blocks inside the Theiler window (monotone, N = 1e5: 6.0 s → 0.13 s).

DFA: all window sizes in one compiled call (N = 1000: 105 µs → 48 µs).

Higuchi FD: compiled slope fit and an in-place Hilbert envelope (N = 300: 3.6× faster).

The first call compiles the kernels (about 2 s); later runs load them from the cache. In a read-only installation, set NUMBA_CACHE_DIR to a writable directory.

synthetic-data checks

For fractional Brownian motion (fBm), the theoretical graph dimension is D = 2 − H. HFD tracks this relation without rescaling its output. Each point below uses 32 independently sampled paths of 8,192 samples, with k_max=10; error bars show ±1 standard deviation across paths, not a confidence interval. The paths use circulant embedding of fractional Gaussian noise, followed by a cumulative sum.

With the same sample length and median binarization, normalized Lempel–Ziv complexity is low for a periodic sine wave and close to 1 for Gaussian white noise. The noise bar summarizes 32 trials; the sine wave has period 128 samples. The dashed line is the asymptotic random-sequence limit, not an upper bound. These are finite-sample sanity checks, not guarantees for every signal or parameter.

Regenerate both figures from a repository checkout (fixed RNG seed 0):

python -m pip install -e . matplotlib
python examples/validate.py

The script writes small, headless PNGs to docs/figures/; use --output-dir PATH to write them elsewhere. Matplotlib is only needed for these plots, not to use the package.

licence

MIT