antropy 0.2.2__tar.gz → 0.2.3__tar.gz

{antropy-0.2.2/src/antropy.egg-info → antropy-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: antropy
-Version: 0.2.2
+Version: 0.2.3
 Summary: AntroPy: entropy and complexity of time-series in Python
 Author-email: Raphael Vallat <raphaelvallat9@gmail.com>
 Maintainer-email: Raphael Vallat <raphaelvallat9@gmail.com>

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

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

{antropy-0.2.2 → antropy-0.2.3}/src/antropy/entropy.py

@@ -31,12 +31,11 @@ __all__ = [
 # the ordinal index from a small pre-computed table.  This avoids the O(m
 # log m) sort and replaces it with O(m) bitwise operations.
 #
-# Note: equal values (ties) are encoded as False by '<', which may assign
-# them to a different ordinal pattern than argsort would.  For the typical
-# case of continuous data this never occurs in practice.
+# Comparisons use '<=' because the left column always has the earlier
+# position. This breaks ties by position, matching stable argsort.
 # ---------------------------------------------------------------------------
 
-# order=3 — key bits: bit2=(a<b), bit1=(a<c), bit0=(b<c)
+# order=3 — key bits: bit2=(a<=b), bit1=(a<=c), bit0=(b<=c)
 # The 8-entry _PE3_LOOKUP maps the 3-bit key to the hashmult hash value
 # (sum of argsort * [1,3,9]) used by the general path; _PE3_REMAP then
 # compresses those 6 sparse hash values to the dense range 0..5.
@@ -52,8 +51,8 @@ for _i, _v in enumerate([5, 7, 11, 15, 19, 21]):
     _PE3_REMAP[_v] = _i
 del _i, _v
 
-# order=4 — key bits: bit5=(a<b), bit4=(a<c), bit3=(a<d), bit2=(b<c),
-#                     bit1=(b<d), bit0=(c<d)
+# order=4 — key bits: bit5=(a<=b), bit4=(a<=c), bit3=(a<=d), bit2=(b<=c),
+#                     bit1=(b<=d), bit0=(c<=d)
 # The 64-entry table directly maps each valid 6-bit key to ordinal 0..23.
 # Invalid keys (impossible comparison patterns) keep the sentinel value -1.
 _PE4_LOOKUP = np.full(64, -1, dtype=np.int64)
@@ -87,24 +86,26 @@ def _perm_entropy_fast(x, order, delay, normalize):
     n, m = x.shape
     n_embed = m - (order - 1) * delay
 
-    # Apply a positional epsilon jitter — adding i*eps to column i — so that
-    # any tied values are broken by column index, exactly matching argsort's
-    # behaviour.  This handles integer signals, quantized data, zero-padded
-    # epochs, and any other input with exact duplicate values.
-    # eps is scaled to the signal magnitude so the jitter never affects the
-    # ordering of distinct values.
-    eps = np.finfo(np.float64).eps * (float(np.abs(x).max()) + 1)
-    cols = [
-        x[:, i * delay : i * delay + n_embed].astype(np.float64) + i * eps for i in range(order)
-    ]
+    # NaN comparisons do not define an ordering and can produce invalid keys.
+    # Process valid epochs separately so a missing sample cannot affect them.
+    # Self-comparison detects NaN without requiring a float dtype.
+    valid_epochs = (x == x).all(axis=1)
+    if not valid_epochs.all():
+        result = np.full(n, np.nan)
+        result[valid_epochs] = _perm_entropy_fast(x[valid_epochs], order, delay, normalize)
+        return float(result[0]) if is_1d else result
+
+    # Keep the original values: a numeric jitter can reorder close values,
+    # and conversion to float64 can lose differences between large integers.
+    cols = [x[:, i * delay : i * delay + n_embed] for i in range(order)]
 
     if order == 3:
         col0, col1, col2 = cols
         # Encode the 3 pairwise comparisons as bits of an integer key
         bit_key = (
-            ((col0 < col1).astype(np.uint8) << 2)
-            | ((col0 < col2).astype(np.uint8) << 1)
-            | (col1 < col2).astype(np.uint8)
+            ((col0 <= col1).astype(np.uint8) << 2)
+            | ((col0 <= col2).astype(np.uint8) << 1)
+            | (col1 <= col2).astype(np.uint8)
         )
         keys = _PE3_REMAP[_PE3_LOOKUP[bit_key]]  # ordinal indices 0..5
         n_perms = 6
@@ -113,12 +114,12 @@ def _perm_entropy_fast(x, order, delay, normalize):
         col0, col1, col2, col3 = cols
         # Encode the 6 pairwise comparisons as bits of an integer key
         bit_key = (
-            ((col0 < col1).astype(np.uint8) << 5)
-            | ((col0 < col2).astype(np.uint8) << 4)
-            | ((col0 < col3).astype(np.uint8) << 3)
-            | ((col1 < col2).astype(np.uint8) << 2)
-            | ((col1 < col3).astype(np.uint8) << 1)
-            | (col2 < col3).astype(np.uint8)
+            ((col0 <= col1).astype(np.uint8) << 5)
+            | ((col0 <= col2).astype(np.uint8) << 4)
+            | ((col0 <= col3).astype(np.uint8) << 3)
+            | ((col1 <= col2).astype(np.uint8) << 2)
+            | ((col1 <= col3).astype(np.uint8) << 1)
+            | (col2 <= col3).astype(np.uint8)
         )
         keys = _PE4_LOOKUP[bit_key]  # ordinal indices 0..23
         n_perms = 24
@@ -150,10 +151,11 @@ def perm_entropy(x, order=3, delay=1, normalize=False):
         2D input is only supported for ``order=3`` or ``order=4``.
     order : int
         Order of permutation entropy. Default is 3.
-    delay : int, list, np.ndarray or range
+    delay : int, list, tuple, 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.
+        entropy across all these delays. For 2D input, the average is taken
+        separately for each epoch. Delay sequences must be nonempty and 1D.
     normalize : bool
         If True, divide by log2(order!) to normalize the entropy between 0
         and 1. Otherwise, return the permutation entropy in bits.
@@ -162,7 +164,8 @@ def perm_entropy(x, order=3, delay=1, normalize=False):
     -------
     pe : float or np.array
         Permutation entropy. Returns a scalar for 1D input, or an array of
-        shape ``(n_epochs,)`` for 2D input.
+        shape ``(n_epochs,)`` for 2D input. For orders 3 and 4, an epoch
+        containing NaN returns NaN without affecting other epochs.
 
     Notes
     -----
@@ -245,15 +248,32 @@ def perm_entropy(x, order=3, delay=1, normalize=False):
     (4,)
     >>> print(np.round(pe, 4))
     [0.9997 0.9991 0.9988 0.9988]
+
+    Multiple delays retain one average per epoch:
+
+    >>> pe_delays = ant.perm_entropy(x2d, delay=(1, 2, 3), normalize=True)
+    >>> pe_delays.shape
+    (4,)
+    >>> single_delays = [ant.perm_entropy(x2d, delay=d, normalize=True) for d in (1, 2, 3)]
+    >>> np.allclose(pe_delays, np.mean(single_delays, axis=0))
+    True
     """
-    # If multiple delays are passed, return the average across all of them
-    if isinstance(delay, (list, np.ndarray, range)):
-        return np.mean([perm_entropy(x, order=order, delay=d, normalize=normalize) for d in delay])
     x = np.asarray(x)
     if x.ndim not in (1, 2):
         raise ValueError("x must be 1D or 2D.")
     if order < 2:
         raise ValueError("Order has to be at least 2.")
+    # If multiple delays are passed, return the average across all of them
+    delays = np.asarray(delay)
+    if delays.ndim > 1:
+        raise ValueError("delay must be a scalar or a 1D sequence.")
+    if delays.ndim == 1:
+        if not delays.size:
+            raise ValueError("delay sequence must not be empty.")
+        return np.mean(
+            [perm_entropy(x, order=order, delay=d, normalize=normalize) for d in delays], axis=0
+        )
+    delay = delays.item()
     if delay < 1:
         raise ValueError("delay must be greater than zero.")
     delay = int(delay)

{antropy-0.2.2 → antropy-0.2.3/src/antropy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: antropy
-Version: 0.2.2
+Version: 0.2.3
 Summary: AntroPy: entropy and complexity of time-series in Python
 Author-email: Raphael Vallat <raphaelvallat9@gmail.com>
 Maintainer-email: Raphael Vallat <raphaelvallat9@gmail.com>

{antropy-0.2.2 → antropy-0.2.3}/tests/test_entropy.py

@@ -4,7 +4,7 @@ import unittest
 
 import numpy as np
 from numpy import apply_along_axis as aal
-from numpy.testing import assert_equal
+from numpy.testing import assert_allclose, assert_equal
 from utils import ARANGE, NORMAL_TS, PURE_SINE, RANDOM_TS, RANDOM_TS_LONG, TEST_DTYPES
 
 from antropy import (
@@ -27,8 +27,8 @@ def _perm_entropy_orig(x, order=3, delay=1, normalize=False):
     """Original argsort-based implementation with no fast path, used as reference.
 
     Uses kind='stable' so that ties are broken by position (earlier index ranks
-    lower), matching the behaviour of the positional epsilon jitter in the fast
-    path.  For tie-free data stable and quicksort give identical results.
+    lower), matching the position-based comparisons in the fast path.
+    For tie-free data stable and quicksort give identical results.
     """
     from math import factorial
 
@@ -82,8 +82,7 @@ class TestEntropy(unittest.TestCase):
     def test_perm_entropy_ties(self):
         """Fast path must agree with the original argsort implementation on signals with ties.
 
-        A positional epsilon jitter is applied to all inputs so ties are broken
-        by column index, exactly matching argsort's position-based tiebreaking.
+        Ties are broken by column index, matching stable argsort.
         This applies to integer arrays, float arrays with duplicate values,
         zero-padded signals, and quantized data stored as float.
         """
@@ -94,8 +93,7 @@ class TestEntropy(unittest.TestCase):
             perm_entropy(x_const, order=3), _perm_entropy_orig(x_const, order=3)
         )
 
-        # Ties at different window positions: without jitter the fast path would
-        # collapse both tied windows to the same pattern; with jitter it matches argsort.
+        # Ties at different window positions must remain distinct patterns.
         # x = [3, 2, 2, 1, 3]:
         #   window [3,2,2] → argsort [1,2,0]  (b<c<a, tie broken by position)
         #   window [2,2,1] → argsort [2,0,1]  (c<a<b, tie broken by position)
@@ -106,7 +104,7 @@ class TestEntropy(unittest.TestCase):
             atol=1e-12,
         )
 
-        # Same signal stored as float — jitter must apply regardless of dtype
+        # Same signal stored as float: tie handling is independent of dtype.
         x_ties_float = x_ties.astype(float)
         np.testing.assert_allclose(
             perm_entropy(x_ties_float, order=3),
@@ -145,6 +143,66 @@ class TestEntropy(unittest.TestCase):
                 err_msg=f"Mismatch on quantized float signal for order={order}",
             )
 
+    def test_perm_entropy_preserves_ordering(self):
+        x = np.array([2, 0, 3, 1, 4, 1, 5, 2, 3, 0, 1, 4], dtype=np.int64)
+        examples = [
+            x,
+            x + 2**60,
+            x.astype(np.uint64) + 2**63,
+            np.array([int(value) + 2**100 for value in x], dtype=object),
+            x * 1e-18,
+            1.0 + x * np.finfo(float).eps,
+        ]
+        for order in [3, 4]:
+            for delay in [1, 2, 3]:
+                for normalize in [False, True]:
+                    # All examples preserve x's ordinal patterns. The original
+                    # embedding helper casts integers to float64, so use x as
+                    # the reference before adding large offsets.
+                    reference = _perm_entropy_orig(x, order, delay, normalize)
+                    for values in examples:
+                        np.testing.assert_allclose(
+                            perm_entropy(values, order, delay, normalize),
+                            reference,
+                            rtol=0,
+                            atol=1e-14,
+                        )
+                    batch = np.vstack([x, x + 2**60])
+                    np.testing.assert_allclose(
+                        perm_entropy(batch, order, delay, normalize),
+                        [reference, reference],
+                        rtol=0,
+                        atol=1e-14,
+                    )
+
+    def test_perm_entropy_nan_epoch_isolation(self):
+        values = np.array([1, 0, 2, 3, 5, 4, 1, 2.0])
+        missing = values.copy()
+        missing[1] = np.nan
+        for order in [3, 4]:
+            for normalize in [False, True]:
+                self.assertTrue(np.isnan(perm_entropy(missing, order, normalize=normalize)))
+                self.assertTrue(
+                    np.isnan(perm_entropy(missing.astype(object), order, normalize=normalize))
+                )
+                self.assertTrue(np.isnan(perm_entropy(np.vstack([missing, missing]), order)).all())
+                expected = _perm_entropy_orig(values, order, normalize=normalize)
+                for position in [0, 1, 2]:
+                    batch = np.vstack([values, values, values])
+                    batch[position] = missing
+                    before = batch.copy()
+                    actual = perm_entropy(batch, order, normalize=normalize)
+                    self.assertTrue(np.isnan(actual[position]))
+                    np.testing.assert_allclose(np.delete(actual, position), expected)
+                    np.testing.assert_array_equal(batch, before)
+
+                infinite = values.copy()
+                infinite[:2] = [-np.inf, np.inf]
+                np.testing.assert_allclose(
+                    perm_entropy(infinite, order, normalize=normalize),
+                    _perm_entropy_orig(infinite, order, normalize=normalize),
+                )
+
     def test_perm_entropy_fast_path(self):
         """Fast paths (order=3/4) must match the original argsort implementation for 1D input."""
         rng = np.random.default_rng(0)
@@ -186,6 +244,44 @@ class TestEntropy(unittest.TestCase):
                         err_msg=f"2D mismatch: order={order}, delay={delay}, normalize={normalize}",
                     )
 
+    def test_perm_entropy_delay_shapes(self):
+        batch = np.random.default_rng(0).random((3, 30))
+        for values in [batch[0], batch]:
+            np.testing.assert_allclose(
+                perm_entropy(values, delay=np.array(2)), perm_entropy(values, delay=2)
+            )
+            for empty in [[], (), range(0), np.array([])]:
+                with self.assertRaisesRegex(ValueError, "delay sequence must not be empty"):
+                    perm_entropy(values, delay=empty)
+            with self.assertRaisesRegex(ValueError, "scalar or a 1D sequence"):
+                perm_entropy(values, delay=np.array([[1, 2]]))
+
+    def test_perm_entropy_2d_multiple_delays(self):
+        x = np.array(
+            [
+                [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 8],
+                [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+            ]
+        )
+        for order in [3, 4]:
+            for normalize in [False, True]:
+                for delays in [[1, 2, 3], (1, 2, 3), np.array([1, 2, 3]), range(1, 4)]:
+                    reference = [
+                        np.mean(
+                            [_perm_entropy_orig(row, order, delay, normalize) for delay in delays]
+                        )
+                        for row in x
+                    ]
+                    result = perm_entropy(x, order, delays, normalize)
+                    self.assertEqual(result.shape, (2,))
+                    np.testing.assert_allclose(result, reference)
+                    single_epoch = perm_entropy(x[:1], order, delays, normalize)
+                    self.assertEqual(single_epoch.shape, (1,))
+                    np.testing.assert_allclose(single_epoch, reference[:1])
+                    scalar = perm_entropy(x[0], order, delays, normalize)
+                    self.assertEqual(np.ndim(scalar), 0)
+                    np.testing.assert_allclose(scalar, reference[0])
+
     def test_spectral_entropy(self):
         spectral_entropy(RANDOM_TS, SF_TS, method="fft")
         spectral_entropy(RANDOM_TS, SF_TS, method="welch")
@@ -194,7 +290,7 @@ class TestEntropy(unittest.TestCase):
         self.assertEqual(np.round(spectral_entropy(PURE_SINE, 100), 2), 0.0)
         # 2D data
         params = dict(sf=SF_TS, normalize=True, method="welch", nperseg=100)
-        assert_equal(
+        assert_allclose(
             aal(spectral_entropy, axis=1, arr=data, **params),
             spectral_entropy(data, **params),
         )
@@ -310,7 +406,7 @@ class TestEntropy(unittest.TestCase):
         assert mob_sine < mob
         assert com_sine < com
         # 2D data (avoid warning with flat line variance)
-        assert_equal(
+        assert_allclose(
             aal(hjorth_params, axis=-1, arr=data[:-1, :]).T,
             hjorth_params(data[:-1, :], axis=-1),
         )

{antropy-0.2.2 → antropy-0.2.3}/tests/test_fractal.py

@@ -4,7 +4,7 @@ import unittest
 
 import numpy as np
 from numpy import apply_along_axis as aal
-from numpy.testing import assert_equal
+from numpy.testing import assert_allclose
 from utils import ARANGE, NORMAL_TS, PURE_COSINE, PURE_SINE, RANDOM_TS, TEST_DTYPES
 
 from antropy import detrended_fluctuation, higuchi_fd, katz_fd, petrosian_fd
@@ -49,16 +49,16 @@ class TestEntropy(unittest.TestCase):
         petrosian_fd(list(RANDOM_TS))
         self.assertEqual(np.round(pfd, 3), 1.030)
         # 2D data
-        assert_equal(aal(petrosian_fd, axis=1, arr=data), petrosian_fd(data))
-        assert_equal(aal(petrosian_fd, axis=0, arr=data), petrosian_fd(data, axis=0))
+        assert_allclose(aal(petrosian_fd, axis=1, arr=data), petrosian_fd(data))
+        assert_allclose(aal(petrosian_fd, axis=0, arr=data), petrosian_fd(data, axis=0))
 
     def test_katz_fd(self):
         x_k = [0.0, 0.0, 2.0, -2.0, 0.0, -1.0, -1.0, 0.0]
         self.assertEqual(np.round(katz_fd(x_k), 3), 5.783)
         # 2D data
         data_kfd = np.vstack((RANDOM_TS, NORMAL_TS, PURE_SINE, PURE_COSINE, ARANGE))
-        assert_equal(aal(katz_fd, axis=1, arr=data_kfd), katz_fd(data_kfd))
-        assert_equal(aal(katz_fd, axis=0, arr=data_kfd), katz_fd(data_kfd, axis=0))
+        assert_allclose(aal(katz_fd, axis=1, arr=data_kfd), katz_fd(data_kfd))
+        assert_allclose(aal(katz_fd, axis=0, arr=data_kfd), katz_fd(data_kfd, axis=0))
 
     def test_higuchi_fd(self):
         """Test for function `higuchi_fd`.