Metadata-Version: 2.4
Name: khisto
Version: 1.0.0
Summary: Optimal histogram visualization using the Khiops algorithm
Keywords: histogram,binning,optimal,khiops,statistics,data-analysis,density-estimation,distribution,numpy,matplotlib,visualization
Author-Email: Elouen Ginat <elouen.ginat@orange.com>
License-Expression: BSD-3-Clause-Clear
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/KhiopsML/khisto-python
Project-URL: Documentation, https://khiopsml.github.io/khisto-python/
Project-URL: Repository, https://github.com/KhiopsML/khisto-python
Project-URL: Issues, https://github.com/KhiopsML/khisto-python/issues
Project-URL: Changelog, https://github.com/KhiopsML/khisto-python/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0
Provides-Extra: matplotlib
Requires-Dist: matplotlib>=3.8; extra == "matplotlib"
Provides-Extra: all
Requires-Dist: matplotlib>=3.8; extra == "all"
Description-Content-Type: text/markdown

# Khisto

[![CI](https://github.com/KhiopsML/khisto-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/KhiopsML/khisto-python/actions/workflows/ci.yaml)
[![Docs](https://github.com/KhiopsML/khisto-python/actions/workflows/docs.yaml/badge.svg)](https://khiopsml.github.io/khisto-python/)
[![Release](https://img.shields.io/github/v/release/KhiopsML/khisto-python?include_prereleases)](https://github.com/KhiopsML/khisto-python/releases)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://github.com/KhiopsML/khisto-python/blob/main/pyproject.toml)
[![License](https://img.shields.io/badge/license-BSD--3--Clause--Clear-blue)](LICENSE)

**Optimal Binning Histograms for Python**

Khisto is a Python library for creating histograms using the **Khiops optimal binning algorithm**. Unlike standard histograms that use fixed-width bins or simple heuristics, Khisto automatically determines the optimal number of bins and their variable widths to best represent the underlying data distribution.

Documentation is available at **[khiopsml.github.io/khisto-python](https://khiopsml.github.io/khisto-python/)**.

| Standard Gaussian | Heavy-tailed Pareto |
| --- | --- |
| ![Adaptive Gaussian histogram](docs/images/gaussian-quick-start.png) | ![Adaptive Pareto histogram](docs/images/pareto-quick-start.png) |

## Installation

```bash
pip install khisto
```

With matplotlib support:

```bash
pip install "khisto[matplotlib]"
```

## Quick Start

```python
import numpy as np
import matplotlib.pyplot as plt
from khisto.matplotlib import hist

# Generate 10,000 samples from a Normal distribution
normal_data = np.random.normal(size=10000)

# Plot an adaptive histogram
n, bins, patches = hist(normal_data)
plt.show()

# Generate 10,000 samples from a Pareto distribution
long_tail_data = np.random.pareto(3, size=10000)

# Plot an adaptive histogram on logarithmic axes.
n, bins, patches = hist(long_tail_data)
plt.xscale("symlog")
plt.yscale("log")
plt.show()
```

## Development

```bash
# Clone repository
git clone https://github.com/KhiopsML/khisto-python.git
cd khisto-python

# Install with dev dependencies
uv sync --group dev --extra all

# Run tests
uv run pytest
```

## License

[BSD 3-Clause Clear License](LICENSE)
