What's new entry
Addition to Pie Charts example
Simplified Matplotlib Bakery

If we are touching the existing API, should we reconsider more fundamentally?

Currently, pie() has two sets of annotations

1. "label", which are strings and by default displayed outside next to the wedges
2. "pct", which are percent numbers and by default displayed inside the wedges

Some observations:

• "pct" is a too specific name, "numbers" would be better.
• That labels are outside and pct inside is an arbitrary choice.

What we fundamentally need to keep:

The two sets of annotations must stay. We'd loose functionality if we allowed only one label. Also, a generalization to more than two sets of annotations does not make sense.

Side-note: If I was designing this from scratch, I'd likely focus on location inner_label and outer_label, and each could be (i) an explicit list of strings (ii) a function (iii) a format-string, likely {}-based, because that allows direct percent-formatting without needing numeric action on our side. However, I belive this would be too much of a change for the current API.

Therefore, I propose to

• keep labels, label_distance as is
• introduce inner_labels and inner_label_distance. inner_labels should take (i) a list (ii) a function (iii) a {} format string
• autopct translates to inner_labels and giving both is an error. Discourage autopct in favor of inner_labels and describe the transition (note that autopct's %-format and callable take values that are scaled by 100).
• pctdistance translates to inner_label_distance and giving both is an error. Discourage pctdistance in favor of inner_labels_distance and state that you should use the variable that is matching to the one used to define the labels inner_labels=..., inner_label_distance=... and autopct=..., pctdistance=....
• optionally, expand labels to also take (ii) a function (iii) a {} format string

Does that sound reasonable?

I am not sure about inner_labels because there is nothing to stop you swapping the positions of these with labels (using the distance parameters), at which point they become outer labels. We also need some way to choose what is being passed through the function or format string: existing functionality is percentages but the feature request is to support the absolute values.

Edit: though I guess by supporting the list of strings we allow the users to format those absolute values however they like within a list comprehension before passing them in 🤔

Also note that labels is special because it will be automatically used by legend (and if you want them in the legend and not on the pie you set labeldistance=None). So that's another reason not to touch that. So the other labels could be named something relative to that: extra_labels, secondary_labels....?

The original proposal in #19338 was for wedgelabels, so just throwing that in...

What I've missed in my above thought is that {} direct percent-formatting takes case of the factor 100 between relative and percent numbers, but it does not solve the issue where to pass relative (or percent) vs. absolute numbers to the formatter. That extra information that we'd need to get in somehow.

I'm trying to find a consistent way to map the option space:

• We need potentially two labels per wedge, typically one of them is inside and one is outside, but the positions are freely adjustable.
• We have three kinds of information: 1. Fixed arbitray labels 2. absolute numbers 3. percent (or relative numbers)
  Note that the number variants are convenience. A user could take the input values, transform them to whatever string they want and pass them as fixed label.

There are two ways for structuring:

• Have two label mechanisms that are structurally equivalent (i.e. allow fixed values and numerics). The distinction would be the (default) position. This was my thought above.
• Distinguish by semantics, i.e. one set of args for fixed labels, one set of args for numeric labels, ...
  Here we actually get into some complication because either we have to define the sets of args (fixed, absolute, percent) but map them to two positions; or we have to merge absolute and percent to one parameter to one numbers parameter and add a flag to determine absolute vs relative. Either way is messy.

IMHO the "absolute values" request comes from the fact that the inner label is too specific in that it only handles percent. There's no API to get arbitrary text in there.

A minimal green-field approach would be inner_labels and outer_labels (or labels when considering compatibility) as lists of fixed texts. Everything else is convenience. Possibly, we don't even need absolute value support then. It is just pie(x, inner_labels=[f'{xi:.1f}' for xi in x]) IMHO this is even better - because more explicit - than pie(x, absolutefmt="%.1f"). Percent formatting is only marginally more complex pie(x, inner_labels=[[f'{xi:.1%}' for xi in x/x.sum()]).

I therefore revise my above proposal to the following minimal change:

• keep labels, label_distance as is
• introduce inner_labels and inner_label_distance. inner_labels should take a list only
• autopct translates to inner_labels and giving both is an error. Describe autopct as a higher-level convenience function to get percent values into inner_labels.
• Document pctdistance as equivalent to inner_label_distance and giving both is an error. State that you should use the variable that is matching to the one used to define the labels inner_labels=..., inner_label_distance=... and autopct=..., pctdistance=....

One can later decide whether both of the labels parameters should grow some formatting / function capability.

I've just read your comment on legend. That's actually making it more complicated.

plt.pie(x, labels=['a', 'b', 'c'])
plt.legend()

plots both the outer labels and the legend, which is most likely not what one wants. One has to additionally pass labeldistance=None, but that prevents using the outer labels for something else (e.g. absolute numbers).

Note that outer labels are a good option if wedges become tiny. Therefore I fundamenally would want capability to put anything outside, e.g.

I believe right now, the only way to add a legend there is explicitly passing the artists and legend labels to legend().

A green-field solution would be to have labels only for the legend and explicit outer_labels and inner_labels on top. This separates concerns. However that'd be quite disruptive.

I have to rethink what we can do here.

Edit: I think we could make a clean transition path for separating labels into labels (legend only) + outer_labels:

• If as user uses labels with a not-None labeldistance, they want an outer-wedge label. Add a deprecation here and state that they should use outer_labels (and outer_label_distance if needed). Add an additional note that they need to pass the same list to labels as well if they want to keep legend entries.
• If a user has used labels=..., labeldistance=None they only want and get a legend. Nothing to do for a start. One can deprecate and remove the labeldistance parameter, when the above deprecation on for labels generating outer texts has run out. Then labels will always only create legend entries and the labeldistance parameter has no effect anymore.

The only downside is the need for users to adapt their code. But that's inevitable if we want a logical separation between legend labels and wedge labels.

This all is independent of the "absolute value" topic, but would fit together with the proposed solution introducing inner_labels there.

I am not sure about inner_labels because there is nothing to stop you swapping the positions of these with labels (using the distance parameters)

I'm not concerned about this. Practically, there's no need to swap - you'll rather swap the lists passed to labels/inner_labels. But if you do that's a very conscious and explicit decision.

naming extra_labels, secondary_labels, wedge_labels

• wedge_labels is a bit ambiguous. While the inner labels are on the wedge, both labels are per-wedge. The outside labels in the plot above could also be regarded as "wedge_labels".
• extra_labels, secondary_labels implies a hierarchy, which IMHO does not exist. Both places are logically equivalent. Having extra_labels/secondary_labels without labels would be a valid use case, but sounds a bit awkward. Additionally, extra/secondary does not give you an idea what they are used for / where they will appear.

I am also wondering if it’s worth factoring out a public pie_label method, to rhyme with bar_label. The existing labels and autopct could remain as conveniences that internally call this method, but a user could also call it directly as many times as they like to get whatever combination of labels they like.

pie_label method: I'm a bit sceptical. If we didn't have labelling functionality at all in pie, that might be the way to go. But as is, there's not much new functionality to be introduced via a pie_label. More than two positions (inside/outside) would be a very edge case. And the fancy number formatting/percent stuff is quite optional, because you can do it out-of-the-box with little overhead I wouldn't introduce new just API for that.

What may be a good idea is a private _wedge_text() method as internal refactoring, which would simplify the label handling in pie.

OK let me see if I can summarise the current thinking:

• Introduce inner_labels and outer_labels which take a list of strings or a format string to be formatted with .format(abs=abs, frac=frac).
• Introduce inner_label_distance (default 0.6) and outer_label_distance (default 1.1) to specify how far the above are from the pie centre.
• Deprecate using labels with not-None labeldistance - direct to use outer labels instead.¹
• Discourage² using autopct in favour of inner_labels. Passing both is an error.
• Passing pctdistance and inner_labels is an error.
• Passing inner_label_distance and autopct is an error.

Good summary! This is one viable way to make the API more consistent.

I think we should offer the formatting option as it will be hard to discourage use of autopct if the replacement is less convenient.

formatting is a bit tricky because you have to decide whether the inputs should be absolute values or fractions. You cannot have both (at least not without an extra parameter ¹). I'm inclined to expect absolute values by default, and that would still not give a replacement for autopct. We could decide to go with relative values, but it feels a bit unintuitive pie(x, inner_labels="%.1f").

The function approach is a bit better, because you could support two signatures def fmt(abs_value: float) -> str and def fmt(abs_value: float, total: float) -> str. The first one is a simpler version for convenince, the second one would support percents as pie(values, inner_label=lambda x, total: f'{x/total:.1%'}).

