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
