ENH: add option to label pie charts with absolute values

rcomer · rcomer · commit 925704e78cb5 · 2024-11-17T16:41:58.000Z
diff --git a/doc/api/next_api_changes/deprecations/29152-REC.rst b/doc/api/next_api_changes/deprecations/29152-REC.rst
@@ -0,0 +1,4 @@
+The *pctdistance* parameter of ``Axes.pie``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is deprecated.  Please use *autodistance* instead.
diff --git a/doc/users/next_whats_new/pie_abs_labels.rst b/doc/users/next_whats_new/pie_abs_labels.rst
@@ -0,0 +1,18 @@
+Label pie charts with absolute input values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pie charts may now be automatically labelled with the original input values
+using the new *absolutefmt* parameter in `~.Axes.pie`.
+
+.. plot::
+    :include-source: true
+    :alt: Pie chart with each wedge labelled with its input value
+
+    import matplotlib.pyplot as plt
+
+    x = [4, 2, 1]
+
+    fig, ax = plt.subplots()
+    ax.pie(x, absolutefmt='%d')
+
+    plt.show()
diff --git a/galleries/examples/pie_and_polar_charts/pie_and_donut_labels.py b/galleries/examples/pie_and_polar_charts/pie_and_donut_labels.py
@@ -15,14 +15,14 @@
 # Now it's time for the pie. Starting with a pie recipe, we create the data
 # and a list of labels from it.
 #
-# We can provide a function to the ``autopct`` argument, which will expand
-# automatic percentage labeling by showing absolute values; we calculate
-# the latter back from relative data and the known sum of all values.
+# We can provide a function to the *absolutefmt* argument, which will expand
+# automatic labeling by also showing percentages.  Note that if we **only**
+# wanted percentages then we could more simply use the *autopct* parameter.
 #
 # We then create the pie and store the returned objects for later.  The first
 # returned element of the returned tuple is a list of the wedges.  Those are
 # `matplotlib.patches.Wedge` patches, which can directly be used as the handles
-# for a legend. We can use the legend's ``bbox_to_anchor`` argument to position
+# for a legend. We can use the legend's *bbox_to_anchor* argument to position
 # the legend outside of the pie. Here we use the axes coordinates ``(1, 0, 0.5,
 # 1)`` together with the location ``"center left"``; i.e. the left central
 # point of the legend will be at the left central point of the bounding box,
@@ -38,17 +38,17 @@
           "250 g butter",
           "300 g berries"]
 
-data = [float(x.split()[0]) for x in recipe]
+data = [int(x.split()[0]) for x in recipe]
 ingredients = [x.split()[-1] for x in recipe]
+total = np.sum(data)
 
 
-def func(pct, allvals):
-    absolute = int(np.round(pct/100.*np.sum(allvals)))
-    return f"{pct:.1f}%\n({absolute:d} g)"
+def func(value):
+    fraction = value / total
+    return f"{fraction:.1%}\n({value:d} g)"
 
 
-wedges, texts, autotexts = ax.pie(data, autopct=lambda pct: func(pct, data),
-                                  textprops=dict(color="w"))
+wedges, texts, autotexts = ax.pie(data, absolutefmt=func, textprops=dict(color="w"))
 
 ax.legend(wedges, ingredients,
           title="Ingredients",
@@ -66,9 +66,9 @@ def func(pct, allvals):
 # Now it's time for the donut. Starting with a donut recipe, we transcribe
 # the data to numbers (converting 1 egg to 50 g), and directly plot the pie.
 # The pie? Wait... it's going to be donut, is it not?
-# Well, as we see here, the donut is a pie, having a certain ``width`` set to
+# Well, as we see here, the donut is a pie, having a certain *width* set to
 # the wedges, which is different from its radius. It's as easy as it gets.
-# This is done via the ``wedgeprops`` argument.
+# This is done via the *wedgeprops* argument.
 #
 # We then want to label the wedges via
 # `annotations <matplotlib.axes.Axes.annotate>`. We first create some
diff --git a/galleries/examples/pie_and_polar_charts/pie_features.py b/galleries/examples/pie_and_polar_charts/pie_features.py
@@ -34,13 +34,19 @@
 # Auto-label slices
 # -----------------
 #
-# Pass a function or format string to *autopct* to label slices.
+# Pass a function or format string to *absolutefmt* to label slices with your
+# input values...
+
+fig, ax = plt.subplots()
+ax.pie(sizes, labels=labels, absolutefmt='%d')
+
+# %%
+# ...or to *autopct* to label slices with the percent sizes of the slice.
 
 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
 # ------------
@@ -63,15 +69,15 @@
 # %%
 # Swap label and autopct text positions
 # -------------------------------------
-# Use the *labeldistance* and *pctdistance* parameters to position the *labels*
+# Use the *labeldistance* and *autodistance* parameters 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)
+       autodistance=1.25, labeldistance=.6)
 
 # %%