Alternative: pie_label()

I've thought about this a bit more. The idea is fundamentally reasonable. On the plus side, we get better decoupling and full control over each label set - currently textprops are shared and rotatelabels only applies to the outside.

Problem 1: AFAICS, we cannot retrieve the underlying data value from a wedge. Therefore no external function can create labels based on the output of pie(). We'd likely need to create a semantic artist PieWedge or a kind of Pie container class to handle this.
Problem 2: Removing all labelling capability from pie and forcing the use of additional functions feels a bit drastic. The alternatives would be to keep some labelling capability and that's not great either: (i) Keeping labels as the simple generic variant keeps the entanglement with legend (ii) Keeping autopct is very specific (iii) changing to a new single labels API forces a migration and makes keeping an additional text labels API only half as valuable.

If feel this is less good than the summarized approach.

Completely green fielding this issue a I'm pretty ignorant about pie - I would personally get rid of autopcnt - it's not like our users cannot calculate the data in terms of a percentage, and the pie chart would look the same. Then the formatting of the quantitative label would be straightforward.

I would prioritise formatting fractions over absolute values:

• Since plotting fractions is basically the point of pie I don’t think it’s too unintuitive that those would have the convenience in terms of labelling. The canonical example would be pie(x, inner_labels="{:.1%}"). Also since pie already calculates the fractions in order to draw the wedges it feels a bit annoying/redundant for the user to have to pre-process the data just for the labels (even if it is a simple and cheap calculation).
• Absolute values are slightly more straightforward to convert to the desired string. In fact if the user has ints then they may not care about formatting, so they could just pass the list of numbers as labels and the Text constructor will take care of converting them to strings.

