Deprecate positional use of most arguments of plotting functions

timhoffm · timhoffm · commit 83abf806671a · 2024-02-13T22:56:46.000+01:00
This increases maintainability for developers and disallows
bad practice of passing lots of positional arguments for users.
If in doubt, I've erred on the side of allowing as much positional
arguments
as possible as long as the intent of a call is still readable.

Note: This was originally motivated by bxp() and boxplot() having many
overlapping parameters but differently ordered.
While at it, I think it's better to rollout the change to
all plotting functions and communicate that in one go
rather than having lots of individual change notices over
time. Also, the freedom to reorder parameters only sets
in after the deprecation. So let's start this now.
diff --git a/doc/api/next_api_changes/deprecations/27786-TH.rst b/doc/api/next_api_changes/deprecations/27786-TH.rst
@@ -0,0 +1,7 @@
+Positional parameters in plotting functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many plotting functions will restrict positional arguments to the first few parameters
+in the future. All further configuration parameters will have to be passed as keyword
+arguments. This is to enforce better code and and allow for future changes with reduced
+risk of breaking existing code.
diff --git a/galleries/examples/statistics/boxplot_color.py b/galleries/examples/statistics/boxplot_color.py
@@ -3,52 +3,34 @@
 Box plots with custom fill colors
 =================================
 
-This plot illustrates how to create two types of box plots
-(rectangular and notched), and how to fill them with custom
-colors by accessing the properties of the artists of the
-box plots. Additionally, the ``labels`` parameter is used to
-provide x-tick labels for each sample.
-
-A good general reference on boxplots and their history can be found
-here: http://vita.had.co.nz/papers/boxplots.pdf
+To color each box of a box plot individually:
+
+1) use the keyword argument ``patch_artist=True`` to create filled boxes.
+2) loop through the created boxes and adapt their color.
 """
 
 import matplotlib.pyplot as plt
 import numpy as np
 
-# Random test data
 np.random.seed(19680801)
-all_data = [np.random.normal(0, std, size=100) for std in range(1, 4)]
-labels = ['x1', 'x2', 'x3']
-
-fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, figsize=(9, 4))
-
-# rectangular box plot
-bplot1 = ax1.boxplot(all_data,
-                     vert=True,  # vertical box alignment
-                     patch_artist=True,  # fill with color
-                     labels=labels)  # will be used to label x-ticks
-ax1.set_title('Rectangular box plot')
-
-# notch shape box plot
-bplot2 = ax2.boxplot(all_data,
-                     notch=True,  # notch shape
-                     vert=True,  # vertical box alignment
-                     patch_artist=True,  # fill with color
-                     labels=labels)  # will be used to label x-ticks
-ax2.set_title('Notched box plot')
+fruit_weights = [
+    np.random.normal(130, 10, size=100),
+    np.random.normal(125, 20, size=100),
+    np.random.normal(120, 30, size=100),
+]
+labels = ['peaches', 'oranges', 'tomatoes']
+colors = ['peachpuff', 'orange', 'tomato']
+
+fig, ax = plt.subplots()
+ax.set_ylabel('fruit weight (g)')
+
+bplot = ax.boxplot(fruit_weights,
+                   patch_artist=True,  # fill with color
+                   labels=labels)  # will be used to label x-ticks
 
 # fill with colors
-colors = ['pink', 'lightblue', 'lightgreen']
-for bplot in (bplot1, bplot2):
-    for patch, color in zip(bplot['boxes'], colors):
-        patch.set_facecolor(color)
-
-# adding horizontal grid lines
-for ax in [ax1, ax2]:
-    ax.yaxis.grid(True)
-    ax.set_xlabel('Three separate samples')
-    ax.set_ylabel('Observed values')
+for patch, color in zip(bplot['boxes'], colors):
+    patch.set_facecolor(color)
 
 plt.show()
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1057,6 +1057,7 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
         self._request_autoscale_view("x")
         return p
 
+    @_api.make_keyword_only("3.9", "label")
     @_preprocess_data(replace_names=["y", "xmin", "xmax", "colors"],
                       label_namer="y")
     def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
@@ -1148,6 +1149,7 @@ def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
             self._request_autoscale_view()
         return lines
 
+    @_api.make_keyword_only("3.9", "label")
     @_preprocess_data(replace_names=["x", "ymin", "ymax", "colors"],
                       label_namer="x")
     def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
@@ -1239,6 +1241,7 @@ def vlines(self, x, ymin, ymax, colors=None, linestyles='solid',
             self._request_autoscale_view()
         return lines
 
+    @_api.make_keyword_only("3.9", "orientation")
     @_preprocess_data(replace_names=["positions", "lineoffsets",
                                      "linelengths", "linewidths",
                                      "colors", "linestyles"])
@@ -1742,6 +1745,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
             self._request_autoscale_view("y")
         return lines
 
+    @_api.make_keyword_only("3.9", "tz")
     @_preprocess_data(replace_names=["x", "y"], label_namer="y")
     @_docstring.dedent_interpd
     def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
@@ -2045,6 +2049,7 @@ def acorr(self, x, **kwargs):
         """
         return self.xcorr(x, x, **kwargs)
 
