Add kde support for hist

docs/stats.py

@@ -216,11 +216,19 @@
 # the :ref:`2D plotting section <ug_apply_cmap>`). Marginal distributions
 # for the 2D histograms can be added using :ref:`panel axes <ug_panels>`.
 #
-# In the future, UltraPlot will include options for adding "smooth" kernel density
-# estimations to histograms plots using a `kde` keyword. It will also include
-# separate `ultraplot.axes.PlotAxes.kde` and `ultraplot.axes.PlotAxes.kde2d` commands.
-# The :func:`~ultraplot.axes.PlotAxes.violin` and :func:`~ultraplot.axes.PlotAxes.violinh` commands
-# will use the same algorithm for kernel density estimation as the `kde` commands.
+# Histograms accept a ``kde=True`` keyword that overlays a smooth
+# `kernel density estimate <https://en.wikipedia.org/wiki/Kernel_density_estimation>`__
+# of each column of data. The curve follows the histogram -- it is scaled to
+# the bin counts unless ``density=True``, accumulated when the histogram is
+# stacked, and drawn in the color of the histogram it belongs to. Use the
+# `kde_kw` keyword to control the estimate (``bw_method``, ``weights``,
+# ``points``) and to style the curve (any `~matplotlib.axes.Axes.plot`
+# property). The same keyword is used by
+# :func:`~ultraplot.axes.PlotAxes.ridgeline` (see :ref:`ug_ridgeline`).
+# This requires `scipy <https://scipy.org>`__, which is installed with
+# ``pip install ultraplot[stats]``. Separate
+# :func:`~ultraplot.axes.PlotAxes.kde` and
+# :func:`~ultraplot.axes.PlotAxes.kde2d` commands are still planned.
 
 # %%
 import numpy as np
@@ -244,6 +252,7 @@
     cycle=("indigo9", "gray3", "red9"),
     labels=list("abc"),
     legend="ul",
+    kde=True,
 )
 
 # %%

pyproject.toml

@@ -88,3 +88,6 @@ docs = [
     "sphinx-sitemap",
     "typing-extensions"
 ]
+stats = [
+    "scipy",
+]