Edit: I guess you could detect whether the format string contains "%}". If it does, give it fractions. If not give it absolute values.

Edit: I guess you could detect whether the format string contains "%}". If it does, give it fractions. If not give it absolute values.

Yes, I've briefly thought about that too, but it's too much magic 🪄 . There's a standard expectation how {.1f} and {.1%} relate to each other. We shouldn't mess with that. Then let's rather do the "percent:..." or "relative:..." or "fraction:..." prefix to the format string.

Named placeholders would give a lot more flexibility...

In [2]: '{abs:d}'.format(abs=42, frac=0.8)
Out[2]: '42'

In [3]: '{frac:.1%}'.format(abs=42, frac=0.8)
Out[3]: '80.0%'

In [4]: '{abs:d} ({frac:.0%})'.format(abs=42, frac=0.8)
Out[4]: '42 (80%)'

Named placeholders would give a lot more flexibility...

Great idea. Add this format-string as acceptable input for inner_labels and outer_labels in #29152 (comment) and we have a compact and clean API.

The fundamental question is: Do we want to go through the hassle of repurposing labels to only apply to legend. If yes, this is the reasonable way forward. If no, only do inner_labels as a replacement of autopct. I'm 0.5 on going all the way (but slowly, i.e. start with a pending deprecation).

I am in favour of making labels only for legend.

• API consistency: almost everywhere that you pass label(s) in Matplotlib, you mean you want them in the legend.
• For the case where you want both a legend and numbers outside the wedges, using labels=list_of_strings, outer_labels=... is more intuitive to me (and simpler) than labels=list_of_strings, labeldistance=None, inner_labels=..., inner_label_distance=1.1.

Side note on naming: I've briefly pondered whether in would make sense to bikeshed outer_labels, inner_labels to replace the "label" part; motivation: set it more clearly apart from labels; e.g. go for wedge_text or similar. However, we have ample precedence for *_label usages independent of labels mapping to legend: bar_label, clabel (contour label), tick_labels, xlabel, ylabel. Therefore outer_labels and inner_labels seem perfectly fine.

Edit: The only other alternative that may be worth considering is to make a single wedge_labels, wedge_label_distance that accepts a single list or a tuple of lists so that one can do:

