entroscope 0.1.0__tar.gz

entroscope-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: entroscope
+Version: 0.1.0
+Summary: The definitive entropy toolkit for time series data
+Author: entroscope contributors
+License: MIT
+Project-URL: Homepage, https://github.com/entroscope/entroscope
+Keywords: entropy,time-series,shannon,permutation,spectral
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# entroscope
+
+[![CI](https://github.com/entroscope/entroscope/actions/workflows/ci.yml/badge.svg)](https://github.com/entroscope/entroscope/actions/workflows/ci.yml)
+
+**The definitive entropy toolkit for time series data.**
+
+`pip install entroscope` and get every entropy measure you'd ever need, with one
+consistent interface that works directly on pandas Series and numpy arrays.
+
+Born from [NextOnMenu](https://nextonmenu.com), where Shannon entropy of food-trend
+search interest had to be computed by hand. entroscope makes that a one-liner.
+
+## Install
+
+```bash
+pip install entroscope
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from entroscope import shannon
+
+s = pd.Series([10, 20, 15, 80, 90, 85, 88, 92])
+shannon.compute(s)              # single entropy value
+shannon.rolling(s, window=20)   # rolling entropy over time
+shannon.delta(s, window=20)     # rate of change
+shannon.plot(s, window=20)      # matplotlib Figure
+```
+
+## Measures
+
+shannon · permutation · sample · approximate · spectral · differential · multiscale
+
+Every measure shares the same API: `compute`, `rolling`, `delta`, `plot`
+(`normalized` where a theoretical maximum exists). Series in → Series out
+(index preserved); ndarray in → ndarray out.
+
+| Method        | Returns                              |
+| ------------- | ------------------------------------ |
+| `compute`     | `float`                              |
+| `rolling`     | Series/ndarray, same length          |
+| `delta`       | Series/ndarray (first difference)    |
+| `normalized`  | `float` in [0, 1] (where defined)    |
+| `plot`        | `matplotlib.figure.Figure`           |
+
+## Real-world example — food-trend analysis (NextOnMenu)
+
+```python
+import pandas as pd
+from entroscope import shannon
+
+matcha_trends = pd.read_csv("matcha_trends.csv")["interest"]
+shannon.plot(matcha_trends, window=20, title="Matcha — entropy over time")
+# entropy drops before a trend goes mainstream
+```
+
+A sustained drop in rolling Shannon entropy means search interest is becoming
+concentrated/structured rather than noisy — an early signal of a trend.
+
+## License
+
+MIT

entroscope-0.1.0/README.md

@@ -0,0 +1,64 @@
+# entroscope
+
+[![CI](https://github.com/entroscope/entroscope/actions/workflows/ci.yml/badge.svg)](https://github.com/entroscope/entroscope/actions/workflows/ci.yml)
+
+**The definitive entropy toolkit for time series data.**
+
+`pip install entroscope` and get every entropy measure you'd ever need, with one
+consistent interface that works directly on pandas Series and numpy arrays.
+
+Born from [NextOnMenu](https://nextonmenu.com), where Shannon entropy of food-trend
+search interest had to be computed by hand. entroscope makes that a one-liner.
+
+## Install
+
+```bash
+pip install entroscope
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from entroscope import shannon
+
+s = pd.Series([10, 20, 15, 80, 90, 85, 88, 92])
+shannon.compute(s)              # single entropy value
+shannon.rolling(s, window=20)   # rolling entropy over time
+shannon.delta(s, window=20)     # rate of change
+shannon.plot(s, window=20)      # matplotlib Figure
+```
+
+## Measures
+
+shannon · permutation · sample · approximate · spectral · differential · multiscale
+
+Every measure shares the same API: `compute`, `rolling`, `delta`, `plot`
+(`normalized` where a theoretical maximum exists). Series in → Series out
+(index preserved); ndarray in → ndarray out.
+
+| Method        | Returns                              |
+| ------------- | ------------------------------------ |
+| `compute`     | `float`                              |
+| `rolling`     | Series/ndarray, same length          |
+| `delta`       | Series/ndarray (first difference)    |
+| `normalized`  | `float` in [0, 1] (where defined)    |
+| `plot`        | `matplotlib.figure.Figure`           |
+
+## Real-world example — food-trend analysis (NextOnMenu)
+
+```python
+import pandas as pd
+from entroscope import shannon
+
+matcha_trends = pd.read_csv("matcha_trends.csv")["interest"]
+shannon.plot(matcha_trends, window=20, title="Matcha — entropy over time")
+# entropy drops before a trend goes mainstream
+```
+
+A sustained drop in rolling Shannon entropy means search interest is becoming
+concentrated/structured rather than noisy — an early signal of a trend.
+
+## License
+
+MIT

entroscope-0.1.0/entroscope/__init__.py

@@ -0,0 +1,16 @@
+"""entroscope — the definitive entropy toolkit for time series data."""
+
+from . import shannon, permutation, spectral, sample, approximate, differential, multiscale
+from .utils import plot
+
+__version__ = "0.1.0"
+__all__ = [
+    "shannon",
+    "permutation",
+    "spectral",
+    "sample",
+    "approximate",
+    "differential",
+    "multiscale",
+    "plot",
+]

entroscope-0.1.0/entroscope/_core.py

@@ -0,0 +1,81 @@
+"""Core engine: input coercion, output wrapping, rolling/delta drivers, plotting.
+
+Every measure module delegates its standard methods here so the
+"Series in -> Series out, array in -> array out" contract and the windowing
+logic live in exactly one place.
+"""
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless-safe; never opens a window
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+import pandas as pd  # noqa: E402
+
+from .utils.windows import sliding_windows  # noqa: E402
+
+
+def as_array(x):
+    """Coerce input to a 1-D float ndarray, returning (array, index_or_None)."""
+    if isinstance(x, pd.Series):
+        index = x.index
+        arr = x.to_numpy(dtype=float)
+    else:
+        index = None
+        arr = np.asarray(x, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError("input must be 1-dimensional")
+    if arr.size == 0:
+        raise ValueError("input is empty")
+    return arr, index
+
+
+def wrap(values, index):
+    """Wrap a result array as a Series (if index given) or return the ndarray."""
+    values = np.asarray(values, dtype=float)
+    if index is not None:
+        return pd.Series(values, index=index)
+    return values
+
+
+def rolling(x, window, kernel, **params):
+    """Apply `kernel` over each full sliding window.
+
+    Output has the same length as the input; positions before the first full
+    window are NaN. Returns a Series (preserving index) if `x` was a Series.
+    """
+    arr, index = as_array(x)
+    n = len(arr)
+    if window <= 0:
+        raise ValueError("window must be a positive integer")
+    if window > n:
+        raise ValueError(f"window ({window}) is larger than series length ({n})")
+    out = np.full(n, np.nan)
+    for end, w in zip(range(window, n + 1), sliding_windows(arr, window)):
+        out[end - 1] = kernel(w, **params)
+    return wrap(out, index)
+
+
+def delta(x, window, kernel, **params):
+    """First difference of the rolling entropy."""
+    roll = rolling(x, window, kernel, **params)
+    if isinstance(roll, pd.Series):
+        return roll.diff()
+    out = np.full_like(roll, np.nan)
+    out[1:] = np.diff(roll)
+    return out
+
+
+def make_plot(x, window, kernel, *, title=None, ylabel="entropy", **params):
+    """Build and return a Figure of rolling entropy. Never calls plt.show()."""
+    roll = rolling(x, window, kernel, **params)
+    fig, ax = plt.subplots(figsize=(10, 4))
+    if isinstance(roll, pd.Series):
+        ax.plot(roll.index, roll.to_numpy())
+    else:
+        ax.plot(range(len(roll)), roll)
+    ax.set_title(title or f"Rolling {ylabel} (window={window})")
+    ax.set_xlabel("position")
+    ax.set_ylabel(ylabel)
+    fig.tight_layout()
+    return fig

entroscope-0.1.0/entroscope/approximate.py

@@ -0,0 +1,51 @@
+"""Approximate entropy (ApEn) — regularity measure, less noise-sensitive."""
+
+import numpy as np
+
+from . import _core
+
+
+def _phi(values, m, tol):
+    """Mean of log(fraction of templates within `tol`) over length-m templates."""
+    n = len(values)
+    templates = np.array([values[i : i + m] for i in range(n - m + 1)])
+    counts = np.empty(len(templates))
+    for i in range(len(templates)):
+        dist = np.max(np.abs(templates - templates[i]), axis=1)
+        counts[i] = np.count_nonzero(dist <= tol) / len(templates)
+    return float(np.mean(np.log(counts)))
+
+
+def _kernel(values, m=2, r=0.2):
+    """Approximate entropy: phi(m) - phi(m+1)."""
+    if r <= 0:
+        raise ValueError("r must be positive")
+    if m < 1:
+        raise ValueError("m must be >= 1")
+    values = np.asarray(values, dtype=float)
+    n = len(values)
+    if n <= m + 1:
+        raise ValueError("series too short for given m")
+    tol = r * np.std(values)
+    if tol == 0:
+        return 0.0
+    return float(_phi(values, m, tol) - _phi(values, m + 1, tol))
+
+
+def compute(series, m=2, r=0.2):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, m=m, r=r)
+
+
+def rolling(series, window=50, m=2, r=0.2):
+    return _core.rolling(series, window, _kernel, m=m, r=r)
+
+
+def delta(series, window=50, m=2, r=0.2):
+    return _core.delta(series, window, _kernel, m=m, r=r)
+
+
+def plot(series, window=50, m=2, r=0.2, title=None):
+    return _core.make_plot(
+        series, window, _kernel, m=m, r=r, title=title, ylabel="approximate entropy"
+    )

entroscope-0.1.0/entroscope/differential.py

@@ -0,0 +1,43 @@
+"""Differential entropy — continuous entropy via a fitted distribution."""
+
+import numpy as np
+from scipy import stats
+
+from . import _core
+
+
+def _kernel(values, dist="normal"):
+    """Differential entropy (nats). dist in {'normal', 'kde'}."""
+    values = np.asarray(values, dtype=float)
+    if dist == "normal":
+        var = np.var(values)
+        if var == 0:
+            return float("-inf")  # degenerate: zero-width distribution
+        return float(0.5 * np.log(2 * np.pi * np.e * var))
+    if dist == "kde":
+        if np.std(values) == 0:
+            return float("-inf")
+        kde = stats.gaussian_kde(values)
+        density = kde(values)
+        density = density[density > 0]
+        return float(-np.mean(np.log(density)))
+    raise ValueError(f"unknown dist {dist!r}; expected 'normal' or 'kde'")
+
+
+def compute(series, dist="normal"):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, dist=dist)
+
+
+def rolling(series, window=50, dist="kde"):
+    return _core.rolling(series, window, _kernel, dist=dist)
+
+
+def delta(series, window=50, dist="kde"):
+    return _core.delta(series, window, _kernel, dist=dist)
+
+
+def plot(series, window=50, dist="kde", title=None):
+    return _core.make_plot(
+        series, window, _kernel, dist=dist, title=title, ylabel="differential entropy"
+    )

entroscope-0.1.0/entroscope/multiscale.py

@@ -0,0 +1,45 @@
+"""Multiscale entropy — sample entropy across coarse-grained time scales."""
+
+import matplotlib.pyplot as plt
+
+from . import _core, sample
+
+
+def _coarse_grain(values, scale):
+    """Average non-overlapping blocks of length `scale`."""
+    n = len(values) // scale
+    trimmed = values[: n * scale]
+    return trimmed.reshape(n, scale).mean(axis=1)
+
+
+def compute(series, scales=range(1, 10), method="sample"):
+    """Return {scale: entropy} by coarse-graining then applying `method`.
+
+    Scales that coarse-grain the series below sample entropy's minimum
+    length are skipped (omitted from the result).
+    """
+    if method != "sample":
+        raise ValueError("only method='sample' is supported")
+    arr, _ = _core.as_array(series)
+    result = {}
+    for scale in scales:
+        if scale == 1:
+            grained = arr
+        else:
+            grained = _coarse_grain(arr, scale)
+        if len(grained) < 4:  # sample entropy needs n > m+1 (m=2 default)
+            continue
+        result[int(scale)] = sample.compute(grained)
+    return result
+
+
+def plot(series, scales=range(1, 10), title=None):
+    """Plot the complexity profile (entropy vs. scale)."""
+    profile = compute(series, scales=scales)
+    fig, ax = plt.subplots(figsize=(8, 4))
+    ax.plot(list(profile.keys()), list(profile.values()), marker="o")
+    ax.set_title(title or "Multiscale entropy")
+    ax.set_xlabel("scale")
+    ax.set_ylabel("sample entropy")
+    fig.tight_layout()
+    return fig

entroscope-0.1.0/entroscope/permutation.py

@@ -0,0 +1,67 @@
+"""Permutation entropy — complexity from ordinal patterns (Bandt & Pompe)."""
+
+import math
+from itertools import permutations
+
+import numpy as np
+
+from . import _core
+from .utils import normalize
+
+
+def _kernel(values, order=3, delay=1):
+    """Permutation entropy (base 2) of ordinal patterns of length `order`."""
+    if order < 2:
+        raise ValueError("order must be >= 2")
+    if delay < 1:
+        raise ValueError("delay must be >= 1")
+    values = np.asarray(values, dtype=float)
+    n = len(values)
+    span = delay * (order - 1)
+    if n - span <= 0:
+        raise ValueError("series too short for given order/delay")
+    perm_index = {p: i for i, p in enumerate(permutations(range(order)))}
+    counts = np.zeros(len(perm_index))
+    for i in range(n - span):
+        window = values[i : i + span + 1 : delay]
+        pattern = tuple(np.argsort(window, kind="stable"))
+        counts[perm_index[pattern]] += 1
+    total = counts.sum()
+    p = counts[counts > 0] / total
+    return float(-np.sum(p * np.log2(p)))
+
+
+def _check_window(window, order, delay):
+    """Raise ValueError if window is too small for the given order/delay."""
+    span = delay * (order - 1)
+    if window <= span:
+        raise ValueError(f"window ({window}) must exceed delay*(order-1) = {span}")
+
+
+def compute(series, order=3, delay=1):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, order=order, delay=delay)
+
+
+def rolling(series, window=20, order=3, delay=1):
+    _check_window(window, order, delay)
+    return _core.rolling(series, window, _kernel, order=order, delay=delay)
+
+
+def delta(series, window=20, order=3, delay=1):
+    _check_window(window, order, delay)
+    return _core.delta(series, window, _kernel, order=order, delay=delay)
+
+
+def normalized(series, order=3, delay=1):
+    """Entropy scaled to [0, 1] by log2(order!)."""
+    return normalize.by_max(
+        compute(series, order=order, delay=delay), math.log2(math.factorial(order))
+    )
+
+
+def plot(series, window=20, order=3, delay=1, title=None):
+    _check_window(window, order, delay)
+    return _core.make_plot(
+        series, window, _kernel, order=order, delay=delay, title=title, ylabel="permutation entropy"
+    )

entroscope-0.1.0/entroscope/sample.py

@@ -0,0 +1,54 @@
+"""Sample entropy (SampEn) — regularity/predictability of a time series."""
+
+import numpy as np
+
+from . import _core
+
+
+def _count_matches(values, m, tol):
+    """Count template-vector pairs (length m) within Chebyshev distance `tol`."""
+    n = len(values)
+    templates = np.array([values[i : i + m] for i in range(n - m + 1)])
+    count = 0
+    for i in range(len(templates) - 1):
+        dist = np.max(np.abs(templates[i + 1 :] - templates[i]), axis=1)
+        count += np.count_nonzero(dist <= tol)
+    return count
+
+
+def _kernel(values, m=2, r=0.2):
+    """Sample entropy: -ln(A/B) of length-(m+1) vs length-m matches."""
+    if r <= 0:
+        raise ValueError("r must be positive")
+    if m < 1:
+        raise ValueError("m must be >= 1")
+    values = np.asarray(values, dtype=float)
+    n = len(values)
+    if n <= m + 1:
+        raise ValueError("series too short for given m")
+    tol = r * np.std(values)
+    if tol == 0:
+        return 0.0  # constant signal: perfectly regular
+    b = _count_matches(values, m, tol)
+    a = _count_matches(values, m + 1, tol)
+    if b == 0 or a == 0:
+        # no regularity detected; return a large-but-finite ceiling
+        return float(np.log((n - m) * (n - m - 1)))
+    return float(-np.log(a / b))
+
+
+def compute(series, m=2, r=0.2):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, m=m, r=r)
+
+
+def rolling(series, window=50, m=2, r=0.2):
+    return _core.rolling(series, window, _kernel, m=m, r=r)
+
+
+def delta(series, window=50, m=2, r=0.2):
+    return _core.delta(series, window, _kernel, m=m, r=r)
+
+
+def plot(series, window=50, m=2, r=0.2, title=None):
+    return _core.make_plot(series, window, _kernel, m=m, r=r, title=title, ylabel="sample entropy")

entroscope-0.1.0/entroscope/shannon.py

@@ -0,0 +1,53 @@
+"""Shannon entropy — classic information entropy over a binned distribution."""
+
+import numpy as np
+
+from . import _core
+from .utils import normalize
+
+
+def _kernel(values, bins=10):
+    """Shannon entropy (base 2) of `values` histogrammed into `bins`."""
+    if bins <= 0:
+        raise ValueError("bins must be a positive integer")
+    values = np.asarray(values, dtype=float)
+    counts, _ = np.histogram(values, bins=bins)
+    total = counts.sum()
+    if total == 0:
+        return 0.0
+    p = counts[counts > 0] / total
+    return float(-np.sum(p * np.log2(p)))
+
+
+def compute(series, bins=10):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, bins=bins)
+
+
+def rolling(series, window=20, bins=10):
+    return _core.rolling(series, window, _kernel, bins=bins)
+
+
+def delta(series, window=20, bins=10):
+    return _core.delta(series, window, _kernel, bins=bins)
+
+
+def normalized(series, bins=10):
+    """Entropy scaled to [0, 1] by the maximum possible (log2(bins))."""
+    return normalize.by_max(compute(series, bins=bins), np.log2(bins))
+
+
+def geographic(region_df, col="interest"):
+    """Shannon entropy of a spatial distribution (e.g. Google Trends by region)."""
+    values = np.asarray(region_df[col], dtype=float)
+    total = values.sum()
+    if total == 0:
+        return 0.0
+    p = values[values > 0] / total
+    return float(-np.sum(p * np.log2(p)))
+
+
+def plot(series, window=20, bins=10, title=None):
+    return _core.make_plot(
+        series, window, _kernel, bins=bins, title=title, ylabel="Shannon entropy"
+    )

entroscope-0.1.0/entroscope/spectral.py

@@ -0,0 +1,52 @@
+"""Spectral entropy — Shannon entropy of the normalized power spectrum."""
+
+import numpy as np
+from scipy import signal as _signal
+
+from . import _core
+from .utils import normalize
+
+
+def _psd(values, sf):
+    """Return the (positive-frequency) power spectral density of `values`."""
+    values = np.asarray(values, dtype=float)
+    values = values - values.mean()
+    freqs, psd = _signal.periodogram(values, fs=sf)
+    return freqs, psd
+
+
+def _kernel(values, sf=1.0):
+    """Spectral entropy (base 2) of the normalized power spectrum."""
+    _, psd = _psd(values, sf)
+    total = psd.sum()
+    if total == 0:
+        return 0.0
+    p = psd[psd > 0] / total
+    return float(-np.sum(p * np.log2(p)))
+
+
+def compute(series, sf=1.0):
+    arr, _ = _core.as_array(series)
+    return _kernel(arr, sf=sf)
+
+
+def rolling(series, window=50, sf=1.0):
+    return _core.rolling(series, window, _kernel, sf=sf)
+
+
+def delta(series, window=50, sf=1.0):
+    return _core.delta(series, window, _kernel, sf=sf)
+
+
+def normalized(series, sf=1.0):
+    """Entropy scaled to [0, 1] by log2(number of frequency bins)."""
+    arr, _ = _core.as_array(series)
+    freqs, _psd_vals = _psd(arr, sf)
+    n_bins = int(np.count_nonzero(_psd_vals > 0))
+    if n_bins <= 1:
+        return 0.0
+    return normalize.by_max(_kernel(arr, sf=sf), np.log2(n_bins))
+
+
+def plot(series, window=50, sf=1.0, title=None):
+    return _core.make_plot(series, window, _kernel, sf=sf, title=title, ylabel="spectral entropy")

entroscope-0.1.0/entroscope/utils/normalize.py

@@ -0,0 +1,13 @@
+"""Normalization helpers: scale an entropy value into [0, 1]."""
+
+
+def by_max(value, max_value):
+    """Return value / max_value clipped to [0, 1]; 0.0 if max_value == 0."""
+    if max_value == 0:
+        return 0.0
+    ratio = value / max_value
+    if ratio < 0.0:
+        return 0.0
+    if ratio > 1.0:
+        return 1.0
+    return float(ratio)