entroscope

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.

It started in NextOnMenu: a falling Shannon entropy of a food's regional search interest turned out to be an early signal that it was about to trend. Computing it meant re-writing the same histogram-and-log boilerplate every time. entroscope is that code, written once.

pip install entroscope

Quick start

import pandas as pd
from entroscope import shannon

s = pd.Series([10, 20, 15, 80, 90, 85, 88, 92])

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]
shannon.plot(s, window=20)      # a matplotlib Figure

Every method accepts a pd.Series or a np.ndarray. Pass a Series and you get a Series back with its index preserved; pass an array and you get an array.

Headless environments (Docker, CI)

entroscope does not change your matplotlib backend on import, so interactive plotting in notebooks keeps working. In a headless environment (a Docker container or CI runner) where you want a guaranteed non-interactive backend, set the standard environment variable:

export MPLBACKEND=Agg        # or, in a Dockerfile:  ENV MPLBACKEND=Agg

The nine measures

One consistent API

Every measure exposes the same methods, so switching measures is a one-word change:

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

from entroscope import plot

# overlay several measures on one axis
plot.compare(s, measures=["shannon", "permutation", "spectral"], window=20)

# a grid of every measure at once
plot.dashboard(s, window=20)

# highlight where entropy drops sharply (trend / regime-change detection)
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:

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.

Validated results

Every measure is checked against an independent implementation, on every CI run:

Details, including two definitions corrected along the way, are in 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/; worked write-ups are in docs/examples/:

• Food trends: detect when search interest stops being random (the original NextOnMenu use case).
• Finance: market uncertainty via permutation and spectral entropy.
• Medical: HRV, EEG seizure onset, respiration, and continuous glucose.
• Business: sales demand, web-traffic anomalies, price volatility, and manufacturing QC.

# food-trend analysis: entropy drops before a trend goes mainstream
import pandas as pd
from entroscope import shannon

matcha = pd.read_csv("matcha_trends.csv")["interest"]
shannon.plot(matcha, window=20, title="Matcha entropy over time")

A sustained drop in rolling entropy means a signal is becoming structured rather than noisy, an early indicator of a forming pattern.

Requirements

Python 3.9+, with numpy, pandas, scipy, and matplotlib (installed automatically).

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, the test/lint commands, and how to add a new entropy measure.

License

MIT