DOCSEARCHbyAlgolia
Submit Docs

AntroPy

repository·master·Indexed 18 days ago

https://github.com/raphaelvallat/antropy

A high-performance Python package for computing entropy and fractal dimension measures of time-series data. Optimized with Numba JIT compilation, it supports 1-D and N-D arrays for physiological signal processing (EEG, ECG, EMG). Key features include functions for Permutation, Spectral, SVD, Approximate, and Sample entropy, as well as Lempel-Ziv complexity, Hjorth parameters, and fractal dimension estimates such as Higuchi, Katz, Petrosian, and Detrended Fluctuation Analysis (DFA).

Tokens
6.3K
Snippets
22
Records
24
Agent score
61%

What's inside antropy

  1. Process multi-channel data with N-D arrays

    master

    Many AntroPy functions accept N-D arrays and an axis argument, allowing you to process multi-channel data (e.g., EEG/ECG) in a single call. Specify the axis along which the time-series is defined (commonly axis=-1).

    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
zc   = ant.num_zerocross(X, normalize=True, axis=-1)         # shape (4,)
se   = ant.spectral_entropy(X, sf=256, normalize=True)       # shape (4,)

  2. Process multi-channel N-D arrays

    master

    Many AntroPy functions accept N-D arrays and an axis argument, allowing you to process multi-channel data (e.g., EEG/ECG) in a single call. For example, if your data shape is (channels, samples), use axis=-1 to compute measures for each channel.

    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
zc  = ant.num_zerocross(X, normalize=True, axis=-1)         # shape (4,)
se   = ant.spectral_entropy(X, sf=256, normalize=True)       # shape (4,)

  3. Install AntroPy for development

    master

    To install AntroPy in an editable mode for development, clone the repository and use uv to install the test group dependencies.

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

  4. Install AntroPy

    master

    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).

    You can install it using pip, uv, or conda.

    # pip
pip install antropy

# uv
uv pip install antropy

# conda
conda install -c conda-forge antropy

  5. Available entropy functions in AntroPy

    master

    AntroPy provides several functions to calculate different types of entropy for signal analysis. The available functions are:

    • app_entropy: Approximate entropy.
    • hjorth_params: Hjorth parameters (activity, mobility, and complexity).
    • lziv_complexity: Lempel-Ziv complexity.
    • num_zerocross: Number of zero crossings.
    • perm_entropy: Permutation entropy.
    • sample_entropy: Sample entropy.
    • spectral_entropy: Spectral entropy.
    • svd_entropy: Singular Value Decomposition (SVD) entropy.

  6. Compute entropy measures

    master

    AntroPy provides several functions to compute different types of entropy for time-series signals:

    • ant.perm_entropy: Permutation entropy (captures ordinal patterns).
    • 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).
    • ant.sample_entropy: Sample entropy (SampEn).
    • 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.
    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))

  7. Compute fractal dimension measures

    master

    AntroPy provides functions to estimate fractal dimensions and scaling exponents:

    • 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) to estimate the Hurst/scaling exponent.
    import numpy as np
import antropy as ant

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

print(ant.petrosian_fd(x))
print(ant.katz_fd(x))
print(ant.higuchi_fd(x))
print(ant.detrended_fluctuation(x))

  8. Available fractal dimension functions in AntroPy

    master

    AntroPy provides several methods to estimate the fractal dimension of a signal. The available functions are:

    • detrended_fluctuation: Detrended Fluctuation Analysis (DFA).
    • higuchi_fd: Higuchi fractal dimension.
    • katz_fd: Katz fractal dimension.
    • petrosian_fd: Petrosian fractal dimension.

  9. Compute entropy and fractal dimension metrics on signals

    master

    You can use antropy to compute various complexity measures including entropy (Permutation, SVD, Spectral, Approximate, Sample) and fractal dimension (Petrosian, Katz, Higuchi) on time-series data. For Detrended Fluctuation Analysis (DFA), use detrended_fluctuation.

    Most entropy functions support an order parameter (for permutation/approximate/sample entropy) and a normalize parameter. spectral_entropy additionally requires the sampling frequency sf.

    import antropy as ant
import numpy as np

signal = np.random.rand(1000)
sf = 100

# Entropy metrics
perm = ant.perm_entropy(signal, order=3, normalize=True)
svd = ant.svd_entropy(signal, order=3, normalize=True)
spec = ant.spectral_entropy(signal, sf, normalize=True)
app = ant.app_entropy(signal, order=2)
sample = ant.sample_entropy(signal, order=2)

