antropy 0.2.0__tar.gz → 0.2.2__tar.gz

antropy-0.2.2/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: antropy
+Version: 0.2.2
+Summary: AntroPy: entropy and complexity of time-series in Python
+Author-email: Raphael Vallat <raphaelvallat9@gmail.com>
+Maintainer-email: Raphael Vallat <raphaelvallat9@gmail.com>
+License: BSD (3-clause)
+Project-URL: Homepage, https://github.com/raphaelvallat/antropy/
+Project-URL: Downloads, https://github.com/raphaelvallat/antropy/
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy>=1.22.4
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: scikit-learn>=1.2.0
+Requires-Dist: numba>=0.57
+Dynamic: license-file
+
+.. -*- mode: rst -*-
+
+|
+
+.. image:: https://badge.fury.io/py/antropy.svg
+  :target: https://badge.fury.io/py/antropy
+
+.. image:: https://img.shields.io/conda/vn/conda-forge/antropy.svg
+  :target: https://anaconda.org/conda-forge/antropy
+
+.. image:: https://img.shields.io/github/license/raphaelvallat/antropy.svg
+  :target: https://github.com/raphaelvallat/antropy/blob/master/LICENSE
+
+.. image:: https://github.com/raphaelvallat/antropy/actions/workflows/python_tests.yml/badge.svg
+  :target: https://github.com/raphaelvallat/antropy/actions/workflows/python_tests.yml
+
+.. image:: https://codecov.io/gh/raphaelvallat/antropy/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/raphaelvallat/antropy
+
+.. image:: https://static.pepy.tech/badge/antropy
+  :target: https://pepy.tech/projects/antropy
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+  :target: https://github.com/astral-sh/ruff
+  :alt: Ruff
+
+----------------
+
+.. figure:: https://raw.githubusercontent.com/raphaelvallat/antropy/master/docs/pictures/logo.png
+   :align: center
+
+**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.
+
+- `Documentation <https://raphaelvallat.com/antropy/>`_
+- `Changelog <https://raphaelvallat.com/antropy/changelog.html>`_
+- `GitHub <https://github.com/raphaelvallat/antropy>`_
+
+----------------
+
+Functions
+=========
+
+Entropy
+-------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - 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
+-----------------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - 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).
+
+.. code-block:: shell
+
+    # pip
+    pip install antropy
+
+    # uv
+    uv pip install antropy
+
+    # conda
+    conda install -c conda-forge antropy
+
+Development installation
+------------------------
+
+.. code-block:: shell
+
+    git clone https://github.com/raphaelvallat/antropy.git
+    cd antropy
+    uv pip install --group=test --editable .
+    pytest --verbose
+
+----------------
+
+Quick start
+===========
+
+Entropy measures
+----------------
+
+.. code-block:: python
+
+    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))
+
+.. parsed-literal::
+
+    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
+-----------------
+
+.. code-block:: python
+
+    print(ant.petrosian_fd(x))
+    print(ant.katz_fd(x))
+    print(ant.higuchi_fd(x))
+    print(ant.detrended_fluctuation(x))
+
+.. parsed-literal::
+
+    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:
+
+.. code-block:: python
+
+    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):
+
+.. list-table::
+   :widths: 32 20 20 28
+   :header-rows: 1
+
+   * - 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 <https://raphaelvallat.com>`_.
+Contributions are welcome — feel free to open an issue or submit a pull request on
+`GitHub <https://github.com/raphaelvallat/antropy>`_.
+
+**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:
+
+- `MNE-features <https://github.com/mne-tools/mne-features>`_ — Jean-Baptiste Schiratti & Alexandre Gramfort
+- `pyEntropy <https://github.com/nikdon/pyEntropy>`_ — Nikolay Donets
+- `pyrem <https://github.com/gilestrolab/pyrem>`_ — Quentin Geissmann
+- `nolds <https://github.com/CSchoel/nolds>`_ — Christopher Scholzel

antropy-0.2.2/README.rst

