Improve hexbin() documentation

examples/statistics/hexbin_demo.py

@@ -1,14 +1,10 @@
 """
-===========
-Hexbin Demo
-===========
+=====================
+Hexagonal binned plot
+=====================
 
-Plotting hexbins with Matplotlib.
-
-Hexbin is an axes method or pyplot function that is essentially
-a pcolor of a 2D histogram with hexagonal cells.  It can be
-much more informative than a scatter plot. In the first plot
-below, try substituting 'scatter' for 'hexbin'.
+`~.Axes.hexbin` is a 2D histogram plot, in which the bins are hexagons and
+the color represents the number of data points within each bin.
 """
 
 import numpy as np
@@ -17,29 +13,23 @@
 # Fixing random state for reproducibility
 np.random.seed(19680801)
 
-n = 100000
+n = 100_000
 x = np.random.standard_normal(n)
 y = 2.0 + 3.0 * x + 4.0 * np.random.standard_normal(n)
-xmin = x.min()
-xmax = x.max()
-ymin = y.min()
-ymax = y.max()
-
-fig, axs = plt.subplots(ncols=2, sharey=True, figsize=(7, 4))
-fig.subplots_adjust(hspace=0.5, left=0.07, right=0.93)
-ax = axs[0]
-hb = ax.hexbin(x, y, gridsize=50, cmap='inferno')
-ax.set(xlim=(xmin, xmax), ylim=(ymin, ymax))
-ax.set_title("Hexagon binning")
-cb = fig.colorbar(hb, ax=ax)
-cb.set_label('counts')
-
-ax = axs[1]
-hb = ax.hexbin(x, y, gridsize=50, bins='log', cmap='inferno')
-ax.set(xlim=(xmin, xmax), ylim=(ymin, ymax))
-ax.set_title("With a log color scale")
-cb = fig.colorbar(hb, ax=ax)
-cb.set_label('log10(N)')
+xlim = x.min(), x.max()
+ylim = y.min(), y.max()
+
+fig, (ax0, ax1) = plt.subplots(ncols=2, sharey=True, figsize=(9, 4))
+
+hb = ax0.hexbin(x, y, gridsize=50, cmap='inferno')
+ax0.set(xlim=xlim, ylim=ylim)
+ax0.set_title("Hexagon binning")
+cb = fig.colorbar(hb, ax=ax0, label='counts')
+
+hb = ax1.hexbin(x, y, gridsize=50, bins='log', cmap='inferno')
+ax1.set(xlim=xlim, ylim=ylim)
+ax1.set_title("With a log color scale")
+cb = fig.colorbar(hb, ax=ax1, label='log10(N)')
 
 plt.show()
 

lib/matplotlib/axes/_axes.py

@@ -4755,6 +4755,9 @@ def reduce_C_function(C: array) -> float
 
             %(PolyCollection:kwdoc)s
 
+        See Also
+        --------
+        hist2d : 2D histogram rectangular bins
         """
         self._process_unit_info([("x", x), ("y", y)], kwargs, convert=False)
 
@@ -6650,7 +6653,8 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
 
         See Also
         --------
-        hist2d : 2D histograms
+        hist2d : 2D histogram with rectangular bins
+        hexbin : 2D histogram with hexagonal bins
 
         Notes
         -----
@@ -7093,6 +7097,7 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
         See Also
         --------
         hist : 1D histogram plotting
+        hexbin : 2D histogram with hexagonal bins
 
         Notes
         -----