# Fractal dimension metrics
petrosian = ant.petrosian_fd(signal)
katz = ant.katz_fd(signal)
higuchi = ant.higuchi_fd(signal)

# Detrended Fluctuation Analysis
dfa = ant.detrended_fluctuation(signal)

  10. Compute entropy and fractal dimension metrics on time-series

    master

    You can use antropy to compute various complexity metrics including permutation entropy, spectral entropy, approximate entropy, sample entropy, and several fractal dimension (FD) measures.

    Commonly used functions include:

    • perm_entropy(x, order=..., normalize=...): Permutation entropy.
    • svd_entropy(x, order=..., normalize=...): Singular value decomposition entropy.
    • spectral_entropy(x, sf, normalize=..., method='welch', nperseg=...): Spectral entropy.
    • app_entropy(x, order=...): Approximate entropy.
    • sample_entropy(x, order=...): Sample entropy.
    • petrosian_fd(x): Petrosian fractal dimension.
    • katz_fd(x): Katz fractal dimension.
    • higuchi_fd(x): Higuchi fractal dimension.
    • detrended_fluctuation(x): Detrended fluctuation analysis (DFA).
    import antropy as ant
import numpy as np

# Example time-series
ts = np.random.rand(1000)

# Compute metrics
metrics = {
    "PermEnt": ant.perm_entropy(ts, order=3, normalize=True),
    "SVDEnt": ant.svd_entropy(ts, order=3, normalize=True),
    "SpecEnt": ant.spectral_entropy(ts, sf=10, normalize=True, method="welch", nperseg=50),
    "AppEnt": ant.app_entropy(ts, order=2),
    "SampleEnt": ant.sample_entropy(ts, order=2),
    "PetrosianFD": ant.petrosian_fd(ts),
    "KatzFD": ant.katz_fd(ts),
    "HiguchiFD": ant.higuchi_fd(ts),
    "DFA": ant.detrended_fluctuation(ts),
}

  11. Compute entropy and fractal dimension metrics on signal traces

    master

    You can use antropy to compute various complexity metrics such as Permutation Entropy, SVD Entropy, Spectral Entropy, Approximate Entropy, Sample Entropy, and several Fractal Dimension (FD) measures. This is useful for analyzing the complexity of time-series data like neural voltage traces.

    Commonly used functions include:

    • ant.perm_entropy(x, order=3, normalize=True)
    • ant.svd_entropy(x, order=3, normalize=True)
    • ant.spectral_entropy(x, sf=sampling_frequency, normalize=True)
    • ant.app_entropy(x, order=2)
    • ant.sample_entropy(x, order=2)
    • ant.petrosian_fd(x)
    • ant.katz_fd(x)
    • ant.higuchi_fd(x)
    • ant.detrended_fluctuation(x)
    import antropy as ant

# Example: computing metrics on a signal trace
# traces[i] represents a single 1D signal array
metrics = {
    "PermEnt": ant.perm_entropy(traces[i], order=3, normalize=True),
    "SVDEnt": ant.svd_entropy(traces[i], order=3, normalize=True),
    "SpecEnt": ant.spectral_entropy(traces[i], sf=sf, normalize=True),
    "AppEnt": ant.app_entropy(traces[i], order=2),
    "SampleEnt": ant.sample_entropy(traces[i], order=2),
    "PetrosianFD": ant.petrosian_fd(traces[i]),
    "KatzFD": ant.katz_fd(traces[i]),
    "HiguchiFD": ant.higuchi_fd(traces[i]),
    "DFA": ant.detrended_fluctuation(traces[i]),
}

  12. Count Zero-Crossings

    master

    Counts the number of times a signal crosses zero.

    Parameters:

    • normalize: If True, divides the count by the number of samples to return a value between 0 and 1.
    • axis: The axis along which to perform the computation. Default is -1.

    Note: A sample that is exactly 0 is treated as positive (signbit(0) == False). A transition like ..., -1, 0, 1, ... counts as one crossing (at the -1 -> 0 boundary).

    import numpy as np
import antropy as ant

# Absolute count
print(int(ant.num_zerocross([-1, 0, 1, 2, 3])))  # 1

# Normalized count
print(int(ant.num_zerocross([0, 0, 2, -1, 0, 1, 0, 2])))  # 2

# Pure sine wave
N = 3000
t = np.arange(N) / 100
x = np.sin(2 * np.pi * 1 * t)
print(int(ant.num_zerocross(x)))  # 7