plt.pie(x, wedge_labels=['a', 'b', 'c'], wedge_label_distance=0.5)
plt.pie(x, wedge_labels=(['a', 'b', 'c'], ['A', 'B', 'C']), wedge_label_distance=(0.5, 1.2))
plt.pie(x, wedge_labels="{frac:.1%}")
plt.pie(x, wedge_labels=("{frac:.1%}", "{abs:.2f}"), wedge_label_distance=(0.5, 1.2))

instead of

plt.pie(x, inner_labels=['a', 'b', 'c'], inner_label_distance=0.5)
plt.pie(x, inner_labels=['a', 'b', 'c'], inner_label_distance=0.5, outer_labels=['A', 'B', 'C'], outer_label_distance=1.2)
plt.pie(x, inner_labels="{frac:.1%}")
plt.pie(x, inner_labels="{frac:.1%}", inner_label_distance=0.5, outer_labels="{abs:.2f}", outer_label_distance=1.2)

The only other alternative that may be worth considering is to make a single wedge_labels, wedge_label_distance that accepts a single list or a tuple of lists

I really like this proposal b/c it removes the semantic issue of being able to position inner/outer label anywhere, and it gives people the flexibility to have as many sets of labels as they want. Though could this also be the external function pie_label? that could then take a third parameter "fmt" that accepts a list of formatting strings/functions/Formatter Objects

Though could this also be the external function pie_label?

Not easily. See #29152 (comment) for the issues I see with pie_label function.

What would be the default for wedge_label_distance?

Is there contributor guidance somewhere (or an example) for documenting a pending deprecation?

Belatedly I realised there is some difference in handling between the current labels and autolabels. So it is not as generalisable as I had assumed. The labels have horizontal alignment set to the side closest to the centre. This makes sense when placing the labels outside the pie so that they do not overlap the wedges. They also have an option to automatically rotate so they are orientated relative to the circle.

OTOH the automatic labels are just aligned to the centre.

Do we want to make horizontalalignment change based on whether wedge_label_distance is greater or less than 1? Or is that too much magic?

Do we want to support the rotatelabels option for all labels? If so does it become a list of bools, similar to now having a list of distances?

Apologies, I should have spotted these things much earlier.

Is there contributor guidance somewhere (or an example) for documenting a pending deprecation?

https://matplotlib.org/devdocs/devel/api_changes.html

Please let me know what's missing from there and how we can make it clearer that that's where those docs are

Apologies, I should have spotted these things much earlier.

Thanks for digging this up, and no apology needed. I also haven't thought about it. These are the things that pop up when going from theory to code.

To the question: The current alignment behavior is largely reasonable. Take this example:

• The inner labels have to horizontally center. Otherwise, they'd only render into one half-side of the wedge.
• For outer labels have to "attach" to the border of the pie. Centering doesn't work because long labels would spill into the pie. The simple solution is to adjust the horizontal alignment based on the position. This gives reasonable results because text is typically wider than high. If you want to be more to-the-point, the alignment would change depending on the position like this (with t.b.d. angles of transition):
  
  You can also see from this picture that keeping the vertical alignment always centered does not make much of a difference: The labels only move a bit closer to the wedge by half the font height.

To answer your questions:

Do we want to make horizontalalignment change based on whether wedge_label_distance is greater or less than 1? Or is that too much magic?

Yes. This is necessary to get the expected / reasonably looking behavior.

Do we want to support the rotatelabels option for all labels? If so does it become a list of bools, similar to now having a list of distances?

Probably yes. It's unlikely that one wants to rotate the inner labels, but having the parameter and only apply it if the labels are outside feels a bit weird. (Note: The difference to the alignment is that the distance-dependent alignment is an automatic choice behind the scenes, but rotatelabels would be explicitly given by the user).

Overall remark: These topics make inner and outer labels less equal, which is an argument in favor of dedicated inner_labels/outer_labels. I'd be open to revisit that discussion in the light of the new insights. But I believe it's not strong enough to exclude the generic labels version.

Is there contributor guidance somewhere (or an example) for documenting a pending deprecation?

https://matplotlib.org/devdocs/devel/api_changes.html

