expanded basic pie example

story645 · story645 · commit f2636de90718 · 2023-01-10T20:03:49.000-05:00
added small examples of labels, autopct, colors, hatch, and distance in an attempt to scaffold up to exploding example addresses some of #24789
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
