Return NaN for non-finite input instead of a made-up entropy

One NaN or inf in the input used to produce a plausible-looking number:
permutation.compute counted NaN as an ordinal pattern (argsort ranks it
last), spectral.compute returned -0.0 because a NaN spectrum filters to
nothing, sample.compute returned a large finite value, and shannon.compute
raised. rolling inherited this, so one gap silently corrupted every window
that contained it.

Every measure's kernel is now wrapped by _core.nan_on_non_finite, so
compute, normalized, rolling and delta return NaN for exactly the windows
that hold a non-finite value and leave the rest of the series unchanged.
multiscale, transfer, spectral.normalized and divergence.kl/js get the
same guard. Zero entropy is also returned as 0.0, never -0.0.

Found while building the training early-warning study
(github.com/Par-python/training-early-warning).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Par-python

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- **Fixed (changes results):** missing and infinite values no longer produce
+  plausible-looking numbers. Previously one NaN made `permutation.compute`
+  return a finite value, `spectral.compute` return `-0.0`, `sample.compute`
+  return a large finite value, and `shannon.compute` raise. Now every measure
+  (`compute`, `normalized`, `multiscale`, `transfer`, `divergence.kl`/`js`)
+  returns NaN when its input holds NaN or ±inf, and `rolling`/`delta` are NaN
+  for exactly the windows that contain one. Reported while building the
+  training early-warning study.
+- **Fixed:** zero entropy is returned as `0.0`, never `-0.0` (constant or
+  perfectly ordered input, a single region in `shannon.geographic`).
 - CI: move the remaining GitHub Actions off the deprecated Node 20 runtime
   (`upload-artifact` and `download-artifact` to v7, `upload-pages-artifact` and
   `deploy-pages` to v5).

README.md

