khisto.matplotlib¶

Use khisto.matplotlib.hist when you want the convenience of plt.hist with bins that adapt to the data instead of flattening it.

khisto.matplotlib.hist(x: ArrayLike, range: tuple[float, float] | None = None, max_bins: int | None = None, density: bool = True, *, ax: Axes | None = None, **kwargs: Any) → tuple[np.ndarray, np.ndarray, Any]¶

Compute and plot an optimal histogram.

Parameters:

xarray_like

Input data. Must be 1-dimensional.

rangetuple of (float, float), optional

Lower and upper range of the bins. Values outside the range are ignored.

max_binsint, optional

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

densitybool, optional

If True, returns and plots a probability density; otherwise, counts. Default is True.

With adaptive binning, bin widths vary, so density and frequency histograms differ visually. Therefore, density is the default, unlike in matplotlib.

axmatplotlib.axes.Axes, optional

Axes object to plot on. If not provided, the current axes will be used.

**kwargs

other keyword arguments are described in matplotlib.pyplot.hist. The bins, weights, and stacked/multiple dataset features are not supported.

Returns:

nndarray: Histogram values (counts by default, or cumulative values when requested).
binsndarray: Bin edges.
patches: Container with the bar patches.