added hatch kwarg arg + tests + what's new

story645 · oscargus · sledziu32 · story645 · commit 60f9af8ec181 · 2022-12-22T01:22:01.000-05:00
expanded basic pie example to include small examples of labels, autopct, colors, hatch, and distance reworded pctdistance and labeldistance b/c of #24789 Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com> Co-authored-by: sledziu32 <sledziu32@gmail.com>
diff --git a/doc/users/next_whats_new/pie_hatch.rst b/doc/users/next_whats_new/pie_hatch.rst
@@ -0,0 +1,14 @@
+``hatch`` *kwarg* for pie
+-------------------------------------------
+
+`~matplotlib.axes.Axes.pie` now accepts a *hatch* keyword that takes as input
+a hatch or list of hatches:
+
+.. plot::
+    :include-source: true
+
+    fig, (ax1, ax2) = plt.subplots(ncols=2)
+    w1,_ = ax1.pie([1,1,1,1], hatch='\/|-', colors=['whitesmoke','silver'],
+                    wedgeprops={'edgecolor':'dimgray'})
+    w2,_ = ax2.pie([1,1,1,1], hatch=[ '-O', '-', '-.O', '-.'],
+                    colors=['thistle'], wedgeprops={'edgecolor':'darkmagenta'})
diff --git a/examples/pie_and_polar_charts/pie_features.py b/examples/pie_and_polar_charts/pie_features.py
@@ -3,39 +3,102 @@
 Basic pie chart
 ===============
 
-Demo of a basic pie chart plus a few additional features.
-
-In addition to the basic pie chart, this demo shows a few optional features:
-
-* slice labels
-* auto-labeling the percentage
-* offsetting a slice with "explode"
-* drop-shadow
-* custom start angle
+Demo of plotting a `~matplotlib.axes.Axes.pie` chart
+"""
 
-Note about the custom start angle:
+# %%
+# Label slices
+# ----------------
+#
+# Plot a pie chart of animals and label the slices. To add
+# labels, pass a list of labels to the *labels* keyword argument
 
-The default ``startangle`` is 0, which would start the "Frogs" slice on the
-positive x-axis. This example sets ``startangle = 90`` such that everything is
-rotated counter-clockwise by 90 degrees, and the frog slice starts on the
-positive y-axis.
-"""
 import matplotlib.pyplot as plt
-
-# Pie chart, where the slices will be ordered and plotted counter-clockwise:
 labels = 'Frogs', 'Hogs', 'Dogs', 'Logs'
 sizes = [15, 30, 45, 10]
-explode = (0, 0.1, 0, 0)  # only "explode" the 2nd slice (i.e. 'Hogs')
 
-fig1, ax1 = plt.subplots()
-ax1.pie(sizes, explode=explode, labels=labels, autopct='%1.1f%%',
-        shadow=True, startangle=90)
-ax1.axis('equal')  # Equal aspect ratio ensures that pie is drawn as a circle.
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels)
 
-plt.show()
+###############################################################################
+# Each slice of the pie chart is a `.patches.Wedge` object; therefore in
+# addition to the customizations shown here, each wedge can be customized as
+# demoed in :doc:`/gallery/pie_and_polar_charts/nested_pie`.
+
+# %%
+# Auto-label slices
+# ---------------------------
+#
+# The pie function can use a format string or function passed to *autopct* to
+# label slices.
+
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels, autopct='%1.1f%%')
+
+#################################################################
+# By default, the label values are obtained from the percent size of the slice.
+
+# %%
+# Color slices
+# ----------------
+#
+# Pass a list of colors to *colors* to set the color of each slice.
+
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels,
+       colors=['olivedrab', 'rosybrown', 'gray', 'saddlebrown'])
+
+# %%
+# Hatch slices
+# ----------------
+#
+# Pass a list of hatch patterns to *hatch* to set the pattern of each slice.
+
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels, hatch=['**O', 'oO', 'O.O', '.||.'])
+
+# %%
+# Swap label and autopct text positions
+# -------------------------------------
+# Use the *labeldistance* and *pctdistance* keywords to position the *labels*
+# and *autopct* text respectively.
+
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels, autopct='%1.1f%%',
+       pctdistance=1.25, labeldistance=.6)
 
 #############################################################################
