add side option for violinplot

add test for side option in violinplot

add whats new for side in violinplot

add violin side option to _axes.pyi and pyplot.py

use side option in violinplot also for lines

add side option to violinplot example

use newer style and correct seed in violin test

update image

change option naming

use proper syntax for code in violin docs

Co-authored-by: Kyle Sunden <[email protected]>

add changed violinplots (capstyle=projecting)

hardcode capstyle only for left-right violins

fix typo

Author: Anja Beck

doc/users/next_whats_new/sides_violinplot.rst

@@ -0,0 +1,4 @@
+Add option to plot only one half of violin plot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting the parameter *side* to 'low' or 'high' allows to only plot one half of the violin plot.

galleries/examples/statistics/violinplot.py

@@ -28,55 +28,73 @@
 pos = [1, 2, 4, 5, 7, 8]
 data = [np.random.normal(0, std, size=100) for std in pos]
 
-fig, axs = plt.subplots(nrows=2, ncols=5, figsize=(10, 6))
+fig, axs = plt.subplots(nrows=2, ncols=6, figsize=(10, 4))
 
 axs[0, 0].violinplot(data, pos, points=20, widths=0.3,
                      showmeans=True, showextrema=True, showmedians=True)
-axs[0, 0].set_title('Custom violinplot 1', fontsize=fs)
+axs[0, 0].set_title('Custom violin 1', fontsize=fs)
 
 axs[0, 1].violinplot(data, pos, points=40, widths=0.5,
                      showmeans=True, showextrema=True, showmedians=True,
                      bw_method='silverman')
-axs[0, 1].set_title('Custom violinplot 2', fontsize=fs)
+axs[0, 1].set_title('Custom violin 2', fontsize=fs)
 
 axs[0, 2].violinplot(data, pos, points=60, widths=0.7, showmeans=True,
                      showextrema=True, showmedians=True, bw_method=0.5)
-axs[0, 2].set_title('Custom violinplot 3', fontsize=fs)
+axs[0, 2].set_title('Custom violin 3', fontsize=fs)
 
 axs[0, 3].violinplot(data, pos, points=60, widths=0.7, showmeans=True,
                      showextrema=True, showmedians=True, bw_method=0.5,
                      quantiles=[[0.1], [], [], [0.175, 0.954], [0.75], [0.25]])
-axs[0, 3].set_title('Custom violinplot 4', fontsize=fs)
+axs[0, 3].set_title('Custom violin 4', fontsize=fs)
 
 axs[0, 4].violinplot(data[-1:], pos[-1:], points=60, widths=0.7,
                      showmeans=True, showextrema=True, showmedians=True,
                      quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5)
-axs[0, 4].set_title('Custom violinplot 5', fontsize=fs)
+axs[0, 4].set_title('Custom violin 5', fontsize=fs)
+
+axs[0, 5].violinplot(data[-1:], pos[-1:], points=60, widths=0.7,
+                     showmeans=True, showextrema=True, showmedians=True,
+                     quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5, side='low')
+
+axs[0, 5].violinplot(data[-1:], pos[-1:], points=60, widths=0.7,
+                     showmeans=True, showextrema=True, showmedians=True,
+                     quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5, side='high')
+axs[0, 5].set_title('Custom violin 6', fontsize=fs)
 
 axs[1, 0].violinplot(data, pos, points=80, vert=False, widths=0.7,
                      showmeans=True, showextrema=True, showmedians=True)
-axs[1, 0].set_title('Custom violinplot 6', fontsize=fs)
+axs[1, 0].set_title('Custom violin 7', fontsize=fs)
 
 axs[1, 1].violinplot(data, pos, points=100, vert=False, widths=0.9,
                      showmeans=True, showextrema=True, showmedians=True,
                      bw_method='silverman')
-axs[1, 1].set_title('Custom violinplot 7', fontsize=fs)
+axs[1, 1].set_title('Custom violin 8', fontsize=fs)
 
 axs[1, 2].violinplot(data, pos, points=200, vert=False, widths=1.1,
                      showmeans=True, showextrema=True, showmedians=True,
                      bw_method=0.5)
