complexeva 0.2.1__tar.gz → 0.2.3__tar.gz

{complexeva-0.2.1 → complexeva-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: complexeva
-Version: 0.2.1
+Version: 0.2.3
 Home-page: 
 Author: Don Yin
 Author-email: don_yin@outlook.com

{complexeva-0.2.1 → complexeva-0.2.3}/complexeva/sequence/__init__.py

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

complexeva-0.2.3/complexeva/sequence/higuchi.py

@@ -0,0 +1,122 @@
+#!/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=64):
+    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=64):
+    """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_envelope(X, k_max=64):
+    """
+    Calculate HFD on the envelope (instantaneous amplitude) of the Hilbert transform.
+    This measures complexity of amplitude modulations.
+    """
+    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
+    analytic_signal = hilbert(X)
+    envelope = numpy.abs(analytic_signal)
+    return hfd(envelope, k_max=k_max)
+
+
+def hfd_hilbert_transform(X, k_max=64):
+    """
+    Calculate HFD on the actual Hilbert transform (imaginary part of analytic signal).
+    This applies fractal analysis to the 90-degree phase-shifted version of the signal.
+    """
+    assert X.ndim == 1, f"X must be a 1d numpy array, got shape {X.shape}"
+    analytic_signal = hilbert(X)
+    hilbert_transform = numpy.imag(analytic_signal)
+    return hfd(hilbert_transform, k_max=k_max)
+
+
+def hfd_hilbert_frequency(X, k_max=64):
+    """
+    Calculate HFD on the instantaneous frequency from Hilbert transform.
+    This measures complexity of frequency modulations (your original implementation).
+    """
+    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)
+
+
+# Keep the original as an alias for backward compatibility
+def hfd_hilbert(X, k_max=64):
+    """
+    Calculate Higuchi Fractal Dimension on the Hilbert-transformed BOLD time-series.
+
+    Based on research literature context, this applies HFD to the envelope
+    (instantaneous amplitude) of the Hilbert transform, which captures temporal
+    brain activity patterns in the BOLD signal amplitude over time.
+
+    Args:
+        X (numpy.ndarray): Input 1D BOLD time-series
+        k_max (int): Maximum k value for HFD calculation
+
+    Returns:
+        float: Higuchi Fractal Dimension of the Hilbert-transformed signal
+    """
+    return hfd_hilbert_envelope(X, 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 variants
+    start_time = time.time()
+    complexity_envelope = hfd_hilbert_envelope(signal)
+    envelope_time = time.time() - start_time
+
+    start_time = time.time()
+    complexity_transform = hfd_hilbert_transform(signal)
+    transform_time = time.time() - start_time
+
+    start_time = time.time()
+    complexity_frequency = hfd_hilbert_frequency(signal)
+    frequency_time = time.time() - start_time
+
+    print(f"Plain HFD: {complexity_plain:.6f}, Time: {plain_time:.6f}s")
+    print(f"Hilbert Envelope HFD: {complexity_envelope:.6f}, Time: {envelope_time:.6f}s")
+    print(f"Hilbert Transform HFD: {complexity_transform:.6f}, Time: {transform_time:.6f}s")
+    print(f"Hilbert Frequency HFD: {complexity_frequency:.6f}, Time: {frequency_time:.6f}s")
+    print(f"\nHilbert/Plain speed ratios:")
+    print(f"  Envelope: {envelope_time/plain_time:.2f}x")
+    print(f"  Transform: {transform_time/plain_time:.2f}x")
+    print(f"  Frequency: {frequency_time/plain_time:.2f}x")

complexeva-0.2.3/complexeva/sequence/lempel_ziv.py

@@ -0,0 +1,266 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+import numpy
+from scipy.signal import hilbert
+import time
+from numba import njit
+
+
+@njit
+def lempel_ziv_core(binary_array):
+    """
+    Core Lempel-Ziv complexity algorithm optimized with numba.
+    Works on binary arrays of 0s and 1s (integers).
+
+    Args:
+        binary_array: numpy array of 0s and 1s (integers)
+
+    Returns:
+        int: The number of distinct patterns (complexity measure)
+    """
+    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:
+            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
+
+
+@njit
+def time_series_to_binary_core(vector, threshold, method_idx):
+    """
+    Core binarization function optimized with numba.
+
+    Args:
+        vector: numpy array of numeric values
+        threshold: threshold value for binarization
+        method_idx: 0=mean, 1=median, 2=diff
+
+    Returns:
+        numpy array of 0s and 1s (integers)
+    """
+    if method_idx == 2:  # diff method
+        diffs = numpy.diff(vector)
+        return (diffs > 0).astype(numpy.int32)
+    else:  # mean or median method
+        return (vector > threshold).astype(numpy.int32)
+
+
+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.
+
+    Args:
+        time_series: Either a binary string (e.g., "1001110") or numeric array to be converted
+        method: Binarization method if time_series is numeric ('median', 'mean', 'diff')
+
+    Returns: int: The number of distinct patterns (complexity measure)
+    """
+    # Handle binary string input
+    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)
+        return lempel_ziv_core(binary_array)
+
+    # Handle numeric input
+    vector = numpy.array(time_series, dtype=numpy.float64)
+
+    if method == "diff":
+        binary_array = time_series_to_binary_core(vector, 0.0, 2)  # threshold not used for diff
+    elif method == "mean":
+        threshold = numpy.mean(vector)
+        binary_array = time_series_to_binary_core(vector, threshold, 0)
+    elif method == "median":
+        threshold = numpy.median(vector)
+        binary_array = time_series_to_binary_core(vector, threshold, 1)
+    else:
+        raise ValueError("Method must be 'mean', 'median', or 'diff'.")
+
+    return lempel_ziv_core(binary_array)
+
+
+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
+    """
+
+    # If input is already a binary string, return it as-is
+    if isinstance(vector, str) and all(c in "01" for c in vector):
+        return vector
+
+    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
+
+
+def lempel_ziv_hilbert_envelope(time_series, method="median", **kwargs):
+    """
+    Calculate Lempel-Ziv complexity on the envelope (instantaneous amplitude) of the Hilbert transform.
+    This measures complexity of amplitude modulations.
+
+    Args:
+        time_series (numpy.ndarray): Input 1D signal
+        method (str): Binarization method ('median', 'mean', 'diff')
+        **kwargs: Additional arguments
+
+    Returns:
+        int: Lempel-Ziv complexity of the Hilbert-transformed signal
+    """
+    time_series = numpy.array(time_series)
+    assert time_series.ndim == 1, f"time_series must be a 1d numpy array, got shape {time_series.shape}"
+    analytic_signal = hilbert(time_series)
+    envelope = numpy.abs(analytic_signal)
+    return lempel_ziv(envelope, method=method, **kwargs)
+
+
+def lempel_ziv_hilbert_transform(time_series, method="median", **kwargs):
+    """
+    Calculate Lempel-Ziv complexity on the actual Hilbert transform (imaginary part of analytic signal).
+    This applies complexity analysis to the 90-degree phase-shifted version of the signal.
+
+    Args:
+        time_series (numpy.ndarray): Input 1D signal
+        method (str): Binarization method ('median', 'mean', 'diff')
+        **kwargs: Additional arguments
+
+    Returns:
+        int: Lempel-Ziv complexity of the Hilbert transform
+    """
+    time_series = numpy.array(time_series)
+    assert time_series.ndim == 1, f"time_series must be a 1d numpy array, got shape {time_series.shape}"
+    analytic_signal = hilbert(time_series)
+    hilbert_transform = numpy.imag(analytic_signal)
+    return lempel_ziv(hilbert_transform, method=method, **kwargs)
+
+
+def lempel_ziv_hilbert_frequency(time_series, method="median", **kwargs):
+    """
+    Calculate Lempel-Ziv complexity on the instantaneous frequency from Hilbert transform.
+    This measures complexity of frequency modulations.
+
+    Args:
+        time_series (numpy.ndarray): Input 1D signal
+        method (str): Binarization method ('median', 'mean', 'diff')
+        **kwargs: Additional arguments
+
+    Returns:
+        int: Lempel-Ziv complexity of the instantaneous frequency
+    """
+    time_series = numpy.array(time_series)
+    assert time_series.ndim == 1, f"time_series must be a 1d numpy array, got shape {time_series.shape}"
+    analytic_signal = hilbert(time_series)
+    instantaneous_phase = numpy.angle(analytic_signal)
+    instantaneous_freq = numpy.diff(instantaneous_phase)
+    instantaneous_freq = numpy.append(instantaneous_freq, instantaneous_freq[-1])
+    return lempel_ziv(instantaneous_freq, method=method, **kwargs)
+
+
+def lempel_ziv_hilbert(time_series, method="median", **kwargs):
+    """
+    Calculate Lempel-Ziv complexity on the Hilbert-transformed BOLD time-series.
+
+    Based on research literature context, this applies LZ complexity to the envelope
+    (instantaneous amplitude) of the Hilbert transform, which captures temporal
+    brain activity patterns in the BOLD signal amplitude over time.
+
+    Args:
+        time_series (numpy.ndarray): Input 1D BOLD time-series
+        method (str): Binarization method ('median', 'mean', 'diff')
+        **kwargs: Additional arguments
+
+    Returns:
+        int: Lempel-Ziv complexity of the Hilbert-transformed signal
+    """
+    return lempel_ziv_hilbert_envelope(time_series, method=method, **kwargs)
+
+
+if __name__ == "__main__":
+    # Test with synthetic signal
+    signal = numpy.random.rand(1000)
+
+    print("Testing Lempel-Ziv complexity methods:")
+    print("=" * 50)
+
+    # Test plain LZ
+    start_time = time.time()
+    lz_plain = lempel_ziv(signal, method="median")
+    plain_time = time.time() - start_time
+
+    # Test Hilbert LZ variants
+    start_time = time.time()
+    lz_envelope = lempel_ziv_hilbert_envelope(signal, method="median")
+    envelope_time = time.time() - start_time
+
+    start_time = time.time()
+    lz_transform = lempel_ziv_hilbert_transform(signal, method="median")
+    transform_time = time.time() - start_time
+
+    start_time = time.time()
+    lz_frequency = lempel_ziv_hilbert_frequency(signal, method="median")
+    frequency_time = time.time() - start_time
+
+    print(f"Plain LZ: {lz_plain}, Time: {plain_time:.6f}s")
+    print(f"Hilbert Envelope LZ: {lz_envelope}, Time: {envelope_time:.6f}s")
+    print(f"Hilbert Transform LZ: {lz_transform}, Time: {transform_time:.6f}s")
+    print(f"Hilbert Frequency LZ: {lz_frequency}, Time: {frequency_time:.6f}s")
+    print(f"\nHilbert/Plain speed ratios:")
+    print(f"  Envelope: {envelope_time/plain_time:.2f}x")
+    print(f"  Transform: {transform_time/plain_time:.2f}x")
+    print(f"  Frequency: {frequency_time/plain_time:.2f}x")
+
+    # Test original functionality
+    print(f"\nOriginal test:")
+    sequence = "1001111011000010"
+    print(f"LZ of binary sequence '{sequence}': {lempel_ziv(sequence)}")
+
+    # Additional benchmark: test the same signal multiple times to see compiled performance
+    print(f"\nPerformance after compilation (running same signal 5 times):")
+    times = []
+    for i in range(5):
+        start_time = time.time()
+        lz_result = lempel_ziv(signal, method="median")
+        elapsed = time.time() - start_time
+        times.append(elapsed)
+        print(f"  Run {i+1}: {lz_result}, Time: {elapsed:.6f}s")
+
+    print(f"Average compiled time: {numpy.mean(times):.6f}s")
+    print(f"Min compiled time: {numpy.min(times):.6f}s")

{complexeva-0.2.1 → complexeva-0.2.3}/complexeva.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: complexeva
-Version: 0.2.1
+Version: 0.2.3
 Home-page: 
 Author: Don Yin
 Author-email: don_yin@outlook.com

{complexeva-0.2.1 → complexeva-0.2.3}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="complexeva",
-    version="0.2.1",
+    version="0.2.3",
     packages=find_packages(),
     install_requires=[],
     author="Don Yin",

complexeva-0.2.1/complexeva/sequence/higuchi.py

@@ -1,39 +0,0 @@
-#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
-
-
-import numpy
-from numba import njit
-
-
-@njit
-def compute_L_x(X, k_max=16):
-    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]
-
-
-if __name__ == "__main__":
-    signal = numpy.random.rand(1000)  # shape: (1000,)
-    complexity = hfd(signal)
-    print(complexity)

complexeva-0.2.1/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))