@@ -0,0 +1,287 @@
+.. -*- mode: rst -*-
+
+|
+
+.. image:: https://badge.fury.io/py/antropy.svg
+  :target: https://badge.fury.io/py/antropy
+
+.. image:: https://img.shields.io/conda/vn/conda-forge/antropy.svg
+  :target: https://anaconda.org/conda-forge/antropy
+
+.. image:: https://img.shields.io/github/license/raphaelvallat/antropy.svg
+  :target: https://github.com/raphaelvallat/antropy/blob/master/LICENSE
+
+.. image:: https://github.com/raphaelvallat/antropy/actions/workflows/python_tests.yml/badge.svg
+  :target: https://github.com/raphaelvallat/antropy/actions/workflows/python_tests.yml
+
+.. image:: https://codecov.io/gh/raphaelvallat/antropy/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/raphaelvallat/antropy
+
+.. image:: https://static.pepy.tech/badge/antropy
+  :target: https://pepy.tech/projects/antropy
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+  :target: https://github.com/astral-sh/ruff
+  :alt: Ruff
+
+----------------
+
+.. figure:: https://raw.githubusercontent.com/raphaelvallat/antropy/master/docs/pictures/logo.png
+   :align: center
+
+**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.
+
+- `Documentation <https://raphaelvallat.com/antropy/>`_
+- `Changelog <https://raphaelvallat.com/antropy/changelog.html>`_
+- `GitHub <https://github.com/raphaelvallat/antropy>`_
+
+----------------
+
+Functions
+=========
+
+Entropy
+-------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - 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
+-----------------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - 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).
+
+.. code-block:: shell
+
+    # pip
+    pip install antropy
+
+    # uv
+    uv pip install antropy
+
+    # conda
+    conda install -c conda-forge antropy
+
+Development installation
+------------------------
+
+.. code-block:: shell
+
+    git clone https://github.com/raphaelvallat/antropy.git
+    cd antropy
+    uv pip install --group=test --editable .
+    pytest --verbose
+
+----------------
+
+Quick start
+===========
+
+Entropy measures
+----------------
+
+.. code-block:: python
+
+    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))
+
+.. parsed-literal::
+
+    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
+-----------------
+
+.. code-block:: python
+
+    print(ant.petrosian_fd(x))
+    print(ant.katz_fd(x))
+    print(ant.higuchi_fd(x))
+    print(ant.detrended_fluctuation(x))
+
+.. parsed-literal::
+
+    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:
+
+.. code-block:: python
+
+    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):
+
+.. list-table::
+   :widths: 32 20 20 28
+   :header-rows: 1
+
+   * - 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 <https://raphaelvallat.com>`_.
+Contributions are welcome — feel free to open an issue or submit a pull request on
+`GitHub <https://github.com/raphaelvallat/antropy>`_.
+
+**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:
+
+- `MNE-features <https://github.com/mne-tools/mne-features>`_ — Jean-Baptiste Schiratti & Alexandre Gramfort
+- `pyEntropy <https://github.com/nikdon/pyEntropy>`_ — Nikolay Donets
+- `pyrem <https://github.com/gilestrolab/pyrem>`_ — Quentin Geissmann
+- `nolds <https://github.com/CSchoel/nolds>`_ — Christopher Scholzel

{antropy-0.2.0 → antropy-0.2.2}/pyproject.toml

@@ -36,7 +36,7 @@ dependencies = [
 [dependency-groups]
 dev = ["ruff>=0.9"]
 test = [
-    "pytest>=6",
+    "pytest>=7.0",
     "pytest-cov",
     # Ensure coverage is new enough for `source_pkgs`.
     "coverage[toml]>=5.3",
@@ -54,7 +54,6 @@ Homepage = "https://github.com/raphaelvallat/antropy/"
 Downloads = "https://github.com/raphaelvallat/antropy/"
 
 [tool.setuptools]
-py-modules = ["antropy"]
 include-package-data = false
 
 [tool.setuptools.packages.find]
@@ -65,8 +64,10 @@ where = ["src"]
 version = {attr = "antropy.__version__"}
 
 [tool.pytest.ini_options]
-minversion = "6.0"
+minversion = "7.0"
 addopts = "--showlocals --durations=10"  # --cov
+testpaths = ["tests"]
+pythonpath = ["tests"]
 doctest_optionflags= ["NORMALIZE_WHITESPACE", "IGNORE_EXCEPTION_DETAIL"]
 filterwarnings = [
     "ignore::UserWarning",

{antropy-0.2.0 → antropy-0.2.2}/src/antropy/__init__.py

@@ -3,4 +3,4 @@ from .entropy import *
 from .fractal import *
 from .utils import *
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"