complexeva 0.2.2__tar.gz → 0.3.0__tar.gz

complexeva-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+build
+dist
+complexeva.egg-info
+_dev**
+**.sh
+
+__pycache__
+.DS_Store
+**test.py
+
+candidate-measures.md
+dev.py

complexeva-0.3.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# changelog
+
+## 0.3.0 (unreleased)
+
+Numerical results of three measures change. To reproduce earlier results, pin `complexeva==0.2.3`.
+
+- Breaking: measures are imported from the top level (`from complexeva import hfd`); `complexeva.sequence` is removed.
+- Breaking: removed unexported helpers (`hfd_hilbert_envelope/transform/frequency`, `lempel_ziv_hilbert_envelope/transform/frequency`, `time_series_to_binary`) and the unused `**kwargs` of `lempel_ziv`.
+
+- `hfd`, `hfd_hilbert`: default `k_max` is now 10 (was 64), which gives lower error and better discrimination on series of a few hundred points.
+- `hfd`: raises `ValueError` when `k_max` is outside 2 to len(X) // 2 (previously `ZeroDivisionError` or NaN on short series).
+- `hfd`: now returns the standard Higuchi fractal dimension D; 0.2.3 returned D - 1 (missing `/k` in L_m(k)) and skipped the last increment of each subsequence.
+- `lempel_ziv`: now counts the final unfinished component as in Kaspar & Schuster (1987); 0.2.3 undercounted by 1 on most inputs. New `normalize=True` option returns c*log2(n)/n.
+- `lyapunov_exponent`: rewritten as the Rosenstein et al. (1993) largest Lyapunov exponent with a Theiler window; 0.2.3 averaged one-step log distances and depended on signal amplitude. New options `min_tsep`, `trajectory_len`, `fit_offset`.

complexeva-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Don Yin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

complexeva-0.3.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: complexeva
+Version: 0.3.0
+Summary: Complexity measures for 1D time series: Higuchi fractal dimension, Lempel-Ziv, compression, Lyapunov exponent
+Project-URL: Homepage, https://github.com/Don-Yin/complexeva
+Project-URL: Changelog, https://github.com/Don-Yin/complexeva/blob/main/CHANGELOG.md
+Author-email: Don Yin <don_yin@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.14
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# complexeva
+
+Complexity measures for 1D time series, implemented with NumPy, SciPy and Numba.
+
+## install
+
+```bash
+pip install complexeva
+```
+
+Requires Python 3.14 or later.
+
+## example
+
+```python
+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
+
+| function | what it returns | main parameters | reference |
+|---|---|---|---|
+| `hfd(X, k_max=10)` | Higuchi fractal dimension, 1 (smooth) to 2 (white noise) | `k_max`: largest time interval, 2 to len(X) // 2; report it with results | Higuchi 1988, Physica D 31:277 |
+| `hfd_hilbert(X, k_max=10)` | `hfd` of the Hilbert envelope (instantaneous amplitude) | as `hfd` | |
+| `lempel_ziv(x, method="median", normalize=False)` | Lempel-Ziv complexity: integer count, or c·log2(n)/n (about 1 for random input) when `normalize=True` | `method`: binarise by `"median"`, `"mean"` or `"diff"` (rising step); a `"0101..."` string is used as is | Kaspar & Schuster 1987, Phys. Rev. A 36:842 |
+| `lempel_ziv_hilbert(x, method="median", normalize=False)` | `lempel_ziv` of the Hilbert envelope | as `lempel_ziv` | |
+| `compression_complexity(data)` | zlib-compressed size / raw size of the array bytes, 0 to about 1 | depends on the array dtype | |
+| `lyapunov_exponent(data, tau=1, m=2, dt=1.0, min_tsep=None, trajectory_len=20, fit_offset=0)` | largest Lyapunov exponent in units of 1/`dt`; positive suggests chaos, about 0 for periodic signals | `tau`, `m`: delay embedding; `min_tsep`: Theiler window (default: mean period); `trajectory_len`: steps fitted | Rosenstein et al. 1993, Physica D 65:117 |
+
+All functions take a 1D array. Results changed in 0.3.0; see [CHANGELOG.md](CHANGELOG.md).
+
+## licence
+
+MIT

complexeva-0.3.0/README.md

@@ -0,0 +1,42 @@
+# complexeva
+
+Complexity measures for 1D time series, implemented with NumPy, SciPy and Numba.
+
+## install
+
+```bash
+pip install complexeva
+```
+
+Requires Python 3.14 or later.
+
+## example
+
+```python
+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
+
+| function | what it returns | main parameters | reference |
+|---|---|---|---|
+| `hfd(X, k_max=10)` | Higuchi fractal dimension, 1 (smooth) to 2 (white noise) | `k_max`: largest time interval, 2 to len(X) // 2; report it with results | Higuchi 1988, Physica D 31:277 |
+| `hfd_hilbert(X, k_max=10)` | `hfd` of the Hilbert envelope (instantaneous amplitude) | as `hfd` | |
+| `lempel_ziv(x, method="median", normalize=False)` | Lempel-Ziv complexity: integer count, or c·log2(n)/n (about 1 for random input) when `normalize=True` | `method`: binarise by `"median"`, `"mean"` or `"diff"` (rising step); a `"0101..."` string is used as is | Kaspar & Schuster 1987, Phys. Rev. A 36:842 |
+| `lempel_ziv_hilbert(x, method="median", normalize=False)` | `lempel_ziv` of the Hilbert envelope | as `lempel_ziv` | |
+| `compression_complexity(data)` | zlib-compressed size / raw size of the array bytes, 0 to about 1 | depends on the array dtype | |
+| `lyapunov_exponent(data, tau=1, m=2, dt=1.0, min_tsep=None, trajectory_len=20, fit_offset=0)` | largest Lyapunov exponent in units of 1/`dt`; positive suggests chaos, about 0 for periodic signals | `tau`, `m`: delay embedding; `min_tsep`: Theiler window (default: mean period); `trajectory_len`: steps fitted | Rosenstein et al. 1993, Physica D 65:117 |
+
+All functions take a 1D array. Results changed in 0.3.0; see [CHANGELOG.md](CHANGELOG.md).
+
+## licence
+
+MIT

