Metadata-Version: 2.5
Name: pundamilia
Version: 0.1.0
Summary: Clustering, ranking and anomaly detection for time series, built on smart-meter and energy load profiles.
Project-URL: Repository, https://github.com/sambaiga/pundamilia
Project-URL: Issues, https://github.com/sambaiga/pundamilia/issues
Author-email: Anthony Faustine <sambaiga@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: anomaly-detection,clustering,conformal,energy,ranking,retrieval,smart-meter,time-series
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: joblib>=1.3.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: pydantic>=2.10.6
Requires-Dist: scikit-learn>=1.6.0
Requires-Dist: scipy>=1.14.0
Provides-Extra: all
Requires-Dist: chronos-forecasting>=2.0.0; extra == 'all'
Requires-Dist: great-tables>=0.17.0; extra == 'all'
Requires-Dist: lets-plot>=4.5.0; extra == 'all'
Requires-Dist: lightgbm>=4.6.0; extra == 'all'
Requires-Dist: matplotlib>=3.9.0; extra == 'all'
Requires-Dist: optuna>=4.2.0; extra == 'all'
Requires-Dist: pacmap>=0.8.0; extra == 'all'
Requires-Dist: ruptures>=1.1.9; extra == 'all'
Requires-Dist: scienceplots>=2.1.1; extra == 'all'
Requires-Dist: shap>=0.46.0; extra == 'all'
Requires-Dist: tensorly>=0.9.0; extra == 'all'
Requires-Dist: torch>=2.4.0; extra == 'all'
Requires-Dist: tslearn>=0.6.3; extra == 'all'
Requires-Dist: twiga>=1.1.3; extra == 'all'
Requires-Dist: twiga[plots]>=1.1.3; extra == 'all'
Requires-Dist: umap-learn>=0.5.7; extra == 'all'
Provides-Extra: bench
Requires-Dist: twiga>=1.1.3; extra == 'bench'
Provides-Extra: changepoint
Requires-Dist: ruptures>=1.1.9; extra == 'changepoint'
Provides-Extra: explain
Requires-Dist: shap>=0.46.0; extra == 'explain'
Provides-Extra: foundation
Requires-Dist: chronos-forecasting>=2.0.0; extra == 'foundation'
Requires-Dist: torch>=2.4.0; extra == 'foundation'
Provides-Extra: plots
Requires-Dist: great-tables>=0.17.0; extra == 'plots'
Requires-Dist: lets-plot>=4.5.0; extra == 'plots'
Requires-Dist: matplotlib>=3.9.0; extra == 'plots'
Requires-Dist: scienceplots>=2.1.1; extra == 'plots'
Requires-Dist: twiga[plots]>=1.1.3; extra == 'plots'
Provides-Extra: ranking
Requires-Dist: lightgbm>=4.6.0; extra == 'ranking'
Provides-Extra: tensor
Requires-Dist: tensorly>=0.9.0; extra == 'tensor'
Provides-Extra: ts
Requires-Dist: tslearn>=0.6.3; extra == 'ts'
Provides-Extra: tuning
Requires-Dist: optuna>=4.2.0; extra == 'tuning'
Requires-Dist: pacmap>=0.8.0; extra == 'tuning'
Requires-Dist: umap-learn>=0.5.7; extra == 'tuning'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <img src="docs/assets/logo.svg" alt="milia: cluster, rank, detect" width="480">
  </picture>
</p>

<p align="center">
  <em>Cluster, rank and detect in time series.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/pundamilia/"><img alt="PyPI" src="https://img.shields.io/pypi/v/pundamilia"></a>
  <a href="https://pypi.org/project/pundamilia/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/pundamilia"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
</p>

<p align="center">
  <a href="https://sambaiga.github.io/pundamilia-docs/"><b>Documentation</b></a> ·
  <a href="https://sambaiga.github.io/pundamilia-docs/getting-started/quickstart.html">Quickstart</a> ·
  <a href="https://sambaiga.github.io/pundamilia-docs/guide/index.html">User guide</a> ·
  <a href="https://sambaiga.github.io/pundamilia-docs/tutorials/index.html">Tutorials</a> ·
  <a href="https://sambaiga.github.io/pundamilia-docs/api/index.html">API</a> ·
  <a href="https://sambaiga.github.io/pundamilia-docs/changelog.html">Changelog</a>
</p>

**milia** groups series that behave alike, finds the cases most similar to a given one, and flags the days or windows that are not normal. It grew out of smart-meter and energy load profiles, which is its home domain, and its methods apply to other time series such as sensor, traffic, retail or clinical signals. Every learned component is a scikit-learn estimator, so it clones, pickles, tunes and composes in a `Pipeline`.

*Milia* is Swahili for stripes: a zebra is recognised in its herd by its stripe pattern, as a series is recognised among thousands.

<table>
  <tr>
    <td align="center" valign="top" width="33%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="docs/assets/illustration-cluster-dark.svg">
        <img src="docs/assets/illustration-cluster.svg" alt="" width="250">
      </picture>
      <h3>Cluster</h3>
      <b>Find the herds.</b><br>
      <sub>Group the series that behave alike, and see how far to trust the groups.</sub>
    </td>
    <td align="center" valign="top" width="33%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="docs/assets/illustration-rank-dark.svg">
        <img src="docs/assets/illustration-rank.svg" alt="" width="250">
      </picture>
      <h3>Rank</h3>
      <b>Find the look-alikes.</b><br>
      <sub>Retrieve the most similar cases, and the action that worked for them.</sub>
    </td>
    <td align="center" valign="top" width="33%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="docs/assets/illustration-detect-dark.svg">
        <img src="docs/assets/illustration-detect.svg" alt="" width="250">
      </picture>
      <h3>Detect</h3>
      <b>Spot the odd stripe.</b><br>
      <sub>Flag the days that are not normal, at a false-alarm rate that you set.</sub>
    </td>
  </tr>
</table>

## Install

```bash
pip install pundamilia              # the distribution; import it as milia
pip install 'pundamilia[all]'       # with plots, tuning, tensor and the other extras
```

## Quick start

```python
from milia import make
from milia.data import synthetic, profiles
from milia.cluster import validation, selection

population = synthetic.generate(meters=60, days=90, steps=48)
shapes = profiles.shape(population.pivot)
scores = validation.sweep(shapes, range(2, 8), resampling=True)
k = selection.recommend(scores, strategy="trust")
labels = make("clusterer", "kmeans", n_clusters=k).fit_predict(shapes)
```

Anomalous days with a conformal guarantee on the share of normal days flagged:

```python
from milia.anomaly.ensemble import Ensemble
from milia.features.window import vector

X = [vector(day) for day in profiles.tensor(population.pivot)[0]]
detector = Ensemble().fit(X[:60]).calibrate(X[60:80], alpha=0.1)
flags = detector.flag(X[80:])
```

Models are registered by module: `milia.available("detector")` lists them. The [documentation](https://sambaiga.github.io/pundamilia-docs/) has the user guide, the tutorials and the API reference.

## Developer

Developed by [Anthony Faustine](https://github.com/sambaiga) ([LinkedIn](https://www.linkedin.com/in/sambaiga)).

## Citation

If you use milia in your work, please cite it:

```bibtex
@software{faustine2026milia,
  title  = {milia: cluster, rank and detect in time series},
  author = {Faustine, Anthony},
  year   = {2026},
  url    = {https://sambaiga.github.io/pundamilia-docs/}
}
```

## Contributing

Open a pull request against `main` with a conventional-commit title. `make test` and `make lint` run the suite and the linters.

## License

Apache-2.0.
