Merge pull request matplotlib#30616 from rcomer/doc-violin_stats

DOC: add what's new info for violin_stats

Author: timhoffm

doc/release/next_whats_new/violin_stats.rst

@@ -0,0 +1,31 @@
+``violin_stats`` simpler *method* parameter
+-------------------------------------------
+
+The *method* parameter of `~.cbook.violin_stats` may now be specified as tuple of
+strings, and has a new default ``("GaussianKDE", "scott")``.  Calling
+`~.cbook.violin_stats` followed by `~.Axes.violin` is therefore now equivalent to
+calling `~.Axes.violinplot`.
+
+.. plot::
+    :include-source: true
+    :alt: Example showing violin_stats followed by violin gives the same result as violinplot
+
+    import matplotlib.pyplot as plt
+    from matplotlib.cbook import violin_stats
+    import numpy as np
+
+    rng = np.random.default_rng(19680801)
+    data = rng.normal(size=(10, 3))
+
+    fig, (ax1, ax2) = plt.subplots(ncols=2, layout='constrained', figsize=(6.4, 3.5))
+
+    # Create the violin plot in one step
+    ax1.violinplot(data)
+    ax1.set_title('One Step')
+
+    # Process the data and then create the violin plot
+    vstats = violin_stats(data)
+    ax2.violin(vstats)
+    ax2.set_title('Two Steps')
+
+    plt.show()

lib/matplotlib/axes/_axes.py

@@ -9006,6 +9006,8 @@ def violin(self, vpstats, positions=None, vert=None,
         --------
         violinplot :
             Draw a violin plot from data instead of pre-computed statistics.
+        .cbook.violin_stats:
+            Calculate a *vpstats* dictionary from data, suitable for passing to violin.
         """
 
         # Statistical quantities to be plotted on the violins

lib/matplotlib/cbook.py

@@ -1443,7 +1443,7 @@ def violin_stats(X, method=("GaussianKDE", "scott"), points=100, quantiles=None)
     dictionary.
 
     Users can skip this function and pass a user-defined set of dictionaries
-    with the same keys to `~.axes.Axes.violinplot` instead of using Matplotlib
+    with the same keys to `~.axes.Axes.violin` instead of using Matplotlib
     to do the calculations. See the *Returns* section below for the keys
     that must be present in the dictionaries.
 
@@ -1471,6 +1471,9 @@ def method(data: ndarray, coords: ndarray) -> ndarray
 
           It should return the KDE of *data* evaluated at *coords*.
 
+          .. versionadded:: 3.11
+             Support for ``(name, bw_method)`` tuple.
+
     points : int, default: 100
         Defines the number of points to evaluate each of the gaussian kernel
         density estimates at.