-# *labeldistance* and *pctdistance* are ratios of the radius; therefore they
+# *labeldistance* and *autodistance* are ratios of the radius; therefore they
 # vary between ``0`` for the center of the pie and ``1`` for the edge of the
 # pie, and can be set to greater than ``1`` to place text outside the pie.
 #
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3154,13 +3154,13 @@ 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")
+    @_api.rename_parameter("3.11", "pctdistance", "autodistance")
     @_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,
+    def pie(self, x, *, explode=None, labels=None, colors=None, absolutefmt=None,
+            autopct=None, autodistance=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, hatch=None):
+            frame=False, rotatelabels=False, normalize=True, hatch=None):
         """
         Plot a pie chart.
 
@@ -3193,18 +3193,38 @@ def pie(self, x, explode=None, labels=None, colors=None,
 
             .. versionadded:: 3.7
 
+        absolutefmt  : None or str or callable, default: None
+            If not *None*, *absolutefmt* is a string or function used to label
+            the wedges with their original numeric values. The label will be
+            placed according to *autodistance*. If *absolutefmt* is a format
+            string, the label will be ``fmt % number``. If *absolutefmt* is a
+            function, then it will be called.  Cannot be used at the same time
+            as *autopct*.
+
+            .. versionadded:: 3.11
+
         autopct : None or str or callable, default: None
             If not *None*, *autopct* is a string or function used to label the
-            wedges with their numeric value. The label will be placed inside
-            the wedge. If *autopct* is a format string, the label will be
-            ``fmt % pct``. If *autopct* is a function, then it will be called.
+            wedges with their percentage values. The label will be placed
+            according to *autodistance*. If *autopct* is a format string, the
+            label will be ``fmt % pct``. If *autopct* is a function, then it
+            will be called.  Cannot be used at the same time as *absolutefmt*.
+
+        autodistance : float, default: 0.6
+            The relative distance along the radius at which the text
+            generated by *absolutefmt* or *autopct* is drawn. To draw the text
+            outside the pie, set *autodistance* > 1. This parameter is ignored
+            if both *absolutefmt* and *autopct* are ``None``.
 
         pctdistance : float, default: 0.6
             The relative distance along the radius at which 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``.
 
+            .. deprecated:: 3.11
+                Use *autodistance* instead.
+
         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.
@@ -3275,9 +3295,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
         The Axes aspect ratio can be controlled with `.Axes.set_aspect`.
         """
         self.set_aspect('equal')
-        # The use of float32 is "historical", but can't be changed without
-        # regenerating the test baselines.
-        x = np.asarray(x, np.float32)
+        x = np.asarray(x)
         if x.ndim > 1:
             raise ValueError("x must be 1D")
 
@@ -3287,9 +3305,11 @@ def pie(self, x, explode=None, labels=None, colors=None,
         sx = x.sum()
 
         if normalize:
-            x = x / sx
+            fracs = x / sx
         elif sx > 1:
             raise ValueError('Cannot plot an unnormalized pie with sum(x) > 1')
+        else:
+            fracs = x
         if labels is None:
             labels = [''] * len(x)
         if explode is None:
@@ -3324,7 +3344,7 @@ def get_next_color():
         slices = []
         autotexts = []
 
-        for frac, label, expl in zip(x, labels, explode):
+        for n, frac, label, expl in zip(x, fracs, labels, explode):
             x, y = center
             theta2 = (theta1 + frac) if counterclock else (theta1 - frac)
             thetam = 2 * np.pi * 0.5 * (theta1 + theta2)
@@ -3369,15 +3389,33 @@ def get_next_color():
                 texts.append(t)
 
             if autopct is not None:
-                xt = x + pctdistance * radius * math.cos(thetam)
-                yt = y + pctdistance * radius * math.sin(thetam)
+                if absolutefmt is not None:
+                    raise ValueError('Only one of autopct and absolutefmt may be used.')
                 if isinstance(autopct, str):
                     s = autopct % (100. * frac)
                 elif callable(autopct):
                     s = autopct(100. * frac)
                 else:
                     raise TypeError(
                         'autopct must be callable or a format string')
+                autolabels = True
+
+            elif absolutefmt is not None:
+                if isinstance(absolutefmt, str):
+                    s = absolutefmt % n
+                elif callable(absolutefmt):
+                    s = absolutefmt(n)
+                else:
+                    raise TypeError(
+                        'absolutefmt must be callable or a format string')
+                autolabels = True
+
+            else:
+                autolabels = False
+
+            if autolabels:
+                xt = x + autodistance * radius * math.cos(thetam)
+                yt = y + autodistance * radius * math.sin(thetam)
                 if mpl._val_or_rc(textprops.get("usetex"), "text.usetex"):
                     # escape % (i.e. \%) if it is not already escaped
                     s = re.sub(r"([^\\])%", r"\1\\%", s)
@@ -3397,7 +3435,7 @@ def get_next_color():
                      xlim=(-1.25 + center[0], 1.25 + center[0]),
                      ylim=(-1.25 + center[1], 1.25 + center[1]))
 