+# *labeldistance* and *pctdistance* are ratios computed relative to the
+# distance of the radius, meaning that a distance of ``0`` places the text
+# at the center of the pie while ``1`` places the text at the edge of the pie.
+
+# %%
+# Explode, shade, and rotate slices
+# ---------------------------------
+#
+# In addition to the basic pie chart, this demo shows a few optional features:
+#
+# * offsetting a slice using *explode*
+# * add a drop-shadow using *shadow*
+# * custom start angle using *startangle*
 #
+# This example orders the slices, separates (explodes) them, and plots them
+# counter-clockwise:
+
+explode = (0, 0.1, 0, 0)  # only "explode" the 2nd slice (i.e. 'Hogs')
+
+fig, ax = plt.subplots()
+ax.pie(sizes, explode=explode, labels=labels, autopct='%1.1f%%',
+        shadow=True, startangle=90)
+plt.show()
+
+##############################################################################
+# The default *startangle* is 0, which would start the "Frogs" slice on the
+# positive x-axis. This example sets ``startangle = 90`` such that everything
+# is rotated counter-clockwise by 90 degrees, and the frog slice starts on the
+# positive y-axis.
+
+##############################################################################
 # .. admonition:: References
 #
 #    The use of the following functions, methods, classes and modules is shown
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3078,7 +3078,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
             autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
             startangle=0, radius=1, counterclock=True,
             wedgeprops=None, textprops=None, center=(0, 0),