-axs[1, 2].set_title('Custom violinplot 8', fontsize=fs)
+axs[1, 2].set_title('Custom violin 9', fontsize=fs)
 
 axs[1, 3].violinplot(data, pos, points=200, vert=False, widths=1.1,
                      showmeans=True, showextrema=True, showmedians=True,
                      quantiles=[[0.1], [], [], [0.175, 0.954], [0.75], [0.25]],
                      bw_method=0.5)
-axs[1, 3].set_title('Custom violinplot 9', fontsize=fs)
+axs[1, 3].set_title('Custom violin 10', fontsize=fs)
 
 axs[1, 4].violinplot(data[-1:], pos[-1:], points=200, vert=False, widths=1.1,
                      showmeans=True, showextrema=True, showmedians=True,
                      quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5)
-axs[1, 4].set_title('Custom violinplot 10', fontsize=fs)
+axs[1, 4].set_title('Custom violin 11', fontsize=fs)
+
+axs[1, 5].violinplot(data[-1:], pos[-1:], points=200, vert=False, widths=1.1,
+                     showmeans=True, showextrema=True, showmedians=True,
+                     quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5, side='low')
+
+axs[1, 5].violinplot(data[-1:], pos[-1:], points=200, vert=False, widths=1.1,
+                     showmeans=True, showextrema=True, showmedians=True,
+                     quantiles=[0.05, 0.1, 0.8, 0.9], bw_method=0.5, side='high')
+axs[1, 5].set_title('Custom violin 12', fontsize=fs)
 
 
 for ax in axs.flat:

lib/matplotlib/axes/_axes.py

@@ -8205,7 +8205,7 @@ def matshow(self, Z, **kwargs):
     @_preprocess_data(replace_names=["dataset"])
     def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
                    showmeans=False, showextrema=True, showmedians=False,
-                   quantiles=None, points=100, bw_method=None):
+                   quantiles=None, points=100, bw_method=None, side='both'):
         """
         Make a violin plot.
 
@@ -8258,6 +8258,10 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
           its only parameter and return a scalar. If None (default), 'scott'
           is used.
 
+        side : {'both', 'low', 'high'}, default: 'both'
+            'both' plots standard violins. 'low'/'high' only
+            plots the side below/above the positions value.
+
         data : indexable object, optional
             DATA_PARAMETER_PLACEHOLDER
 
@@ -8309,10 +8313,10 @@ def _kde_method(X, coords):
                                      quantiles=quantiles)
         return self.violin(vpstats, positions=positions, vert=vert,
                            widths=widths, showmeans=showmeans,
-                           showextrema=showextrema, showmedians=showmedians)
+                           showextrema=showextrema, showmedians=showmedians, side=side)
 
     def violin(self, vpstats, positions=None, vert=True, widths=0.5,
-               showmeans=False, showextrema=True, showmedians=False):
+               showmeans=False, showextrema=True, showmedians=False, side='both'):
         """
         Draw a violin plot from pre-computed statistics.
 
@@ -8368,6 +8372,10 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
         showmedians : bool, default: False
           If true, will toggle rendering of the medians.
 
+        side : {'both', 'low', 'high'}, default: 'both'
+            'both' plots standard violins. 'low'/'high' only
+            plots the side below/above the positions value.
+
         Returns
         -------
         dict
@@ -8430,8 +8438,13 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
         elif len(widths) != N:
             raise ValueError(datashape_message.format("widths"))
 
+        # Validate side
+        _api.check_in_list(["both", "low", "high"], side=side)
+
         # Calculate ranges for statistics lines (shape (2, N)).
-        line_ends = [[-0.25], [0.25]] * np.array(widths) + positions
+        line_ends = [[-0.25 if side in ['both', 'low'] else 0],
+                     [0.25 if side in ['both', 'high'] else 0]] \
+                          * np.array(widths) + positions
 
         # Colors.
         if mpl.rcParams['_internal.classic_mode']:
@@ -8443,20 +8456,34 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
         # Check whether we are rendering vertically or horizontally
         if vert:
             fill = self.fill_betweenx