-        if autopct is None:
+        if not autotexts:
             return slices, texts
         else:
             return slices, texts, autotexts
diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
@@ -299,8 +299,9 @@ class Axes(_AxesBase):
         explode: ArrayLike | None = ...,
         labels: Sequence[str] | None = ...,
         colors: ColorType | Sequence[ColorType] | None = ...,
+        absolutefmt: str | Callable[[float], str] | None = ...,
         autopct: str | Callable[[float], str] | None = ...,
-        pctdistance: float = ...,
+        autodistance: float = ...,
         shadow: bool = ...,
         labeldistance: float | None = ...,
         startangle: float = ...,
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -3772,11 +3772,13 @@ def phase_spectrum(
 @_copy_docstring_and_deprecators(Axes.pie)
 def pie(
     x: ArrayLike,
+    *,
     explode: ArrayLike | None = None,
     labels: Sequence[str] | None = None,
     colors: ColorType | Sequence[ColorType] | None = None,
+    absolutefmt: str | Callable[[float], str] | None = None,
     autopct: str | Callable[[float], str] | None = None,
-    pctdistance: float = 0.6,
+    autodistance: float = 0.6,
     shadow: bool = False,
     labeldistance: float | None = 1.1,
     startangle: float = 0,
@@ -3787,7 +3789,6 @@ def pie(
     center: tuple[float, float] = (0, 0),
     frame: bool = False,
     rotatelabels: bool = False,
-    *,
     normalize: bool = True,
     hatch: str | Sequence[str] | None = None,
     data=None,
@@ -3797,8 +3798,9 @@ def pie(
         explode=explode,
         labels=labels,
         colors=colors,
+        absolutefmt=absolutefmt,
         autopct=autopct,
-        pctdistance=pctdistance,
+        autodistance=autodistance,
         shadow=shadow,
         labeldistance=labeldistance,
         startangle=startangle,
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -5961,6 +5961,39 @@ def test_pie_default():
             autopct='%1.1f%%', shadow=True, startangle=90)
 
 
+def test_pie_abs():
+    labels = ['Frogs', 'Hogs', 'Dogs', 'Logs']
+    sizes = [15, 30, 45, 10]
+    fig1, ax1 = plt.subplots(figsize=(8, 6))
+    slices, texts, autotexts = ax1.pie(
+        sizes, labels=labels, absolutefmt='%d')
+
+    assert [txt.get_text() for txt in texts] == labels
+    assert [txt.get_text() for txt in autotexts] == [str(size) for size in sizes]
+
+
+def test_pie_abs_func():
+    labels = ['Frogs', 'Hogs', 'Dogs', 'Logs']
+    sizes = [15, 30, 45, 10]
+    fig1, ax1 = plt.subplots(figsize=(8, 6))
+
+    def double(n):
+        return n * 2
+
+    slices, texts, autotexts = ax1.pie(
+        sizes, labels=labels, absolutefmt=double)
+
+    assert [txt.get_text() for txt in texts] == labels
+    assert [txt.get_text() for txt in autotexts] == [str(size * 2) for size in sizes]
+
+
+def test_pie_both_number_formats():
+    sizes = [15, 30, 45, 10]
+    fig1, ax1 = plt.subplots(figsize=(8, 6))
+    with pytest.raises(ValueError, match='Only one of autopct and absolutefmt'):
+        ax1.pie(sizes, absolutefmt='%d', autopct='%1.1f%%')
+
+
 @image_comparison(['pie_linewidth_0', 'pie_linewidth_0', 'pie_linewidth_0'],
                   extensions=['png'], style='mpl20', tol=0.01)
 def test_pie_linewidth_0():