complexeva-0.3.0/complexeva/__init__.py

@@ -0,0 +1,6 @@
+from .compression import compression_complexity
+from .higuchi import hfd, hfd_hilbert
+from .lempel_ziv import lempel_ziv, lempel_ziv_hilbert
+from .lyapunov_exponent import lyapunov_exponent
+
+__all__ = ["compression_complexity", "hfd", "hfd_hilbert", "lempel_ziv", "lempel_ziv_hilbert", "lyapunov_exponent"]

complexeva-0.3.0/complexeva/compression.py

@@ -0,0 +1,9 @@
+import zlib
+
+import numpy as np
+
+
+def compression_complexity(data: np.ndarray) -> float:
+    """zlib-compressed size divided by raw size of the array bytes."""
+    raw = data.tobytes()
+    return len(zlib.compress(raw)) / len(raw)

complexeva-0.3.0/complexeva/higuchi.py

@@ -0,0 +1,40 @@
+import numpy
+from numba import njit
+from scipy.signal import hilbert
+
+
+@njit
+def compute_L_x(X, k_max):
+    N = len(X)
+    L = numpy.zeros(k_max)
+    x = numpy.zeros(k_max)
+    for k in range(1, k_max + 1):
+        Lk = numpy.zeros(k)
+        for m in range(k):
+            # Higuchi (1988): M = floor((N - m) / k) increments with 1-based m, i.e. (N - 1 - m) // k here
+            Lmk = 0.0
+            n_max = (N - 1 - m) // k
+            for i in range(1, n_max + 1):
+                Lmk += numpy.abs(X[m + i * k] - X[m + (i - 1) * k])
+            Lmk *= (N - 1) / (n_max * k)  # normalisation factor
+            Lk[m] = Lmk / k  # curve length L_m(k); without /k the slope is D - 1
+        L[k - 1] = numpy.log(Lk.mean())
+        x[k - 1] = numpy.log(1.0 / k)
+    return x, L
+
+
+def hfd(X, k_max=10):
+    """Higuchi fractal dimension of a 1D numpy array."""
+    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
+    if not 2 <= k_max <= len(X) // 2:
+        raise ValueError(f"k_max must be between 2 and len(X) // 2 = {len(X) // 2}, got {k_max}")
+    x, L = compute_L_x(X, k_max)
+    A = numpy.column_stack((x, numpy.ones_like(x)))
+    beta, _, _, _ = numpy.linalg.lstsq(A, L, rcond=None)
+    return beta[0]
+
+
+def hfd_hilbert(X, k_max=10):
+    """Higuchi fractal dimension of the Hilbert envelope (instantaneous amplitude) of X."""
+    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
+    return hfd(numpy.abs(numpy.asarray(hilbert(X))), k_max=k_max)

complexeva-0.3.0/complexeva/lempel_ziv.py