-            perp_lines = functools.partial(self.hlines, colors=linecolor)
-            par_lines = functools.partial(self.vlines, colors=linecolor)
+            if side in ['low', 'high']:
+                perp_lines = functools.partial(self.hlines, colors=linecolor,
+                                                capstyle='projecting')
+                par_lines = functools.partial(self.vlines, colors=linecolor,
+                                                capstyle='projecting')
+            else:
+                perp_lines = functools.partial(self.hlines, colors=linecolor)
+                par_lines = functools.partial(self.vlines, colors=linecolor)
         else:
             fill = self.fill_between
-            perp_lines = functools.partial(self.vlines, colors=linecolor)
-            par_lines = functools.partial(self.hlines, colors=linecolor)
+            if side in ['low', 'high']:
+                perp_lines = functools.partial(self.vlines, colors=linecolor,
+                                                capstyle='projecting')
+                par_lines = functools.partial(self.hlines, colors=linecolor,
+                                                capstyle='projecting')
+            else:
+                perp_lines = functools.partial(self.vlines, colors=linecolor)
+                par_lines = functools.partial(self.hlines, colors=linecolor)
 
         # Render violins
         bodies = []
         for stats, pos, width in zip(vpstats, positions, widths):
             # The 0.5 factor reflects the fact that we plot from v-p to v+p.
             vals = np.array(stats['vals'])
             vals = 0.5 * width * vals / vals.max()
-            bodies += [fill(stats['coords'], -vals + pos, vals + pos,
+            bodies += [fill(stats['coords'],
+                            -vals + pos if side in ['both', 'low'] else pos,
+                            vals + pos if side in ['both', 'high'] else pos,
                             facecolor=fillcolor, alpha=0.3)]
             means.append(stats['mean'])
             mins.append(stats['min'])

lib/matplotlib/axes/_axes.pyi

@@ -743,6 +743,7 @@ class Axes(_AxesBase):
         | float
         | Callable[[GaussianKDE], float]
         | None = ...,
+        side: Literal["both", "low", "high"] = ...,
         *,
         data=...,
     ) -> dict[str, Collection]: ...
@@ -755,6 +756,7 @@ class Axes(_AxesBase):
         showmeans: bool = ...,
         showextrema: bool = ...,
         showmedians: bool = ...,
+        side: Literal["both", "low", "high"] = ...,
     ) -> dict[str, Collection]: ...
 
     table = mtable.table

lib/matplotlib/pyplot.py

@@ -4075,6 +4075,7 @@ def violinplot(
     | float
     | Callable[[GaussianKDE], float]
     | None = None,
+    side: Literal["both", "low", "high"] = "both",
     *,
     data=None,
 ) -> dict[str, Collection]:
@@ -4089,6 +4090,7 @@ def violinplot(
         quantiles=quantiles,
         points=points,
         bw_method=bw_method,
+        side=side,
         **({"data": data} if data is not None else {}),
     )
 

lib/matplotlib/tests/baseline_images/test_axes/violinplot_sides.png

@@ -3794,6 +3794,21 @@ def test_horiz_violinplot_custompoints_200():
                   showextrema=False, showmedians=False, points=200)
 
 
+@image_comparison(['violinplot_sides.png'], remove_text=True, style='mpl20')
+def test_violinplot_sides():
+    ax = plt.axes()
+    np.random.seed(19680801)
+    data = [np.random.normal(size=100)]
+    # Check horizontal violinplot
+    for pos, side in zip([0, -0.5, 0.5], ['both', 'low', 'high']):
+        ax.violinplot(data, positions=[pos], vert=False, showmeans=False,
+                      showextrema=True, showmedians=True, side=side)
+    # Check vertical violinplot
+    for pos, side in zip([4, 3.5, 4.5], ['both', 'low', 'high']):
+        ax.violinplot(data, positions=[pos], vert=True, showmeans=False,
+                      showextrema=True, showmedians=True, side=side)
+
+
 def test_violinplot_bad_positions():
     ax = plt.axes()
     # First 9 digits of frac(sqrt(47))