Merge pull request matplotlib#28074 from saranti/boxplot_vert

Add  `orientation` parameter to Boxplot and deprecate `vert`

Author: rcomer

doc/api/next_api_changes/deprecations/28074-TS.rst

@@ -0,0 +1,9 @@
+``boxplot`` and ``bxp`` *vert* parameter, and ``rcParams["boxplot.vertical"]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The parameter *vert: bool* has been deprecated on `~.Axes.boxplot` and
+`~.Axes.bxp`. It is replaced by *orientation: {"vertical", "horizontal"}*
+for API consistency.
+
+``rcParams["boxplot.vertical"]``, which controlled the orientation of ``boxplot``,
+is deprecated without replacement.

doc/users/next_whats_new/boxplot_orientation.rst

@@ -0,0 +1,21 @@
+``boxplot`` and ``bxp`` orientation parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Boxplots have a new parameter *orientation: {"vertical", "horizontal"}*
+to change the orientation of the plot. This replaces the deprecated
+*vert: bool* parameter.
+
+
+.. plot::
+    :include-source: true
+    :alt: Example of creating 4 horizontal boxplots.
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, ax = plt.subplots()
+    np.random.seed(19680801)
+    all_data = [np.random.normal(0, std, 100) for std in range(6, 10)]
+
+    ax.boxplot(all_data, orientation='horizontal')
+    plt.show()

galleries/examples/statistics/boxplot_demo.py

@@ -46,11 +46,11 @@
 axs[1, 0].set_title("don't show\noutlier points")
 
 # horizontal boxes
-axs[1, 1].boxplot(data, sym='rs', vert=False)
+axs[1, 1].boxplot(data, sym='rs', orientation='horizontal')
 axs[1, 1].set_title('horizontal boxes')
 
 # change whisker length
-axs[1, 2].boxplot(data, sym='rs', vert=False, whis=0.75)
+axs[1, 2].boxplot(data, sym='rs', orientation='horizontal', whis=0.75)
 axs[1, 2].set_title('change whisker length')
 
 fig.subplots_adjust(left=0.08, right=0.98, bottom=0.05, top=0.9,
@@ -107,7 +107,7 @@
 fig.canvas.manager.set_window_title('A Boxplot Example')
 fig.subplots_adjust(left=0.075, right=0.95, top=0.9, bottom=0.25)
 
-bp = ax1.boxplot(data, notch=False, sym='+', vert=True, whis=1.5)
+bp = ax1.boxplot(data, notch=False, sym='+', orientation='vertical', whis=1.5)
 plt.setp(bp['boxes'], color='black')
 plt.setp(bp['whiskers'], color='black')
 plt.setp(bp['fliers'], color='red', marker='+')

lib/matplotlib/axes/_axes.py

@@ -3819,9 +3819,10 @@ def apply_mask(arrays, mask):
     @_api.make_keyword_only("3.9", "notch")
     @_preprocess_data()
     @_api.rename_parameter("3.9", "labels", "tick_labels")
-    def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
-                positions=None, widths=None, patch_artist=None,
-                bootstrap=None, usermedians=None, conf_intervals=None,
+    def boxplot(self, x, notch=None, sym=None, vert=None,
+                orientation='vertical', whis=None, positions=None,
+                widths=None, patch_artist=None, bootstrap=None,
+                usermedians=None, conf_intervals=None,
                 meanline=None, showmeans=None, showcaps=None,
                 showbox=None, showfliers=None, boxprops=None,
                 tick_labels=None, flierprops=None, medianprops=None,
@@ -3877,9 +3878,21 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             the fliers.  If `None`, then the fliers default to 'b+'.  More
             control is provided by the *flierprops* parameter.
 
-        vert : bool, default: :rc:`boxplot.vertical`
-            If `True`, draws vertical boxes.
-            If `False`, draw horizontal boxes.
+        vert : bool, optional
+            .. deprecated:: 3.10
+                Use *orientation* instead.
+
+                If this is given during the deprecation period, it overrides
+                the *orientation* parameter.
+
+            If True, plots the boxes vertically.
+            If False, plots the boxes horizontally.
+
+        orientation : {'vertical', 'horizontal'}, default: 'vertical'
+            If 'horizontal', plots the boxes horizontally.
+            Otherwise, plots the boxes vertically.
+
+            .. versionadded:: 3.10
 
         whis : float or (float, float), default: 1.5
             The position of the whiskers.
@@ -4047,8 +4060,6 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                                        labels=tick_labels, autorange=autorange)
         if notch is None:
             notch = mpl.rcParams['boxplot.notch']
-        if vert is None:
-            vert = mpl.rcParams['boxplot.vertical']
         if patch_artist is None:
             patch_artist = mpl.rcParams['boxplot.patchartist']
         if meanline is None:
@@ -4148,13 +4159,14 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                            meanline=meanline, showfliers=showfliers,
                            capprops=capprops, whiskerprops=whiskerprops,
                            manage_ticks=manage_ticks, zorder=zorder,
-                           capwidths=capwidths, label=label)
+                           capwidths=capwidths, label=label,
+                           orientation=orientation)
         return artists
 
     @_api.make_keyword_only("3.9", "widths")
