khisto.histogram

The fastest way to use Khisto: a NumPy-like (hist, bin_edges) API with adaptive bins, optional max_bins control, and no plotting overhead.

khisto.histogram(a: ArrayLike, range: tuple[float, float] | None = None, max_bins: int | None = None, density: bool = True) → tuple[NDArray[float64], NDArray[float64]]

Compute an optimal histogram using the Khiops binning algorithm.

Parameters:

aarray_like

Input data. Must be 1-dimensional.

rangetuple of (float, float), optional

The lower and upper range of the bins. Values outside the range are ignored. If not provided, the range is (a.min(), a.max()).

max_binsint, optional

Maximum number of bins. If not provided, the algorithm selects the optimal number of bins automatically.

densitybool, optional

If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Default is True.

Returns:

histndarray

The values of the histogram.

bin_edgesndarray

The bin edges (length(hist) + 1).

See also

numpy.histogram

NumPy’s histogram function (bins and weights parameters are not supported).

Notes

Unlike numpy.histogram, this function uses optimal binning which may produce bins of unequal width. The bins are determined by the Khiops algorithm to best represent the underlying data distribution.

The method implemented in Khiops is comprehensively detailed in [2] and further extended in [1].

References

[1]

M. Boulle. Floating-point histograms for exploratory analysis of large scale real-world data sets. Intelligent Data Analysis, 28(5):1347-1394, 2024.

[2]

V. Zelaya Mendizabal, M. Boulle, F. Rossi. Fast and fully-automated histograms for large-scale data sets. Computational Statistics & Data Analysis, 180:0-0, 2023.