@@ -0,0 +1,77 @@
+import numpy
+from numba import njit
+from scipy.signal import hilbert
+
+
+@njit
+def lempel_ziv_core(binary_array):
+    """Kaspar-Schuster count of components needed to reproduce a 0/1 integer array."""
+    history_pos = 0  # position in history we're comparing against
+    current_len = 1  # length of current pattern we're checking
+    max_pattern_len = 1  # length of longest matching pattern found
+    seq_pos = 1  # current position in sequence
+    complexity = 1  # start with 1 as first character is always a new pattern
+    seq_len = len(binary_array)
+
+    while seq_pos + current_len <= seq_len:
+        if binary_array[history_pos + current_len - 1] == binary_array[seq_pos + current_len - 1]:
+            current_len += 1
+        else:
+            max_pattern_len = max(max_pattern_len, current_len)
+            history_pos += 1
+            if history_pos == seq_pos:
+                complexity += 1
+                seq_pos += max_pattern_len
+                history_pos = 0
+                current_len = 1
+                max_pattern_len = 1
+            else:
+                current_len = 1
+    if current_len > 1:  # sequence ended inside a copied component; Kaspar-Schuster counts it
+        complexity += 1
+    return complexity
+
+
+def _binarize(time_series, method):
+    """0/1 array: above median or mean, or increasing step for 'diff' (median follows doi:10.1101/2021.09.23.461002)."""
+    vector = numpy.asarray(time_series, dtype=numpy.float64)
+    if method == "diff":
+        bits = numpy.diff(vector) > 0
+    elif method == "mean":
+        bits = vector > numpy.mean(vector)
+    elif method == "median":
+        bits = vector > numpy.median(vector)
+    else:
+        raise ValueError("Method must be 'mean', 'median', or 'diff'.")
+    return bits.astype(numpy.int32)
+
+
+def lempel_ziv(time_series, method="median", normalize=False):
+    """
+    Lempel-Ziv complexity as described in Kaspar and Schuster (1987), Phys. Rev. A.
+    Counts the number of distinct patterns that need to be copied to reproduce the sequence.
+
+    Args:
+        time_series: Either a binary string (e.g., "1001110") or numeric array to be binarised
+        method: Binarization method if time_series is numeric ('median', 'mean', 'diff')
+        normalize: If True, return c * log2(n) / n for the binary sequence of length n (about 1 for random input)
+
+    Returns: int (raw count) or float (normalized)
+    """
+    if isinstance(time_series, str) and all(c in "01" for c in time_series):
+        binary_array = numpy.array([int(c) for c in time_series], dtype=numpy.int32)
+    else:
+        binary_array = _binarize(time_series, method)
+    complexity = int(lempel_ziv_core(binary_array))
+    if not normalize:
+        return complexity
+    n = len(binary_array)
+    return float(complexity * numpy.log2(n) / n) if n > 1 else 0.0
+
+
+def lempel_ziv_hilbert(time_series, method="median", normalize=False):
+    """Lempel-Ziv complexity of the Hilbert envelope (instantaneous amplitude) of a 1D signal."""
+    time_series = numpy.asarray(time_series)
+    assert time_series.ndim == 1, f"time_series must be a 1d numpy array, got shape {time_series.shape}"
+    envelope = numpy.abs(numpy.asarray(hilbert(time_series)))
+    return lempel_ziv(envelope, method=method, normalize=normalize)

complexeva-0.3.0/complexeva/lyapunov_exponent.py