-    def bxp(self, bxpstats, positions=None, widths=None, vert=True,
-            patch_artist=False, shownotches=False, showmeans=False,
-            showcaps=True, showbox=True, showfliers=True,
+    def bxp(self, bxpstats, positions=None, widths=None, vert=None,
+            orientation='vertical', patch_artist=False, shownotches=False,
+            showmeans=False, showcaps=True, showbox=True, showfliers=True,
             boxprops=None, whiskerprops=None, flierprops=None,
             medianprops=None, capprops=None, meanprops=None,
             meanline=False, manage_ticks=True, zorder=None,
@@ -4213,9 +4225,21 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
             Either a scalar or a vector and sets the width of each cap.
             The default is ``0.5*(width of the box)``, see *widths*.
 
-        vert : bool, default: True
-            If `True` (default), makes the boxes vertical.
-            If `False`, makes horizontal boxes.
+        vert : bool, optional
+            .. deprecated:: 3.10
+                Use *orientation* instead.
+
+                If this is given during the deprecation period, it overrides
+                the *orientation* parameter.
+
+            If True, plots the boxes vertically.
+            If False, plots the boxes horizontally.
+
+        orientation : {'vertical', 'horizontal'}, default: 'vertical'
+            If 'horizontal', plots the boxes horizontally.
+            Otherwise, plots the boxes vertically.
+
+            .. versionadded:: 3.10
 
         patch_artist : bool, default: False
             If `False` produces boxes with the `.Line2D` artist.
@@ -4334,8 +4358,29 @@ def merge_kw_rc(subkey, explicit, zdelta=0, usemarker=True):
         if meanprops is None or removed_prop not in meanprops:
             mean_kw[removed_prop] = ''
 
+        # vert and orientation parameters are linked until vert's
+        # deprecation period expires. vert only takes precedence
+        # if set to False.
+        if vert is None:
+            vert = mpl.rcParams['boxplot.vertical']
+        else:
+            _api.warn_deprecated(
+                "3.10",
+                name="vert: bool",
+                alternative="orientation: {'vertical', 'horizontal'}"
+            )
+        if vert is False:
+            orientation = 'horizontal'
+        _api.check_in_list(['horizontal', 'vertical'], orientation=orientation)
+
+        if not mpl.rcParams['boxplot.vertical']:
+            _api.warn_deprecated(
+                "3.10",
+                name='boxplot.vertical', obj_type="rcparam"
+            )
+
         # vertical or horizontal plot?
-        maybe_swap = slice(None) if vert else slice(None, None, -1)
+        maybe_swap = slice(None) if orientation == 'vertical' else slice(None, None, -1)
 
         def do_plot(xs, ys, **kwargs):
             return self.plot(*[xs, ys][maybe_swap], **kwargs)[0]
@@ -4460,7 +4505,7 @@ def do_patch(xs, ys, **kwargs):
                     artist.set_label(lbl)
 
         if manage_ticks:
-            axis_name = "x" if vert else "y"
+            axis_name = "x" if orientation == 'vertical' else "y"
             interval = getattr(self.dataLim, f"interval{axis_name}")
             axis = self._axis_map[axis_name]
             positions = axis.convert_units(positions)

lib/matplotlib/axes/_axes.pyi

@@ -350,6 +350,7 @@ class Axes(_AxesBase):
         notch: bool | None = ...,
         sym: str | None = ...,
         vert: bool | None = ...,
+        orientation: Literal["vertical", "horizontal"] = ...,
         whis: float | tuple[float, float] | None = ...,
         positions: ArrayLike | None = ...,
         widths: float | ArrayLike | None = ...,
@@ -382,7 +383,8 @@ class Axes(_AxesBase):
         positions: ArrayLike | None = ...,
         *,
         widths: float | ArrayLike | None = ...,
-        vert: bool = ...,
+        vert: bool | None = ...,
+        orientation: Literal["vertical", "horizontal"] = ...,
         patch_artist: bool = ...,
         shownotches: bool = ...,
         showmeans: bool = ...,

lib/matplotlib/mpl-data/stylelib/classic.mplstyle

@@ -380,7 +380,6 @@ boxplot.showbox: True
 boxplot.showcaps: True
 boxplot.showfliers: True
 boxplot.showmeans: False
-boxplot.vertical: True
 boxplot.whiskerprops.color: b
 boxplot.whiskerprops.linestyle: --
 boxplot.whiskerprops.linewidth: 1.0

lib/matplotlib/pyplot.py

@@ -2935,6 +2935,7 @@ def boxplot(
     notch: bool | None = None,
     sym: str | None = None,
     vert: bool | None = None,
+    orientation: Literal["vertical", "horizontal"] = "vertical",
     whis: float | tuple[float, float] | None = None,
     positions: ArrayLike | None = None,
     widths: float | ArrayLike | None = None,
@@ -2967,6 +2968,7 @@ def boxplot(
         notch=notch,
         sym=sym,
         vert=vert,
+        orientation=orientation,
         whis=whis,
         positions=positions,
         widths=widths,