-            frame=False, rotatelabels=False, *, normalize=True):
+            frame=False, rotatelabels=False, *, normalize=True, hatch=None):
         """
         Plot a pie chart.
 
@@ -3104,29 +3104,34 @@ def pie(self, x, explode=None, labels=None, colors=None,
             A sequence of colors through which the pie chart will cycle.  If
             *None*, will use the colors in the currently active cycle.
 
+        hatch : str or list, default: None
+            Hatching pattern applied to all pie wedges or sequence of patterns
+            through which the chart will cycle. For a list of valid patterns,
+            see :doc:`/gallery/shapes_and_collections/hatch_style_reference`
+
+            .. versionadded:: 3.7
+
         autopct : None or str or callable, default: None
-            If not *None*, is a string or function used to label the wedges
-            with their numeric value.  The label will be placed inside the
-            wedge.  If it is a format string, the label will be ``fmt % pct``.
-            If it is a function, it will be called.
+            If not *None*, *autopct* a string or function used to label the
+            wedges with their numeric value.  The label will be placed inside
+            the wedge.  If it is a format string, the label will be
+            ``fmt % pct``. If it is a function, it will be called.
 
         pctdistance : float, default: 0.6
-            The ratio between the center of each pie slice and the start of
-            the text generated by *autopct*.  Ignored if *autopct* is *None*.
+            The relative distance along the radius at which the the text
+            generated by *autopct* is drawn. To draw the text outside the pie,
+            set *pctdistance* > 1. This parameter is ignored if *autopct* is
+            ``None``.
+
+        labeldistance : float or None, default: 1.1
+            The relative distance along the radius at which the labels are
+            drawn. To draw the labels inside the pie, set  *labeldistance* < 1.
+            If set to ``None``, labels are not drawn but are still stored for
+            use in `.legend`.
 
         shadow : bool, default: False
             Draw a shadow beneath the pie.
 
-        normalize : bool, default: True
-            When *True*, always make a full pie by normalizing x so that
-            ``sum(x) == 1``. *False* makes a partial pie if ``sum(x) <= 1``
-            and raises a `ValueError` for ``sum(x) > 1``.
-
-        labeldistance : float or None, default: 1.1
-            The radial distance at which the pie labels are drawn.
-            If set to ``None``, label are not drawn, but are stored for use in
-            ``legend()``
-
         startangle : float, default: 0 degrees
             The angle by which the start of the pie is rotated,
             counterclockwise from the x-axis.
@@ -3138,11 +3143,11 @@ def pie(self, x, explode=None, labels=None, colors=None,
             Specify fractions direction, clockwise or counterclockwise.
 
         wedgeprops : dict, default: None
-            Dict of arguments passed to the wedge objects making the pie.
-            For example, you can pass in ``wedgeprops = {'linewidth': 3}``
-            to set the width of the wedge border lines equal to 3.
-            For more details, look at the doc/arguments of the wedge object.
-            By default, ``clip_on=False``.
+            Dict of arguments passed to each `.patches.Wedge` of the pie.
+            For example, ``wedgeprops = {'linewidth': 3}`` sets the width of
+            the wedge border lines equal to 3. By default, ``clip_on=False``.
+            When there is a conflict between these properties and other
+            keywords, properties passed to *wedgeprops* take precedence.
 
         textprops : dict, default: None
             Dict of arguments to pass to the text objects.
@@ -3156,6 +3161,11 @@ def pie(self, x, explode=None, labels=None, colors=None,
         rotatelabels : bool, default: False
             Rotate each label to the angle of the corresponding slice if true.
 
+        normalize : bool, default: True
+            When *True*, always make a full pie by normalizing x so that
+            ``sum(x) == 1``. *False* makes a partial pie if ``sum(x) <= 1``
+            and raises a `ValueError` for ``sum(x) > 1``.
+
         data : indexable object, optional
             DATA_PARAMETER_PLACEHOLDER
 
@@ -3226,7 +3236,9 @@ def get_next_color():
         slices = []
         autotexts = []
 
-        for frac, label, expl in zip(x, labels, explode):
+        hatch = itertools.cycle(np.atleast_1d(hatch))
+
+        for frac, label, expl, htch in zip(x, labels, explode, hatch):
             x, y = center
             theta2 = (theta1 + frac) if counterclock else (theta1 - frac)
             thetam = 2 * np.pi * 0.5 * (theta1 + theta2)
@@ -3236,6 +3248,7 @@ def get_next_color():
             w = mpatches.Wedge((x, y), radius, 360. * min(theta1, theta2),
                                360. * max(theta1, theta2),
                                facecolor=get_next_color(),
+                               hatch=htch,
                                clip_on=False,
                                label=label)
             w.set(**wedgeprops)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2755,15 +2755,15 @@ def pie(
         pctdistance=0.6, shadow=False, labeldistance=1.1,
         startangle=0, radius=1, counterclock=True, wedgeprops=None,
         textprops=None, center=(0, 0), frame=False,
-        rotatelabels=False, *, normalize=True, data=None):
+        rotatelabels=False, *, normalize=True, hatch=None, data=None):
     return gca().pie(
         x, explode=explode, labels=labels, colors=colors,
         autopct=autopct, pctdistance=pctdistance, shadow=shadow,
         labeldistance=labeldistance, startangle=startangle,
         radius=radius, counterclock=counterclock,
         wedgeprops=wedgeprops, textprops=textprops, center=center,
         frame=frame, rotatelabels=rotatelabels, normalize=normalize,
-        **({"data": data} if data is not None else {}))
+        hatch=hatch, **({"data": data} if data is not None else {}))
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -5740,6 +5740,24 @@ def test_normalize_kwarg_pie():
     assert abs(t2[0][-1].theta2 - 360.) > 1e-3
 
 
+@check_figures_equal()
+def test_pie_hatch_single(fig_test, fig_ref):
+    x = [0.3, 0.3, 0.1]
+    hatch = '+'
+    fig_test.subplots().pie(x, hatch=hatch)
+    wedges, _ = fig_ref.subplots().pie(x)
+    [w.set_hatch(hatch) for w in wedges]
+
+
+@check_figures_equal()
+def test_pie_hatch_multi(fig_test, fig_ref):
+    x = [0.3, 0.3, 0.1]
+    hatch = ['/', '+', '.']
+    fig_test.subplots().pie(x, hatch=hatch)
+    wedges, _ = fig_ref.subplots().pie(x)
+    [w.set_hatch(hp) for w, hp in zip(wedges, hatch)]
+
+
 @image_comparison(['set_get_ticklabels.png'])
 def test_set_get_ticklabels():
     # test issue 2246
