entroscope 0.2.0__tar.gz → 0.3.0__tar.gz

{entroscope-0.2.0 → entroscope-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: entroscope
-Version: 0.2.0
+Version: 0.3.0
 Summary: The definitive entropy toolkit for time series data
 Author: entroscope contributors
 License: MIT
-Project-URL: Homepage, https://github.com/entroscope/entroscope
+Project-URL: Homepage, https://github.com/Par-python/entroscope
 Keywords: entropy,time-series,shannon,permutation,spectral
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -27,21 +27,41 @@ Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: matplotlib
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn; extra == "sklearn"
+Provides-Extra: polars
+Requires-Dist: polars; extra == "polars"
+Provides-Extra: reference
+Requires-Dist: antropy; extra == "reference"
+Requires-Dist: EntropyHub; extra == "reference"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs<2; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff==0.16.7; extra == "dev"
+Requires-Dist: scikit-learn; extra == "dev"
+Requires-Dist: polars; extra == "dev"
 Dynamic: license-file
 
 # entroscope
 
-[![PyPI version](https://img.shields.io/pypi/v/entroscope.svg)](https://pypi.org/project/entroscope/)
-[![Python versions](https://img.shields.io/pypi/pyversions/entroscope.svg)](https://pypi.org/project/entroscope/)
-[![CI](https://github.com/Par-python/entroscope/actions/workflows/ci.yml/badge.svg)](https://github.com/Par-python/entroscope/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://img.shields.io/github/actions/workflow/status/Par-python/entroscope/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI&labelColor=24292e)](https://github.com/Par-python/entroscope/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/entroscope.svg?style=flat-square&logo=pypi&logoColor=white&labelColor=24292e&color=blue)](https://pypi.org/project/entroscope/)
+[![Downloads](https://img.shields.io/pepy/dt/entroscope.svg?style=flat-square&logo=python&logoColor=white&labelColor=24292e&color=blue)](https://pepy.tech/project/entroscope)
+[![Python](https://img.shields.io/pypi/pyversions/entroscope.svg?style=flat-square&logo=python&logoColor=white&labelColor=24292e&color=blue)](https://pypi.org/project/entroscope/)
+[![Stars](https://img.shields.io/github/stars/Par-python/entroscope.svg?style=flat-square&logo=github&logoColor=white&labelColor=24292e&color=yellow)](https://github.com/Par-python/entroscope/stargazers)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=24292e)](https://opensource.org/licenses/MIT)
 
-**The definitive entropy toolkit for time series data.** Seven entropy measures,
-one consistent interface, working directly on pandas Series and numpy arrays.
+**The definitive entropy toolkit for time series data.** Nine entropy measures,
+one consistent interface, working directly on pandas and polars Series and numpy
+arrays. Results are [validated against antropy, EntropyHub and scipy](#validated-results).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Par-python/entroscope/master/docs/assets/entropy-drop-dark.png">
+  <img alt="Two stacked charts. Top: a synthetic signal that is random noise until step 180, then a regular cycle. Bottom: its rolling spectral entropy, high during the noise and falling sharply shortly after step 180." src="https://raw.githubusercontent.com/Par-python/entroscope/master/docs/assets/entropy-drop-light.png">
+</picture>
 
 It started in [NextOnMenu](https://github.com/Par-python/nextonmenu): a falling
 Shannon entropy of a food's regional search interest turned out to be an early
@@ -60,7 +80,7 @@ from entroscope import shannon
 
 s = pd.Series([10, 20, 15, 80, 90, 85, 88, 92])
 
-shannon.compute(s)              # 0.73 (a single entropy value)
+shannon.compute(s)              # 1.75 (a single entropy value, in bits)
 shannon.rolling(s, window=20)   # rolling entropy over time (a Series)
 shannon.delta(s, window=20)     # rate of change of entropy
 shannon.normalized(s)           # entropy scaled to [0, 1]
@@ -81,7 +101,7 @@ the standard environment variable:
 export MPLBACKEND=Agg        # or, in a Dockerfile:  ENV MPLBACKEND=Agg
 ```
 
-## The seven measures
+## The nine measures
 
 | Measure          | Import                    | Captures                                         |
 | ---------------- | ------------------------- | ------------------------------------------------ |
@@ -92,6 +112,8 @@ export MPLBACKEND=Agg        # or, in a Dockerfile:  ENV MPLBACKEND=Agg
 | **Spectral**     | `entroscope.spectral`     | Spread of the power spectrum (frequency domain)  |
 | **Differential** | `entroscope.differential` | Continuous entropy via a fitted distribution     |
 | **Multiscale**   | `entroscope.multiscale`   | Sample entropy across coarse-grained time scales |
+| **Transfer**     | `entroscope.transfer`     | Directional information flow X → Y (KSG/binned)  |
+| **Divergence**   | `entroscope.divergence`   | KL and Jensen-Shannon distance between samples   |
 
 ## One consistent API
 
@@ -108,6 +130,11 @@ Every measure exposes the same methods, so switching measures is a one-word chan
 Shannon additionally provides `geographic(df, col=...)` for spatial distributions
 (e.g. search interest by region). Multiscale provides `compute` and `plot`.
 
+The two-input measures take a pair of series. `transfer.compute(x, y)` (plus
+`rolling`, `delta`, `plot`) estimates how much `x`'s past tells you about `y`'s
+future; `divergence.kl(p, q)` and `divergence.js(p, q)` (plus `plot`) compare two
+samples' distributions over shared bins.
+
 ## Visualization
 
 ```python
@@ -126,6 +153,43 @@ plot.drop_events(s, measure="shannon", window=20, threshold=0.4)
 All plot functions return a `matplotlib.figure.Figure` and never call
 `plt.show()`, so they're safe in scripts, notebooks, and CI alike.
 
+## Integrations
+
+**polars**: pass a polars Series anywhere a pandas Series works; rolling and
+delta results come back as a polars Series with the same name.
+
+**scikit-learn**: `EntropyFeatures` turns time-series windows into entropy
+features inside a pipeline:
+
+```python
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.pipeline import make_pipeline
+from entroscope.features import EntropyFeatures
+
+# windows: shape (n_windows, window_length); one row per window
+model = make_pipeline(EntropyFeatures(), RandomForestClassifier())
+model.fit(windows, labels)
+```
+
+Install the optional dependencies with `pip install "entroscope[sklearn]"` or
+`"entroscope[polars]"`. See the [integrations guide](docs/integrations.md).
+
+## Validated results
+
+Every measure is checked against an independent implementation, on every CI run:
+
+| Measure                          | Checked against                                   |
+| -------------------------------- | ------------------------------------------------- |
+| sample, approximate, permutation | antropy and EntropyHub: exact match (< 1e-10)     |
+| spectral                         | antropy: exact match                              |
+| multiscale                       | EntropyHub `MSEn`: exact match                    |
+| shannon, differential (normal)   | scipy: exact match                                |
+| transfer                         | analytic Gaussian closed form and Kraskov (2004)  |
+
+Details, including two definitions corrected along the way, are in
+[docs/validation.md](docs/validation.md). Run the checks yourself with
+`pip install -e ".[dev,reference]" && pytest tests/test_reference.py`.
+
 ## Real-world examples
 
 Runnable scripts live in [`examples/`](examples/); worked write-ups are in

{entroscope-0.2.0 → entroscope-0.3.0}/README.md

@@ -1,12 +1,20 @@
 # entroscope
 
-[![PyPI version](https://img.shields.io/pypi/v/entroscope.svg)](https://pypi.org/project/entroscope/)
-[![Python versions](https://img.shields.io/pypi/pyversions/entroscope.svg)](https://pypi.org/project/entroscope/)
-[![CI](https://github.com/Par-python/entroscope/actions/workflows/ci.yml/badge.svg)](https://github.com/Par-python/entroscope/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
-
-**The definitive entropy toolkit for time series data.** Seven entropy measures,
-one consistent interface, working directly on pandas Series and numpy arrays.
+[![CI](https://img.shields.io/github/actions/workflow/status/Par-python/entroscope/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI&labelColor=24292e)](https://github.com/Par-python/entroscope/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/entroscope.svg?style=flat-square&logo=pypi&logoColor=white&labelColor=24292e&color=blue)](https://pypi.org/project/entroscope/)
+[![Downloads](https://img.shields.io/pepy/dt/entroscope.svg?style=flat-square&logo=python&logoColor=white&labelColor=24292e&color=blue)](https://pepy.tech/project/entroscope)
+[![Python](https://img.shields.io/pypi/pyversions/entroscope.svg?style=flat-square&logo=python&logoColor=white&labelColor=24292e&color=blue)](https://pypi.org/project/entroscope/)
+[![Stars](https://img.shields.io/github/stars/Par-python/entroscope.svg?style=flat-square&logo=github&logoColor=white&labelColor=24292e&color=yellow)](https://github.com/Par-python/entroscope/stargazers)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=24292e)](https://opensource.org/licenses/MIT)
+
+**The definitive entropy toolkit for time series data.** Nine entropy measures,
+one consistent interface, working directly on pandas and polars Series and numpy
+arrays. Results are [validated against antropy, EntropyHub and scipy](#validated-results).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Par-python/entroscope/master/docs/assets/entropy-drop-dark.png">
+  <img alt="Two stacked charts. Top: a synthetic signal that is random noise until step 180, then a regular cycle. Bottom: its rolling spectral entropy, high during the noise and falling sharply shortly after step 180." src="https://raw.githubusercontent.com/Par-python/entroscope/master/docs/assets/entropy-drop-light.png">
+</picture>
 
 It started in [NextOnMenu](https://github.com/Par-python/nextonmenu): a falling
 Shannon entropy of a food's regional search interest turned out to be an early
@@ -25,7 +33,7 @@ from entroscope import shannon
 
 s = pd.Series([10, 20, 15, 80, 90, 85, 88, 92])
 
-shannon.compute(s)              # 0.73 (a single entropy value)
+shannon.compute(s)              # 1.75 (a single entropy value, in bits)
 shannon.rolling(s, window=20)   # rolling entropy over time (a Series)
 shannon.delta(s, window=20)     # rate of change of entropy
 shannon.normalized(s)           # entropy scaled to [0, 1]
@@ -46,7 +54,7 @@ the standard environment variable:
 export MPLBACKEND=Agg        # or, in a Dockerfile:  ENV MPLBACKEND=Agg
 ```
 
-## The seven measures
+## The nine measures
 
 | Measure          | Import                    | Captures                                         |
 | ---------------- | ------------------------- | ------------------------------------------------ |
@@ -57,6 +65,8 @@ export MPLBACKEND=Agg        # or, in a Dockerfile:  ENV MPLBACKEND=Agg
 | **Spectral**     | `entroscope.spectral`     | Spread of the power spectrum (frequency domain)  |
 | **Differential** | `entroscope.differential` | Continuous entropy via a fitted distribution     |
 | **Multiscale**   | `entroscope.multiscale`   | Sample entropy across coarse-grained time scales |
+| **Transfer**     | `entroscope.transfer`     | Directional information flow X → Y (KSG/binned)  |
+| **Divergence**   | `entroscope.divergence`   | KL and Jensen-Shannon distance between samples   |
 
 ## One consistent API
 
@@ -73,6 +83,11 @@ Every measure exposes the same methods, so switching measures is a one-word chan
 Shannon additionally provides `geographic(df, col=...)` for spatial distributions
 (e.g. search interest by region). Multiscale provides `compute` and `plot`.
 
+The two-input measures take a pair of series. `transfer.compute(x, y)` (plus
+`rolling`, `delta`, `plot`) estimates how much `x`'s past tells you about `y`'s
+future; `divergence.kl(p, q)` and `divergence.js(p, q)` (plus `plot`) compare two
+samples' distributions over shared bins.
+
 ## Visualization
 
 ```python
@@ -91,6 +106,43 @@ plot.drop_events(s, measure="shannon", window=20, threshold=0.4)
 All plot functions return a `matplotlib.figure.Figure` and never call
 `plt.show()`, so they're safe in scripts, notebooks, and CI alike.
 
+## Integrations
+
+**polars**: pass a polars Series anywhere a pandas Series works; rolling and
+delta results come back as a polars Series with the same name.
+
+**scikit-learn**: `EntropyFeatures` turns time-series windows into entropy
+features inside a pipeline:
+
+```python
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.pipeline import make_pipeline
+from entroscope.features import EntropyFeatures
+
+# windows: shape (n_windows, window_length); one row per window
+model = make_pipeline(EntropyFeatures(), RandomForestClassifier())
+model.fit(windows, labels)
+```
+
+Install the optional dependencies with `pip install "entroscope[sklearn]"` or
+`"entroscope[polars]"`. See the [integrations guide](docs/integrations.md).
+
+## Validated results
+
+Every measure is checked against an independent implementation, on every CI run:
+
+| Measure                          | Checked against                                   |
+| -------------------------------- | ------------------------------------------------- |
+| sample, approximate, permutation | antropy and EntropyHub: exact match (< 1e-10)     |
+| spectral                         | antropy: exact match                              |
+| multiscale                       | EntropyHub `MSEn`: exact match                    |
+| shannon, differential (normal)   | scipy: exact match                                |
+| transfer                         | analytic Gaussian closed form and Kraskov (2004)  |
+
+Details, including two definitions corrected along the way, are in
+[docs/validation.md](docs/validation.md). Run the checks yourself with
+`pip install -e ".[dev,reference]" && pytest tests/test_reference.py`.
+
 ## Real-world examples
 
 Runnable scripts live in [`examples/`](examples/); worked write-ups are in

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/__init__.py

@@ -1,28 +1,28 @@
 """entroscope: the definitive entropy toolkit for time series data."""
 
 from . import (
-    shannon,
-    permutation,
-    spectral,
-    sample,
     approximate,
     differential,
+    divergence,
     multiscale,
+    permutation,
+    sample,
+    shannon,
+    spectral,
     transfer,
-    divergence,
 )
 from .utils import plot
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __all__ = [
-    "shannon",
-    "permutation",
-    "spectral",
-    "sample",
     "approximate",
     "differential",
-    "multiscale",
-    "transfer",
     "divergence",
+    "multiscale",
+    "permutation",
     "plot",
+    "sample",
+    "shannon",
+    "spectral",
+    "transfer",
 ]

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/_core.py

@@ -17,11 +17,31 @@ import pandas as pd
 from .utils.windows import sliding_windows
 
 
+class _PolarsName:
+    """Stand-in 'index' for polars input, which has no index — only a name."""
+
+    def __init__(self, name):
+        self.name = name
+
+
+def _is_polars_series(x):
+    # Checked by module name so polars stays an optional dependency.
+    cls = type(x)
+    return cls.__name__ == "Series" and cls.__module__.startswith("polars")
+
+
 def as_array(x):
-    """Coerce input to a 1-D float ndarray, returning (array, index_or_None)."""
+    """Coerce input to a 1-D float ndarray, returning (array, index_or_None).
+
+    pandas input returns its index; polars input returns a `_PolarsName` so
+    `wrap` can rebuild a polars Series; anything else returns None.
+    """
     if isinstance(x, pd.Series):
         index = x.index
         arr = x.to_numpy(dtype=float)
+    elif _is_polars_series(x):
+        index = _PolarsName(x.name)
+        arr = np.asarray(x.to_numpy(), dtype=float)
     else:
         index = None
         arr = np.asarray(x, dtype=float)
@@ -33,8 +53,12 @@ def as_array(x):
 
 
 def wrap(values, index):
-    """Wrap a result array as a Series (if index given) or return the ndarray."""
+    """Wrap a result array to match the input type: pandas, polars, or ndarray."""
     values = np.asarray(values, dtype=float)
+    if isinstance(index, _PolarsName):
+        import polars as pl
+
+        return pl.Series(index.name, values)
     if index is not None:
         return pd.Series(values, index=index)
     return values
@@ -60,11 +84,14 @@ def rolling(x, window, kernel, **params):
 
 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)
+    arr, index = as_array(x)
+    return wrap(first_difference(rolling(arr, window, kernel, **params)), index)
+
+
+def first_difference(values):
+    """`values[t] - values[t-1]`, with NaN at position 0 (like `Series.diff`)."""
+    out = np.full(len(values), np.nan)
+    out[1:] = np.diff(values)
     return out
 
 
@@ -75,7 +102,7 @@ def make_plot(x, window, kernel, *, title=None, ylabel="entropy", **params):
     if isinstance(roll, pd.Series):
         ax.plot(roll.index, roll.to_numpy())
     else:
-        ax.plot(range(len(roll)), roll)
+        ax.plot(range(len(roll)), np.asarray(roll))
     ax.set_title(title or f"Rolling {ylabel} (window={window})")
     ax.set_xlabel("position")
     ax.set_ylabel(ylabel)

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/_transfer_estimators.py

@@ -13,6 +13,7 @@ embedding test.
 
 import numpy as np
 from scipy.special import digamma
+
 from .utils import knn
 
 

entroscope-0.3.0/entroscope/features.py

@@ -0,0 +1,96 @@
+"""scikit-learn integration — entropy values as features for ML pipelines.
+
+Each row of ``X`` is one time-series window; each output column is one entropy
+measure of that window::
+
+    from sklearn.pipeline import make_pipeline
+    from sklearn.ensemble import RandomForestClassifier
+    from entroscope.features import EntropyFeatures
+
+    model = make_pipeline(EntropyFeatures(), RandomForestClassifier())
+    model.fit(windows, labels)          # windows: (n_windows, window_length)
+
+Requires scikit-learn (``pip install "entroscope[sklearn]"``). It is imported
+here rather than in ``entroscope/__init__.py`` so the core library stays free
+of the dependency.
+"""
+
+import numpy as np
+
+try:
+    from sklearn.base import BaseEstimator, TransformerMixin
+    from sklearn.utils.validation import check_array, check_is_fitted
+except ImportError as exc:  # pragma: no cover - exercised only without sklearn
+    raise ImportError(
+        "entroscope.features needs scikit-learn: pip install 'entroscope[sklearn]'"
+    ) from exc
+
+from . import approximate, differential, permutation, sample, shannon, spectral
+
+_MEASURES = {
+    "shannon": shannon.compute,
+    "permutation": permutation.compute,
+    "spectral": spectral.compute,
+    "sample": sample.compute,
+    "approximate": approximate.compute,
+    "differential": differential.compute,
+}
+
+DEFAULT_MEASURES = ("shannon", "permutation", "spectral", "sample", "approximate")
+
+
+class EntropyFeatures(TransformerMixin, BaseEstimator):
+    """Transform time-series windows into one entropy feature per measure.
+
+    Parameters
+    ----------
+    measures : sequence of str
+        Measures to compute, in output-column order. Any of ``shannon``,
+        ``permutation``, ``spectral``, ``sample``, ``approximate``,
+        ``differential``.
+    params : dict, optional
+        Per-measure keyword arguments, e.g. ``{"sample": {"m": 2, "r": 0.15}}``.
+
+    Stateless: ``fit`` only validates input and records its width. Supports
+    ``set_output(transform="pandas")`` for DataFrame output with named columns.
+    """
+
+    def __init__(self, measures=DEFAULT_MEASURES, params=None):
+        self.measures = measures
+        self.params = params
+
+    def _check_config(self):
+        unknown = [m for m in self.measures if m not in _MEASURES]
+        if unknown or not len(self.measures):
+            raise ValueError(
+                f"unknown or empty measures {unknown or list(self.measures)!r}; "
+                f"choose from {sorted(_MEASURES)}"
+            )
+        extra = set(self.params or {}) - set(self.measures)
+        if extra:
+            raise ValueError(f"params given for measures not in `measures`: {sorted(extra)}")
+
+    def fit(self, X, y=None):
+        self._check_config()
+        X = check_array(X, dtype=float)
+        self.n_features_in_ = X.shape[1]
+        return self
+
+    def transform(self, X):
+        check_is_fitted(self, "n_features_in_")
+        X = check_array(X, dtype=float)
+        if X.shape[1] != self.n_features_in_:
+            raise ValueError(
+                f"X has {X.shape[1]} features, but EntropyFeatures is expecting "
+                f"{self.n_features_in_} features as input."
+            )
+        params = self.params or {}
+        out = np.empty((X.shape[0], len(self.measures)))
+        for j, name in enumerate(self.measures):
+            fn, kwargs = _MEASURES[name], params.get(name, {})
+            out[:, j] = [fn(row, **kwargs) for row in X]
+        return out
+
+    def get_feature_names_out(self, input_features=None):
+        check_is_fitted(self, "n_features_in_")
+        return np.asarray([f"{name}_entropy" for name in self.measures], dtype=object)

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/multiscale.py

@@ -1,6 +1,7 @@
 """Multiscale entropy — sample entropy across coarse-grained time scales."""
 
 import matplotlib.pyplot as plt
+import numpy as np
 
 from . import _core, sample
 
@@ -12,24 +13,33 @@ def _coarse_grain(values, scale):
     return trimmed.reshape(n, scale).mean(axis=1)
 
 
-def compute(series, scales=range(1, 10), method="sample"):
+def compute(series, scales=range(1, 10), method="sample", m=2, r=0.2):
     """Return {scale: entropy} by coarse-graining then applying `method`.
 
+    Following Costa et al. (2002), the tolerance is fixed at ``r * std`` of the
+    ORIGINAL series and reused at every scale, so white noise loses entropy as
+    the scale grows while 1/f-like signals keep it.
+
     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")
+    if r <= 0:
+        raise ValueError("r must be positive")
+    if m < 1:
+        raise ValueError("m must be >= 1")
     arr, _ = _core.as_array(series)
+    tol = r * np.std(arr)
     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)
+        if len(grained) <= m + 1:  # sample entropy needs n > m+1
             continue
-        result[int(scale)] = sample.compute(grained)
+        result[int(scale)] = sample._sampen(grained, m, tol)
     return result
 
 

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/sample.py

@@ -5,10 +5,13 @@ 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)])
+def _count_matches(values, m, tol, n_templates):
+    """Count template-vector pairs (length m) within Chebyshev distance `tol`.
+
+    Only the first `n_templates` templates are used, so the length-m and
+    length-(m+1) counts are taken over the same starting points.
+    """
+    templates = np.array([values[i : i + m] for i in range(n_templates)])
     count = 0
     for i in range(len(templates) - 1):
         dist = np.max(np.abs(templates[i + 1 :] - templates[i]), axis=1)
@@ -16,6 +19,19 @@ def _count_matches(values, m, tol):
     return count
 
 
+def _sampen(values, m, tol):
+    """Sample entropy with an absolute tolerance (Richman & Moorman, 2000)."""
+    n = len(values)
+    if tol == 0:
+        return 0.0  # constant signal: perfectly regular
+    b = _count_matches(values, m, tol, n - m)
+    a = _count_matches(values, m + 1, tol, n - m)
+    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 _kernel(values, m=2, r=0.2):
     """Sample entropy: -ln(A/B) of length-(m+1) vs length-m matches."""
     if r <= 0:
@@ -23,18 +39,9 @@ def _kernel(values, m=2, r=0.2):
     if m < 1:
         raise ValueError("m must be >= 1")
     values = np.asarray(values, dtype=float)
-    n = len(values)
-    if n <= m + 1:
+    if len(values) <= 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))
+    return _sampen(values, m, r * np.std(values))
 
 
 def compute(series, m=2, r=0.2):

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/spectral.py

@@ -41,8 +41,8 @@ def delta(series, window=50, sf=1.0):
 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))
+    _, 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))

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/transfer.py

@@ -73,12 +73,9 @@ def rolling(x, y, window=120, *, k=4, lag=1, method="ksg", bins=6):
 
 def delta(x, y, window=120, *, k=4, lag=1, method="ksg", bins=6):
     """First difference of the rolling transfer entropy."""
-    roll = rolling(x, y, window, k=k, lag=lag, method=method, bins=bins)
-    if isinstance(roll, pd.Series):
-        return roll.diff()
-    out = np.full_like(roll, np.nan)
-    out[1:] = np.diff(roll)
-    return out
+    xa, ya, yindex = _coerce_pair(x, y)
+    roll = rolling(xa, ya, window, k=k, lag=lag, method=method, bins=bins)
+    return _core.wrap(_core.first_difference(roll), yindex)
 
 
 def plot(x, y, window=120, *, k=4, lag=1, method="ksg", bins=6, title=None):
@@ -88,7 +85,7 @@ def plot(x, y, window=120, *, k=4, lag=1, method="ksg", bins=6, title=None):
     if isinstance(roll, pd.Series):
         ax.plot(roll.index, roll.to_numpy())
     else:
-        ax.plot(range(len(roll)), roll)
+        ax.plot(range(len(roll)), np.asarray(roll))
     ax.set_title(title or f"Rolling transfer entropy (window={window})")
     ax.set_xlabel("position")
     ax.set_ylabel("transfer entropy (bits)")

{entroscope-0.2.0 → entroscope-0.3.0}/entroscope/utils/knn.py

@@ -25,16 +25,11 @@ def count_within_radius(points, radii):
     points = np.asarray(points, dtype=float)
     radii = np.asarray(radii, dtype=float)
     tree = cKDTree(points)
-    counts = np.empty(len(points), dtype=int)
-    for i, (p, r) in enumerate(zip(points, radii)):
-        # ball_point with p=inf, count neighbors strictly inside r, minus self.
-        idx = tree.query_ball_point(p, r=r, p=np.inf)
-        # exclude self and any point exactly at radius r (strict inequality).
-        c = 0
-        for j in idx:
-            if j == i:
-                continue
-            if np.max(np.abs(points[j] - p)) < r:
-                c += 1
-        counts[i] = c
-    return counts
+    # query_ball_point counts distance <= r; shrinking each radius to the next
+    # float below it gives the strict inequality. Subtract 1 for the point itself.
+    inner = np.nextafter(radii, 0)
+    counts = np.asarray(
+        tree.query_ball_point(points, r=inner, p=np.inf, return_length=True), dtype=int
+    )
+    # Nothing is strictly within a zero radius, but duplicates sit at distance 0.
+    return np.where(radii > 0, counts - 1, 0)