@@ -83,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`.
 
+**Missing values.** Any NaN or ±inf in the input makes the result NaN, never a
+made-up number. `rolling` and `delta` are NaN only for the windows that contain
+the gap, so the rest of the series is unaffected. `rolling` is causal: the value
+at position t uses positions t−window+1 through t.
+
 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

entroscope/_core.py

@@ -10,6 +10,8 @@
 non-interactive backend should set ``MPLBACKEND=Agg`` in their environment.
 """
 
+import functools
+
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
@@ -30,6 +32,23 @@ def _is_polars_series(x):
     return cls.__name__ == "Series" and cls.__module__.startswith("polars")
 
 
+def nan_on_non_finite(kernel):
+    """Make `kernel` return NaN when its input contains NaN or +/-inf.
+
+    Without this, kernels turn missing values into plausible-looking numbers (argsort
+    ranks NaN last, a NaN spectrum sums to NaN, ...). Applied to each measure's
+    `_kernel`, it also makes `rolling` NaN for exactly the windows that hold a gap.
+    """
+
+    @functools.wraps(kernel)
+    def wrapper(values, *args, **kwargs):
+        if not np.isfinite(np.asarray(values, dtype=float)).all():
+            return float("nan")
+        return kernel(values, *args, **kwargs)
+
+    return wrapper
+
+
 def as_array(x):
     """Coerce input to a 1-D float ndarray, returning (array, index_or_None).
 

entroscope/approximate.py

@@ -16,6 +16,7 @@ def _phi(values, m, tol):
     return float(np.mean(np.log(counts)))
 
 
+@_core.nan_on_non_finite
 def _kernel(values, m=2, r=0.2):
     """Approximate entropy: phi(m) - phi(m+1)."""
     if r <= 0:

entroscope/differential.py

@@ -6,6 +6,7 @@
 from . import _core
 
 
+@_core.nan_on_non_finite
 def _kernel(values, dist="normal"):
     """Differential entropy (nats). dist in {'normal', 'kde'}."""
     values = np.asarray(values, dtype=float)

entroscope/divergence.py

@@ -40,6 +40,11 @@ def _binned_probs(p, q, bins):
 _LN2 = np.log(2.0)
 
 
+def _all_finite(*arrays):
+    """False if any sample holds NaN or +/-inf; kl/js then return NaN."""
+    return all(np.isfinite(a).all() for a in arrays)
+
+
 def _kl_bits(pp, qq):
     """KL(pp || qq) in bits, with epsilon smoothing so the result stays finite."""
     pp = pp + _EPS
@@ -57,6 +62,8 @@ def kl(p, q, bins=10):
     """
     pa, _ = _core.as_array(p)
     qa, _ = _core.as_array(q)
+    if not _all_finite(pa, qa):
+        return float("nan")
     pp, qq = _binned_probs(pa, qa, bins)
     return _kl_bits(pp, qq)
 
@@ -68,6 +75,8 @@ def js(p, q, bins=10):
     """
     pa, _ = _core.as_array(p)
     qa, _ = _core.as_array(q)
+    if not _all_finite(pa, qa):
+        return float("nan")
     pp, qq = _binned_probs(pa, qa, bins)
     m = 0.5 * (pp + qq)
     return 0.5 * _kl_bits(pp, m) + 0.5 * _kl_bits(qq, m)

entroscope/multiscale.py

@@ -30,6 +30,7 @@ def compute(series, scales=range(1, 10), method="sample", m=2, r=0.2):
     if m < 1:
         raise ValueError("m must be >= 1")
     arr, _ = _core.as_array(series)
+    finite = bool(np.isfinite(arr).all())
     tol = r * np.std(arr)
     result = {}
     for scale in scales:
@@ -39,7 +40,7 @@ def compute(series, scales=range(1, 10), method="sample", m=2, r=0.2):
             grained = _coarse_grain(arr, scale)
         if len(grained) <= m + 1:  # sample entropy needs n > m+1
             continue
-        result[int(scale)] = sample._sampen(grained, m, tol)
+        result[int(scale)] = sample._sampen(grained, m, tol) if finite else float("nan")
     return result
 
 

entroscope/permutation.py

@@ -9,6 +9,7 @@
 from .utils import normalize
 
 
+@_core.nan_on_non_finite
 def _kernel(values, order=3, delay=1):
     """Permutation entropy (base 2) of ordinal patterns of length `order`."""
     if order < 2:
@@ -28,7 +29,7 @@ def _kernel(values, order=3, delay=1):
         counts[perm_index[pattern]] += 1
     total = counts.sum()
     p = counts[counts > 0] / total
-    return float(-np.sum(p * np.log2(p)))
+    return float(-np.sum(p * np.log2(p))) + 0.0  # + 0.0 turns -0.0 into 0.0
 
 
 def _check_window(window, order, delay):

entroscope/sample.py

@@ -32,6 +32,7 @@ def _sampen(values, m, tol):
     return float(-np.log(a / b))
 
 
+@_core.nan_on_non_finite
 def _kernel(values, m=2, r=0.2):
     """Sample entropy: -ln(A/B) of length-(m+1) vs length-m matches."""
     if r <= 0:

entroscope/shannon.py

@@ -6,6 +6,7 @@
 from .utils import normalize
 
 
+@_core.nan_on_non_finite
 def _kernel(values, bins=10):
     """Shannon entropy (base 2) of `values` histogrammed into `bins`."""
     if bins <= 0:
@@ -16,7 +17,7 @@ def _kernel(values, bins=10):
     if total == 0:
         return 0.0
     p = counts[counts > 0] / total
-    return float(-np.sum(p * np.log2(p)))
+    return float(-np.sum(p * np.log2(p))) + 0.0  # + 0.0 turns -0.0 into 0.0
 
 
 def compute(series, bins=10):
@@ -44,7 +45,7 @@ def geographic(region_df, col="interest"):
     if total == 0:
         return 0.0
     p = values[values > 0] / total
-    return float(-np.sum(p * np.log2(p)))
+    return float(-np.sum(p * np.log2(p))) + 0.0  # + 0.0 turns -0.0 into 0.0
 
 
 def plot(series, window=20, bins=10, title=None):