Please let me know what's missing from there and how we can make it clearer that that's where those docs are

Thanks - I am aware of that page and it's great for how to deprecate something in the next meso release. However, I think we recently agreed that something should not be deprecated unless the alternative has been available for at least one meso release. So if we introduce wedge_labels in v3.11 we do not deprecate labeldistance not None until v3.12. I assume for the warning I do it as normal but set pending=True, but am unclear if I need to document as normal or do something different.

Edit: never mind I found an example.
https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.set_constrained_layout.html#matplotlib.figure.Figure.set_constrained_layout
https://matplotlib.org/stable/api/prev_api_changes/api_changes_3.6.0.html#pending-deprecation-of-layout-methods

If you want to be more to-the-point, the alignment would change depending on the position like this (with t.b.d. angles of transition)

I like this - it would be good to revisit once I have something working with the simpler current logic.

These topics make inner and outer labels less equal, which is an argument in favor of dedicated inner_labels/outer_labels. I'd be open to revisit that discussion in the light of the new insights. But I believe it's not strong enough to exclude the generic labels version.

I think either way internally I build a list of lists, so it should be pretty easy to switch later if we decide to go that way. For now I will proceed with wedge_labels.

Currently the fontsize used for labels is rcParams['xtick.labelsize'] whereas for the auto labels no choice is made so I assume it is rcParams['font.size']. rcParams['xtick.labelsize'] defaults to 'medium' so if the user didn't touch rcParams then I think these will be the same. These choices predate Matplotlib being in git. Does anyone have an opinion what these should be for wedge_labels? I note that

• The user can already override the fontsize for all labels using the textprops parameter, though that will make them all the same size.
• The Text objects are all returned from the function so the user can update properties on individual labels there, though that will of course be more fiddly.

Obvious options

1. Make them rcParams['xtick.labelsize'] if distance > 1, otherwise rcParams['font.size']. Advantage: more flexibility for the user to choose different sizes. Probably consistent with thinking of the pie as a polar axes with the outer labels as tick labels and the inner labels as annotations.
2. Just make them all rcParams['font.size']. Advantage: perhaps the least surprising for the user.
3. Just make them all rcParams['xtick.labelsize']. I'm not seeing an obvious advantage of this.

We could also make textprops more flexible to take a dictionary for each set of labels, either now or as a future enhancement.

Still very WIP. I only pushed so that the branch is backed up!

So if we introduce wedge_labels in v3.11 we do not deprecate labeldistance not None until v3.12. I assume for the warning I do it as normal but set pending=True, but am unclear if I need to document as normal or do something different.\n\nEdit: never mind I found an example.\n

Thanks! That means this information is missing from that guide and it should be updated to include it there.

We could also make textprops more flexible to take a dictionary for each set of labels, either now or as a future enhancement.

Definitely a fan of broadcast all the things, but depending on your bandwidth I agree w/ you on 1. That'll probably produce the cleanest labels by default.

I’d intuitively go with that

2. Just make them all rcParams['font.size']. Advantage: perhaps the least surprising for the user.

If you want to look for more analogies, check annotate(), bar_label(), clabel(), …

Thinking again about the labeldistance parameter, instead of

1. Now: pending deprecation for setting it to anything other than None
2. Later: full deprecation for above
3. Even later: deprecate parameter completely as it can now only be None

we could do

1. Now: behaviour change - in 2 releases time None becomes the default.
2. Later: deprecate parameter; direct to use wedge_lables instead

This gets us there in one less step and one less release. Downstream can silence the immediate deprecation warning by just passing labeldistance=1.1. That will work fine with previous versions and also gives two versions of overlap where wedge_labels will also work before the parameter is deprecated.

There is a test case that passes labels="l" where "l" is a key for the data dictionary. It also passes autopct. I have not tried, but I think wedge_labels=['l', format_string] would not work without making changes in the _preprocess_data decorator.

Do we still need to support cases that this test represents? If so, should we go back to inner_labels/outer_labels? Or modify _preprocess_data? Or is there another way?

For now I have modified _preprocess_data to work on a sequence, though I am unclear whether we really want to do that for such a widely used decorator.

I'm also generally a bit concerned about how much new code there is here for a relatively small feature.