+    @_api.make_keyword_only("3.9", "normed")
     @_preprocess_data(replace_names=["x", "y"], label_namer="y")
     def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
               usevlines=True, maxlags=10, **kwargs):
@@ -3112,6 +3117,7 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
         self.add_container(stem_container)
         return stem_container
 
+    @_api.make_keyword_only("3.9", "explode")
     @_preprocess_data(replace_names=["x", "explode", "labels", "colors"])
     def pie(self, x, explode=None, labels=None, colors=None,
             autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
@@ -3388,6 +3394,7 @@ def _errorevery_to_mask(x, errorevery):
         everymask[errorevery] = True
         return everymask
 
+    @_api.make_keyword_only("3.9", "ecolor")
     @_preprocess_data(replace_names=["x", "y", "xerr", "yerr"],
                       label_namer="y")
     @_docstring.dedent_interpd
@@ -3764,6 +3771,7 @@ def apply_mask(arrays, mask):
 
         return errorbar_container  # (l0, caplines, barcols)
 
+    @_api.make_keyword_only("3.9", "notch")
     @_preprocess_data()
     def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                 positions=None, widths=None, patch_artist=None,
@@ -4078,6 +4086,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
                            capwidths=capwidths)
         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,
@@ -4531,6 +4540,7 @@ def invalid_shape_exception(csize, xsize):
             colors = None  # use cmap, norm after collection is created
         return c, colors, edgecolors
 
+    @_api.make_keyword_only("3.9", "marker")
     @_preprocess_data(replace_names=["x", "y", "s", "linewidths",
                                      "edgecolors", "c", "facecolor",
                                      "facecolors", "color"],
@@ -4811,6 +4821,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
 
         return collection
 
+    @_api.make_keyword_only("3.9", "gridsize")
     @_preprocess_data(replace_names=["x", "y", "C"], label_namer="y")
     @_docstring.dedent_interpd
     def hexbin(self, x, y, C=None, gridsize=100, bins=None,
@@ -6590,6 +6601,7 @@ def clabel(self, CS, levels=None, **kwargs):
 
     #### Data analysis
 
+    @_api.make_keyword_only("3.9", "range")
     @_preprocess_data(replace_names=["x", 'weights'], label_namer="x")
     def hist(self, x, bins=None, range=None, density=False, weights=None,
              cumulative=False, bottom=None, histtype='bar', align='mid',
@@ -7134,6 +7146,7 @@ def stairs(self, values, edges=None, *,
         self._request_autoscale_view()
         return patch
 
+    @_api.make_keyword_only("3.9", "range")
     @_preprocess_data(replace_names=["x", "y", "weights"])
     @_docstring.dedent_interpd
     def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
@@ -7343,6 +7356,7 @@ def ecdf(self, x, weights=None, *, complementary=False,
             line.sticky_edges.x[:] = [0, 1]
         return line
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -7454,6 +7468,7 @@ def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
         else:
             return pxx, freqs, line
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x", "y"], label_namer="y")
     @_docstring.dedent_interpd
     def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -7556,6 +7571,7 @@ def csd(self, x, y, NFFT=None, Fs=None, Fc=None, detrend=None,
         else:
             return pxy, freqs, line
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7642,6 +7658,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, line
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7711,6 +7728,7 @@ def angle_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, lines[0]
 
+    @_api.make_keyword_only("3.9", "Fs")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
@@ -7780,6 +7798,7 @@ def phase_spectrum(self, x, Fs=None, Fc=None, window=None,
 
         return spec, freqs, lines[0]
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x", "y"])
     @_docstring.dedent_interpd
     def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
@@ -7844,6 +7863,7 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
 
         return cxy, freqs
 
+    @_api.make_keyword_only("3.9", "NFFT")
     @_preprocess_data(replace_names=["x"])
     @_docstring.dedent_interpd
     def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
@@ -8000,6 +8020,7 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,
 
         return spec, freqs, t, im
 
+    @_api.make_keyword_only("3.9", "precision")
     @_docstring.dedent_interpd
     def spy(self, Z, precision=0, marker=None, markersize=None,
             aspect='equal', origin="upper", **kwargs):
@@ -8190,6 +8211,7 @@ def matshow(self, Z, **kwargs):
             mticker.MaxNLocator(nbins=9, steps=[1, 2, 5, 10], integer=True))
         return im
 
+    @_api.make_keyword_only("3.9", "vert")
     @_preprocess_data(replace_names=["dataset"])
     def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
                    showmeans=False, showextrema=True, showmedians=False,
@@ -8295,6 +8317,7 @@ def _kde_method(X, coords):
                            widths=widths, showmeans=showmeans,
                            showextrema=showextrema, showmedians=showmedians)
 
+    @_api.make_keyword_only("3.9", "vert")
     def violin(self, vpstats, positions=None, vert=True, widths=0.5,
                showmeans=False, showextrema=True, showmedians=False):
         """
diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