@@ -0,0 +1,74 @@
+import numpy as np
+from numba import njit
+
+
+@njit(cache=True)
+def _divergence(Y, min_tsep, trajectory_len):
+    """mean log distance between each orbit point and its nearest neighbour after k steps (Rosenstein 1993)"""
+    n_traj = Y.shape[0] - trajectory_len + 1
+    neighbour = np.empty(n_traj, dtype=np.int64)
+    for i in range(n_traj):
+        best, best_j = np.inf, -1
+        for j in range(n_traj):
+            if abs(i - j) <= min_tsep:  # Theiler window: skip temporally close points
+                continue
+            d = np.sum((Y[i] - Y[j]) ** 2)
+            if d < best:
+                best, best_j = d, j
+        neighbour[i] = best_j
+    log_div = np.full(trajectory_len, -np.inf)
+    for k in range(trajectory_len):
+        total, count = 0.0, 0
+        for i in range(n_traj):
+            d = np.sqrt(np.sum((Y[i + k] - Y[neighbour[i] + k]) ** 2))
+            if d > 0:
+                total += np.log(d)
+                count += 1
+        if count > 0:
+            log_div[k] = total / count
+    return log_div
+
+
+def _mean_period(x):
+    """1 / power-weighted mean frequency, the default Theiler window"""
+    psd = np.abs(np.fft.rfft(x - x.mean())) ** 2
+    freqs = np.fft.rfftfreq(len(x))
+    return int(np.ceil(np.sum(psd[1:]) / np.sum(freqs[1:] * psd[1:])))
+
+
+def lyapunov_exponent(data, tau=1, m=2, dt=1.0, min_tsep=None, trajectory_len=20, fit_offset=0):
+    """
+    Largest Lyapunov exponent by the Rosenstein et al. (1993) method.
+
+    The series is delay-embedded, each point is paired with its nearest neighbour outside a Theiler window,
+    and the exponent is the slope of the mean log divergence of those pairs over `trajectory_len` steps.
+
+    Args:
+        data: 1D array-like time series
+        tau: embedding delay in samples
+        m: embedding dimension
+        dt: sampling interval; the result is in units of 1/dt
+        min_tsep: Theiler window in samples; defaults to the mean period of the signal
+        trajectory_len: number of steps over which divergence is followed and fitted
+        fit_offset: number of initial steps excluded from the line fit
+
+    Returns:
+        float: largest Lyapunov exponent (positive suggests chaos, about 0 or below for regular signals)
+    """
+    x = np.asarray(data, dtype=np.float64)
+    if x.ndim != 1:
+        raise ValueError(f"data must be 1D, got shape {x.shape}")
+    if min_tsep is None:
+        min_tsep = min(_mean_period(x), len(x) // 4)
+    n_vectors = len(x) - (m - 1) * tau
+    n_traj = n_vectors - trajectory_len + 1
+    if n_traj < 2 * min_tsep + 2:
+        raise ValueError(f"series too short: {n_traj} trajectories for min_tsep={min_tsep}")
+    Y = np.stack([x[i * tau : i * tau + n_vectors] for i in range(m)], axis=1)
+    log_div = _divergence(Y, min_tsep, trajectory_len)
+    ks = np.arange(trajectory_len)[fit_offset:]
+    log_div = log_div[fit_offset:]
+    finite = np.isfinite(log_div)
+    if finite.sum() < 2:
+        return -np.inf
+    return float(np.polyfit(ks[finite], log_div[finite], 1)[0] / dt)

complexeva-0.3.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "complexeva"
+version = "0.3.0"
+description = "Complexity measures for 1D time series: Higuchi fractal dimension, Lempel-Ziv, compression, Lyapunov exponent"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Don Yin", email = "don_yin@outlook.com" }]
+requires-python = ">=3.14"
+dependencies = ["numpy", "scipy", "numba"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/Don-Yin/complexeva"
+Changelog = "https://github.com/Don-Yin/complexeva/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["/complexeva", "/tests", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 128

complexeva-0.3.0/tests/test_higuchi.py

@@ -0,0 +1,47 @@
+import numpy
+import pytest
+
+from complexeva import hfd
+
+
+def reference_hfd(x, k_max):
+    """Literal Higuchi (1988) formula with 1-based m, written for clarity rather than speed."""
+    N = len(x)
+    log_inv_k, log_L = [], []
+    for k in range(1, k_max + 1):
+        lengths = []
+        for m in range(1, k + 1):
+            M = (N - m) // k
+            total = sum(abs(x[m - 1 + i * k] - x[m - 1 + (i - 1) * k]) for i in range(1, M + 1))
+            lengths.append(total * (N - 1) / (M * k) / k)
+        log_inv_k.append(numpy.log(1.0 / k))
+        log_L.append(numpy.log(numpy.mean(lengths)))
+    return numpy.polyfit(log_inv_k, log_L, 1)[0]
+
+
+@pytest.mark.parametrize("seed", [0, 1, 2])
+def test_matches_literal_formula(seed):
+    x = numpy.random.default_rng(seed).standard_normal(500)
+    assert hfd(x, k_max=16) == pytest.approx(reference_hfd(x, 16), abs=1e-10)
+
+
+def test_k_max_bounds():
+    x = numpy.random.default_rng(3).standard_normal(100)
+    assert numpy.isfinite(hfd(x, k_max=50))
+    for bad in (1, 51):
+        with pytest.raises(ValueError):
+            hfd(x, k_max=bad)
+
+
+@pytest.mark.parametrize(
+    "name, expected, tol",
+    [("white", 2.0, 0.05), ("brown", 1.5, 0.08), ("sine", 1.0, 0.05)],
+)
+def test_known_dimensions(name, expected, tol):
+    rng = numpy.random.default_rng(0)
+    signals = {
+        "white": rng.standard_normal(8192),
+        "brown": numpy.cumsum(rng.standard_normal(8192)),
+        "sine": numpy.sin(numpy.linspace(0, 20 * numpy.pi, 8192)),
+    }
+    assert hfd(signals[name]) == pytest.approx(expected, abs=tol)

complexeva-0.3.0/tests/test_lempel_ziv.py

@@ -0,0 +1,80 @@
+import numpy
+import pytest
+
+from complexeva import lempel_ziv, lempel_ziv_hilbert
+
+
+def reference_kaspar_schuster(s):
+    """Kaspar & Schuster (1987) algorithm as transcribed on Wikipedia, for strings of length >= 2."""
+    i, k, start, c, k_max, n = 0, 1, 1, 1, 1, len(s)
+    while True:
+        if s[i + k - 1] == s[start + k - 1]:
+            k += 1
+            if start + k > n:
+                c += 1
+                break
+        else:
+            k_max = max(k, k_max)
+            i += 1
+            if i == start:
+                c += 1
+                start += k_max
+                if start + 1 > n:
+                    break
+                i, k, k_max = 0, 1, 1
+            else:
+                k = 1
+    return c
+
+
+@pytest.mark.parametrize(
+    "s, expected",
+    [("1", 1), ("0000000000", 2), ("0101010101", 3), ("0001101001000101", 6), ("1001111011000010", 6)],
+)
+def test_known_strings(s, expected):
+    assert lempel_ziv(s) == expected
+
+
+def test_matches_reference_on_random_strings():
+    rng = numpy.random.default_rng(0)
+    for _ in range(3000):
+        s = "".join(rng.choice(["0", "1"], size=int(rng.integers(2, 300))))
+        assert lempel_ziv(s) == reference_kaspar_schuster(s), s
+
+
+@pytest.mark.parametrize("method", ["median", "mean", "diff"])
+def test_numeric_input_equals_binarised_string(method):
+    x = numpy.random.default_rng(1).standard_normal(400)
+    if method == "diff":
+        bits = numpy.diff(x) > 0
+    else:
+        bits = x > (numpy.median(x) if method == "median" else numpy.mean(x))
+    assert lempel_ziv(x, method=method) == reference_kaspar_schuster("".join("1" if b else "0" for b in bits))
+
+
+def test_normalize_default_off_and_formula():
+    s = "1001111011000010"
+    assert lempel_ziv(s) == 6 and isinstance(lempel_ziv(s), int)
+    assert lempel_ziv(s, normalize=True) == pytest.approx(6 * numpy.log2(16) / 16)
+    assert lempel_ziv("1", normalize=True) == 0.0
+
+
+def test_normalized_random_near_one_and_regular_low():
+    rng = numpy.random.default_rng(4)
+    assert lempel_ziv(rng.standard_normal(20000), normalize=True) == pytest.approx(1.0, abs=0.1)
+    assert lempel_ziv(numpy.sin(numpy.linspace(0, 40 * numpy.pi, 20000)), normalize=True) < 0.05
+
+
+def test_normalize_uses_binary_length_for_diff():
+    x = numpy.random.default_rng(5).standard_normal(300)
+    raw = lempel_ziv(x, method="diff")
+    assert lempel_ziv(x, method="diff", normalize=True) == pytest.approx(raw * numpy.log2(299) / 299)
+
+
+def test_hilbert_variant_forwards_normalize():
+    x = numpy.random.default_rng(6).standard_normal(500)
+    assert 0 < lempel_ziv_hilbert(x, normalize=True) < 2
+
+
+def test_hilbert_variant_runs():
+    assert lempel_ziv_hilbert(numpy.random.default_rng(2).standard_normal(500)) > 1

complexeva-0.3.0/tests/test_lyapunov.py

@@ -0,0 +1,49 @@
+import numpy
+import pytest
+
+from complexeva import lyapunov_exponent
+
+
+def logistic(n, x0=0.3):
+    x = numpy.empty(n)
+    x[0] = x0
+    for i in range(1, n):
+        x[i] = 4 * x[i - 1] * (1 - x[i - 1])
+    return x
+
+
+def henon(n):
+    x, y, out = 0.1, 0.1, numpy.empty(n)
+    for i in range(n):
+        x, y = 1 - 1.4 * x * x + y, 0.3 * x
+        out[i] = x
+    return out
+
+
+def test_logistic_map_is_ln2():
+    assert lyapunov_exponent(logistic(3000), m=1, trajectory_len=8) == pytest.approx(numpy.log(2), abs=0.03)
+
+
+def test_henon_map_known_value():
+    assert lyapunov_exponent(henon(3000), m=2, trajectory_len=8) == pytest.approx(0.419, abs=0.03)
+
+
+def test_regular_signal_is_about_zero():
+    x = numpy.sin(numpy.linspace(0, 40 * numpy.pi, 3000))
+    assert abs(lyapunov_exponent(x)) < 0.01
+
+
+def test_scale_and_offset_invariant():
+    x = logistic(2000)
+    a = lyapunov_exponent(x, m=1, trajectory_len=8)
+    assert lyapunov_exponent(1000 * x + 5, m=1, trajectory_len=8) == pytest.approx(a, rel=1e-9)
+
+
+def test_dt_scales_result():
+    x = logistic(2000)
+    assert lyapunov_exponent(x, m=1, trajectory_len=8, dt=0.5) == pytest.approx(2 * lyapunov_exponent(x, m=1, trajectory_len=8))
+
+
+def test_too_short_raises():
+    with pytest.raises(ValueError):
+        lyapunov_exponent(numpy.arange(10.0), min_tsep=5)

complexeva-0.2.2/PKG-INFO

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: complexeva
-Version: 0.2.2
-Home-page: 
-Author: Don Yin
-Author-email: don_yin@outlook.com
-Description-Content-Type: text/markdown
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-
-# overview
-implementations of complexity measures in 1D sequences
-
-# examples
-```python
-from complexeva.sequence import lyapunov_exponent, hfd, lempel_ziv, compression_complexity
-
-signal = numpy.random.rand(1000)  # shape: (1000,)
-complexity = hfd(signal)
-print(complexity)
-```
-
-# install
-```bash
-pip install complexeva
-```

complexeva-0.2.2/README.md

@@ -1,16 +0,0 @@
-# overview
-implementations of complexity measures in 1D sequences
-
-# examples
-```python
-from complexeva.sequence import lyapunov_exponent, hfd, lempel_ziv, compression_complexity
-
-signal = numpy.random.rand(1000)  # shape: (1000,)
-complexity = hfd(signal)
-print(complexity)
-```
-
-# install
-```bash
-pip install complexeva
-```

complexeva-0.2.2/complexeva/sequence/__init__.py

@@ -1,6 +0,0 @@
-from .higuchi import hfd, hfd_hilbert
-from .lempel_ziv import lempel_ziv
-from .compression import compression_complexity
-from .lyapunov_exponent import lyapunov_exponent
-
-__all__ = ["compression_complexity", "lyapunov_exponent", "hfd", "hfd_hilbert", "lempel_ziv"]

complexeva-0.2.2/complexeva/sequence/compression.py

@@ -1,18 +0,0 @@
-#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
-
-import zlib
-import numpy as np
-
-
-def compression_complexity(data: np.ndarray) -> float:
-    """
-    calculate compression complexity using zlib compression -> float: compression complexity score
-    """
-    data = data.tobytes()
-    compressed = zlib.compress(data)
-    return len(compressed) / len(data)  # Normalized complexity score
-
-
-if __name__ == "__main__":
-    signal = np.random.rand(1000)  # shape: (1000,)
-    print(compression_complexity(signal))

complexeva-0.2.2/complexeva/sequence/higuchi.py

@@ -1,75 +0,0 @@
-#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
-
-
-import numpy
-from numba import njit
-from scipy.signal import hilbert
-
-
-@njit
-def compute_L_x(X, k_max=16):
-    k_max = min(k_max, len(X) // 2) if k_max is None else k_max
-    N = len(X)
-    L = numpy.zeros(k_max)
-    x = numpy.zeros(k_max)
-    for k in range(1, k_max + 1):
-        Lk = numpy.zeros(k)
-        for m in range(k):
-            Lmk = 0.0
-            n_max = (N - m) // k
-            for i in range(1, n_max):
-                Lmk += numpy.abs(X[m + i * k] - X[m + (i - 1) * k])
-            Lmk *= (N - 1) / (n_max * k)
-            Lk[m] = Lmk
-        L[k - 1] = numpy.log(Lk.mean())
-        x[k - 1] = numpy.log(1.0 / k)
-    return x, L
-
-
-def hfd(X, k_max=16):
-    """expect a 1d numpy array as input"""
-    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
-    x, L = compute_L_x(X, k_max)
-    A = numpy.column_stack((x, numpy.ones_like(x)))
-    beta, _, _, _ = numpy.linalg.lstsq(A, L, rcond=None)
-    return beta[0]
-
-
-def hfd_hilbert(X, k_max=16):
-    """
-    Calculate Higuchi Fractal Dimension on the instantaneous frequency
-    obtained from Hilbert transform of the input signal.
-
-    Args:
-        X (numpy.ndarray): Input 1D signal
-        k_max (int): Maximum k value for HFD calculation
-
-    Returns:
-        float: Higuchi Fractal Dimension of the instantaneous frequency
-    """
-    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
-    analytic_signal = hilbert(X)
-    instantaneous_phase = numpy.angle(analytic_signal)
-    instantaneous_freq = numpy.diff(instantaneous_phase)
-    instantaneous_freq = numpy.append(instantaneous_freq, instantaneous_freq[-1])
-    return hfd(instantaneous_freq, k_max=k_max)
-
-
-if __name__ == "__main__":
-    import time
-
-    signal = numpy.random.rand(1000)  # shape: (1000,)
-
-    # Test plain HFD speed
-    start_time = time.time()
-    complexity_plain = hfd(signal)
-    plain_time = time.time() - start_time
-
-    # Test Hilbert HFD speed
-    start_time = time.time()
-    complexity_hilbert = hfd_hilbert(signal)
-    hilbert_time = time.time() - start_time
-
-    print(f"Plain HFD: {complexity_plain:.6f}, Time: {plain_time:.6f}s")
-    print(f"Hilbert HFD: {complexity_hilbert:.6f}, Time: {hilbert_time:.6f}s")
-    print(f"Speed ratio (Hilbert/Plain): {hilbert_time/plain_time:.2f}x")

complexeva-0.2.2/complexeva/sequence/lempel_ziv.py

@@ -1,76 +0,0 @@
-#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
-
-import numpy
-
-
-def lempel_ziv(time_series, method="median", **kwargs):
-    """
-    - compared to other implementations, this implementation is makes the most sense
-
-    Lempel-Ziv complexity as described in Kaspar and Schuster, Phys. Rev. A.
-    Counts the number of distinct patterns that need to be copied to reproduce the sequence.
-    Returns: int: The number of distinct patterns (complexity measure)
-    """
-    sequence = time_series_to_binary(time_series, method=method)
-
-    history_pos = 0  # position in history we're comparing against
-    current_len = 1  # length of current pattern we're checking
-    max_pattern_len = 1  # length of longest matching pattern found
-    seq_pos = 1  # current position in sequence
-    complexity = 1  # start with 1 as first character is always a new pattern
-    seq_len = len(sequence)
-
-    while seq_pos + current_len <= seq_len:
-        if sequence[history_pos + current_len - 1] == sequence[seq_pos + current_len - 1]:
-            current_len += 1
-        else:
-            if current_len > max_pattern_len:
-                max_pattern_len = current_len
-            history_pos += 1
-            if history_pos == seq_pos:
-                complexity += 1
-                seq_pos += max_pattern_len
-                history_pos = 0
-                current_len = 1
-                max_pattern_len = 1
-            else:
-                current_len = 1
-    return complexity
-
-
-def time_series_to_binary(vector, method="median"):
-    """
-    - convert a time series to a binary sequence based on a threshold.
-    - returns: str: A binary sequence as a string of '0's and '1's.
-    - https://doi.org/10.1101/2021.09.23.461002 this paper used median, making median the default method.
-    - diff also makes somewhat sense
-    """
-
-    vector = numpy.array(vector)
-
-    match method:
-
-        case "mean":
-            threshold = numpy.mean(vector)
-            binary_seq = "".join(["1" if x > threshold else "0" for x in vector])
-
-        case "median":
-            threshold = numpy.median(vector)
-            binary_seq = "".join(["1" if x > threshold else "0" for x in vector])
-
-        case "diff":  # this measures whether the value is increasing or decreasing as compared to the previous value
-            diffs = numpy.diff(vector)
-            binary_seq = "".join(["1" if x > 0 else "0" for x in diffs])
-
-        case _:
-            raise ValueError("Method must be 'mean', 'median', or 'diff'.")
-
-    return binary_seq
-
-
-if __name__ == "__main__":
-    sequence = "1001111011000010"
-    print(lempel_ziv(sequence))
-    signal = numpy.random.rand(1000)
-    binary_sequence = time_series_to_binary(signal, method="median")
-    print(lempel_ziv(binary_sequence))

complexeva-0.2.2/complexeva/sequence/lyapunov_exponent.py

@@ -1,32 +0,0 @@
-import numpy as np
-from scipy.spatial.distance import pdist, squareform
-
-
-def lyapunov_exponent(data, tau=1, m=2, dt=1):
-    """
-    Calculate the largest Lyapunov exponent for a time series.
-
-    Args:
-        data: numpy array or list of numerical values
-        tau: time delay (default=1)
-        m: embedding dimension (default=2)
-        dt: time step (default=1)
-
-    Returns:
-        float: largest Lyapunov exponent
-    """
-    x = np.array(data)
-    N = len(x)
-    Y = np.zeros((N - (m - 1) * tau, m))
-    for i in range(m):
-        Y[:, i] = x[i * tau : N - (m - 1) * tau + i * tau]
-    D = squareform(pdist(Y))
-    np.fill_diagonal(D, np.inf)  # Exclude self-matches
-    nearest = np.argmin(D, axis=1)
-    div = np.zeros(N - (m - 1) * tau - 1)
-    for i in range(len(div)):
-        div[i] = np.abs(x[i + 1] - x[nearest[i] + 1])
-    positive_div = div[div > 0]  # Avoid log(0)
-    if len(positive_div) == 0:
-        return 0.0
-    return -np.mean(np.log(positive_div)) / dt

complexeva-0.2.2/complexeva/validate.py

@@ -1,117 +0,0 @@
-#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
-
-"""
-- validating measures of complexity is actually working using synthetic data on various Hurst exponents
-"""
-
-import numpy
-import matplotlib.pyplot as plt
-from complexeva.sequence.higuchi import hfd
-from complexeva.sequence.lempel_ziv import lempel_ziv
-
-
-class ComplexityMeasuresValidator2D:
-    def __init__(self, funcs, timeseries_len=1000, num_hurst=200):
-        self.funcs, self.num_hurst, self.timeseries_len = funcs, num_hurst, timeseries_len
-
-    def fbm(self, hurst):
-        """
-        Generate fractional Brownian motion (fBm) time series.
-
-        This method uses the spectral synthesis method to generate a fBm time series
-        with a specified Hurst exponent.
-
-        Parameters:
-        -----------
-        hurst : float
-            The Hurst exponent, a value between 0 and 1 that characterizes
-            the fractal properties of the time series.
-
-        Returns:
-        --------
-        numpy.ndarray
-            A 1D array representing the generated fBm time series.
-
-        Notes:
-        ------
-        - The length of the generated time series is determined by self.timeseries_len.
-        - This method uses the Fourier filtering method to generate fBm.
-        - The first frequency component is set to a small non-zero value (1e-6) to avoid division by zero.
-        """
-
-        n = self.timeseries_len
-        f = numpy.fft.fftfreq(n)
-        f[0] = 1e-6  # avoid division by zero
-        psd = numpy.abs(f) ** (-2 * hurst - 1)
-        gaussian = numpy.random.randn(n) + 1j * numpy.random.randn(n)
-        fBm = numpy.fft.ifft(gaussian * numpy.sqrt(psd)).real
-        return fBm
-
-    def plot_vs_hurst(self):
-        hurst_exponent = numpy.linspace(0.001, 1, self.num_hurst)
-        fBm_series = [self.fbm(h) for h in hurst_exponent]
-        expected_hfd = [2 - h for h in hurst_exponent]
-        hfd_results = []
-
-        for func in self.funcs:
-            hfd_results.append([func(series) for series in fBm_series])
-
-        # ---- plotting ----
-        fig, axs = plt.subplots(3, 1, figsize=(9, 10))
-
-        axs[0].plot(fBm_series[0])
-        axs[0].set_title(f"fBm series with H = {hurst_exponent[0]:.3f}", fontsize=21)
-        mid_index = len(hurst_exponent) // 2
-        axs[1].plot(fBm_series[mid_index])
-        axs[1].set_title(f"fBm series with H = {hurst_exponent[mid_index]:.3f}", fontsize=21)
-        axs[2].plot(fBm_series[-1])
-        axs[2].set_title(f"fBm series with H = {hurst_exponent[-1]:.3f}", fontsize=21)
-
-        for ax in axs:
-            ax.set_xlabel("Time", fontsize=21)
-            ax.set_ylabel("Value", fontsize=21)
-            ax.tick_params(axis="both", which="major", labelsize=12)
-            ax.grid(True)
-
-        plt.tight_layout()
-        plt.savefig("fBm_series_examples.png", dpi=320, bbox_inches="tight")
-
-        # Create figure with two subplots side by side
-        fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(18, 7))
-
-        # Original HFD vs Hurst plot
-        ax1.plot(hurst_exponent, expected_hfd, label="Expected FD")
-        for i, func in enumerate(self.funcs):
-            ax1.plot(hurst_exponent, hfd_results[i], label=f"HFD ({func.__name__})")
-        ax1.set_xlabel("Hurst Exponent (H)", fontsize=14)
-        ax1.set_ylabel("Raw Complexity", fontsize=14)
-        ax1.set_title("Before Normalization", fontsize=16)
-        ax1.grid(True)
-        ax1.tick_params(axis="both", labelsize=12)
-        ax1.legend(fontsize=12)
-
-        # Normalized HFD vs Hurst plot
-        ax2.plot(hurst_exponent, expected_hfd, label="Expected FD")
-        for i, func in enumerate(self.funcs):
-            # Normalize results between 0 and 1
-            normalized_results = (hfd_results[i] - numpy.min(hfd_results[i])) / (
-                numpy.max(hfd_results[i]) - numpy.min(hfd_results[i])
-            )
-            ax2.plot(hurst_exponent, normalized_results, label=f"HFD ({func.__name__})")
-        ax2.set_xlabel("Hurst Exponent (H)", fontsize=14)
-        ax2.set_ylabel("Normalized Complexity", fontsize=14)
-        ax2.set_title("After Normalization (0-1)", fontsize=16)
-        ax2.grid(True)
-        ax2.tick_params(axis="both", labelsize=12)
-        ax2.legend(fontsize=12)
-
-        plt.tight_layout()
-        plt.savefig("hfd_vs_hurst_comparison.png", dpi=320, bbox_inches="tight")
-
-
-if __name__ == "__main__":
-    validator = ComplexityMeasuresValidator2D([hfd])
-    validator.plot_vs_hurst()
-
-    validator = ComplexityMeasuresValidator2D([lempel_ziv])
-    validator.plot_vs_hurst()

complexeva-0.2.2/complexeva.egg-info/PKG-INFO

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: complexeva
-Version: 0.2.2
-Home-page: 
-Author: Don Yin
-Author-email: don_yin@outlook.com
-Description-Content-Type: text/markdown
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-
-# overview
-implementations of complexity measures in 1D sequences
-
-# examples
-```python
-from complexeva.sequence import lyapunov_exponent, hfd, lempel_ziv, compression_complexity
-
-signal = numpy.random.rand(1000)  # shape: (1000,)
-complexity = hfd(signal)
-print(complexity)
-```
-
-# install
-```bash
-pip install complexeva
-```

complexeva-0.2.2/complexeva.egg-info/SOURCES.txt

@@ -1,13 +0,0 @@
-README.md
-setup.py
-complexeva/__init__.py
-complexeva/validate.py
-complexeva.egg-info/PKG-INFO
-complexeva.egg-info/SOURCES.txt
-complexeva.egg-info/dependency_links.txt
-complexeva.egg-info/top_level.txt
-complexeva/sequence/__init__.py
-complexeva/sequence/compression.py
-complexeva/sequence/higuchi.py
-complexeva/sequence/lempel_ziv.py
-complexeva/sequence/lyapunov_exponent.py

complexeva-0.2.2/complexeva.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

complexeva-0.2.2/complexeva.egg-info/top_level.txt

@@ -1 +0,0 @@
-complexeva

complexeva-0.2.2/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-

complexeva-0.2.2/setup.py

@@ -1,15 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="complexeva",
-    version="0.2.2",
-    packages=find_packages(),
-    install_requires=[],
-    author="Don Yin",
-    author_email="don_yin@outlook.com",
-    description="",
-    long_description=open("README.md").read(),
-    long_description_content_type="text/markdown",
-    url="",
-    pyhon_requires=">=3.12",
-)