Skip to main content

https://badge.fury.io/py/antropy.svg https://img.shields.io/conda/vn/conda-forge/antropy.svg https://img.shields.io/github/license/raphaelvallat/antropy.svg https://github.com/raphaelvallat/antropy/actions/workflows/python_tests.yml/badge.svg https://codecov.io/gh/raphaelvallat/antropy/branch/master/graph/badge.svg https://static.pepy.tech/badge/antropy Ruff
https://raw.githubusercontent.com/raphaelvallat/antropy/master/docs/pictures/logo.png

AntroPy is a Python package for computing entropy and fractal dimension measures of time-series. It is designed for speed (Numba JIT compilation) and ease of use, and works on both 1-D and N-D arrays. Typical use cases include feature extraction from physiological signals (e.g. EEG, ECG, EMG), and signal processing research.


Functions

Entropy

Function

Description

ant.perm_entropy

Permutation entropy — captures ordinal patterns in the signal.

ant.spectral_entropy

Spectral (power-spectrum) entropy via FFT or Welch method.

ant.svd_entropy

Singular value decomposition entropy of the time-delay embedding matrix.

ant.app_entropy

Approximate entropy (ApEn) — regularity measure sensitive to the length of the signal.

ant.sample_entropy

Sample entropy (SampEn) — less biased alternative to ApEn.

ant.lziv_complexity

Lempel-Ziv complexity for symbolic / binary sequences.

ant.num_zerocross

Number of zero-crossings.

ant.hjorth_params

Hjorth mobility and complexity parameters.

Fractal dimension

Function

Description

ant.petrosian_fd

Petrosian fractal dimension.

ant.katz_fd

Katz fractal dimension.

ant.higuchi_fd

Higuchi fractal dimension — slope of log curve-length vs log interval.

ant.detrended_fluctuation

Detrended fluctuation analysis (DFA) — estimates the Hurst / scaling exponent.


Installation

AntroPy requires Python 3.10+ and depends on NumPy (≥ 1.22.4), SciPy (≥ 1.8.0), scikit-learn (≥ 1.2.0), and Numba (≥ 0.57).

# pip
pip install antropy

# uv
uv pip install antropy

# conda
conda install -c conda-forge antropy

Development installation

git clone https://github.com/raphaelvallat/antropy.git
cd antropy
uv pip install --group=test --editable .
pytest --verbose

Quick start

Entropy measures

import numpy as np
import antropy as ant

np.random.seed(1234567)
x = np.random.normal(size=3000)

print(ant.perm_entropy(x, normalize=True))
print(ant.spectral_entropy(x, sf=100, method='welch', normalize=True))
print(ant.svd_entropy(x, normalize=True))
print(ant.app_entropy(x))
print(ant.sample_entropy(x))
print(ant.hjorth_params(x))             # mobility in samples⁻¹
print(ant.hjorth_params(x, sf=100))     # mobility in Hz
print(ant.num_zerocross(x))
print(ant.lziv_complexity('01111000011001', normalize=True))
0.9995              # perm_entropy        (0 = regular, 1 = random)
0.9941              # spectral_entropy     (0 = pure tone, 1 = white noise)
0.9999              # svd_entropy
2.0152              # app_entropy
2.1986              # sample_entropy
(1.4313, 1.2153)    # hjorth (mobility, complexity)
(143.1339, 1.2153)  # hjorth with sf=100 Hz
1531                # num_zerocross
1.3598              # lziv_complexity (normalized)

Fractal dimension

print(ant.petrosian_fd(x))
print(ant.katz_fd(x))
print(ant.higuchi_fd(x))
print(ant.detrended_fluctuation(x))
1.0311    # petrosian_fd
5.9543    # katz_fd
2.0037    # higuchi_fd   (≈ 2 for white noise)
0.4790    # DFA alpha    (≈ 0.5 for white noise)

N-D arrays

Some functions accept N-D arrays and an axis argument, making it easy to process multi-channel data in a single call:

import numpy as np
import antropy as ant

# 4 channels × 3000 samples
X = np.random.normal(size=(4, 3000))

pe   = ant.perm_entropy(X, normalize=True, axis=-1)          # shape (4,)
mob, com = ant.hjorth_params(X, sf=256, axis=-1)             # shape (4,) each
nzc  = ant.num_zerocross(X, normalize=True, axis=-1)         # shape (4,)
se   = ant.spectral_entropy(X, sf=256, normalize=True)       # shape (4,)

Performance

Benchmarks on a MacBook Pro M1 Max (2021):

Function

1 000 samples

10 000 samples

Complexity

ant.perm_entropy

24 µs

87 µs

O(n) ¹

ant.spectral_entropy

141 µs

863 µs

O(n log n) ⁴

ant.svd_entropy

35 µs

140 µs

O(n·m²) ²

ant.app_entropy

1.5 ms

45.9 ms

O(n²) worst ⁵

ant.sample_entropy

917 µs

46.0 ms

O(n²) worst ⁵

ant.lziv_complexity

241 µs

25.2 ms

O(n²/log n)

ant.num_zerocross

2.5 µs

6 µs

O(n)

ant.hjorth_params

19 µs

44 µs

O(n)

ant.petrosian_fd

6 µs

14 µs

O(n)

ant.katz_fd

9 µs

22 µs

O(n)

ant.higuchi_fd

7 µs

92 µs

O(n·kmax) ³

ant.detrended_fluctuation

99 µs

1.4 ms

O(n log n)

¹ perm_entropy: O(n) for order ∈ {3, 4} (default), O(n·m·log m) for order > 4. ² svd_entropy: m = order (default 3). ³ higuchi_fd: kmax = max interval (default 10). ⁴ spectral_entropy: O(n log n) for FFT method, O(n) for Welch with fixed nperseg (default). ⁵ app_entropy / sample_entropy: O(n²) worst case, empirically ~O(n^1.5) via KDTree average case.

Numba functions (sample_entropy, higuchi_fd, detrended_fluctuation) incur a one-time compilation cost on the first call.


Contributing

AntroPy was created and is maintained by Raphael Vallat. Contributions are welcome — feel free to open an issue or submit a pull request on GitHub.

Note: this program is provided with NO WARRANTY OF ANY KIND. Always validate results against known references.


Acknowledgements

Several functions in AntroPy were adapted from:

Metadata

Release files for antropy 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for antropy 0.2.3
File Size Uploaded Provenance Actions
antropy-0.2.3.tar.gz 31.5 kB Without provenance Details for antropy-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for antropy 0.2.3
File Interpreter ABI Platform Actions
antropy-0.2.3-py3-none-any.whl Python 3 none any Details for antropy-0.2.3-py3-none-any.whl

Total release size: 55.2 kB

Release files / antropy-0.2.3.tar.gz

Download URL antropy-0.2.3.tar.gz
Size 31.5 kB
Tags Source
SHA-256 checksum
How to use checksums
75827535384caa3a04d962d0a0808dcde6f84e8f8746c7df0d6a6b75e964aca8
BLAKE2b-256 checksum
How to use checksums
b953929eebfb55b42f1ae73874cd934b4078d9b7ed70477032cf8d9347866a79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.11

Release files / antropy-0.2.3-py3-none-any.whl

Download URL antropy-0.2.3-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e814537e7c9a26c67e583b40299e45ab87c9cef5d44ad2c9fe716bfe6265365f
BLAKE2b-256 checksum
How to use checksums
e7879f37d292c0a5a9af0eb784afad56a20f7c10f7ecd43d4074bedd02ca3f99
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.11

Security for antropy 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page