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 locationinner_label andouter_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

• keeplabels,label_distance as is
• introduceinner_labels andinner_label_distance.inner_labels should take (i) a list (ii) a function (iii) a{} format string
• autopct translates toinner_labels and giving both is an error. Discourageautopct in favor ofinner_labels and describe the transition (note that autopct's %-format and callable take values that are scaled by 100).
• pctdistance translates toinner_label_distance and giving both is an error. Discouragepctdistance in favor ofinner_labels_distance and state that you should use the variable that is matching to the one used to define the labelsinner_labels=..., inner_label_distance=... andautopct=..., pctdistance=....
• optionally, expandlabels to also take (ii) a function (iii) a{} format string

Does that sound reasonable?

I am not sure aboutinner_labels because there is nothing to stop you swapping the positions of these withlabels (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 thatlabels is special because it will be automatically used bylegend (and if you want them in the legend and not on the pie you setlabeldistance=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 forwedgelabels, 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 beinner_labels andouter_labels (orlabels when considering compatibility) as lists of fixed texts. Everything else is convenience. Possibly, we don't even need absolute value support then. It is justpie(x, inner_labels=[f'{xi:.1f}' for xi in x]) IMHO this is even better - because more explicit - thanpie(x, absolutefmt="%.1f"). Percent formatting is only marginally more complexpie(x, inner_labels=[[f'{xi:.1%}' for xi in x/x.sum()]).

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

• keeplabels,label_distance as is
• introduceinner_labels andinner_label_distance.inner_labels should take a list only
• autopct translates toinner_labels and giving both is an error. Describeautopct as a higher-level convenience function to get percent values into inner_labels.
• Documentpctdistance as equivalent toinner_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 labelsinner_labels=..., inner_label_distance=... andautopct=..., 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 labelsand the legend, which is most likely not what one wants. One has to additionally passlabeldistance=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 tolegend().

A green-field solution would be to havelabels only for the legend and explicitouter_labels andinner_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 separatinglabels intolabels (legend only) +outer_labels:

• If as user useslabels with a not-Nonelabeldistance, they want an outer-wedge label. Add a deprecation here and state that they should useouter_labels (andouter_label_distance if needed). Add an additional note that they need to pass the same list tolabels as well if they want to keep legend entries.
• If a user has usedlabels=..., labeldistance=None they only want and get a legend. Nothing to do for a start. One can deprecate and remove thelabeldistance parameter, when the above deprecation on forlabels generating outer texts has run out. Thenlabels will always only create legend entries and thelabeldistance 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 introducinginner_labels there.

I am not sure aboutinner_labels because there is nothing to stop you swapping the positions of these withlabels (using the distance parameters)

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

namingextra_labels,secondary_labels,wedge_labels

• wedge_labels is a bit ambiguous. While the inner labels areon 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. Havingextra_labels/secondary_labels withoutlabels 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 publicpie_label method, to rhyme withbar_label. The existinglabels andautopct 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 inpie, that might be the way to go. But as is, there's not much new functionality to be introduced via apie_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:

• Introduceinner_labels andouter_labels which take a list of strings or a format string to be formatted with.format(abs=abs, frac=frac).
• Introduceinner_label_distance (default 0.6) andouter_label_distance (default 1.1) to specify how far the above are from the pie centre.
• Deprecate usinglabels with not-Nonelabeldistance - direct to use outer labels instead.¹
• Discourage² usingautopct in favour ofinner_labels. Passing both is an error.
• Passingpctdistance andinner_labels is an error.
• Passinginner_label_distance andautopct is an error.

Good summary! This isone 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 unintuitivepie(x, inner_labels="%.1f").

The function approach is a bit better, because you could support two signaturesdef fmt(abs_value: float) -> str anddef fmt(abs_value: float, total: float) -> str. The first one is a simpler version for convenince, the second one would support percents aspie(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 - currentlytextprops are shared androtatelabels 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 ofpie(). We'd likely need to create a semantic artistPieWedge or a kind ofPie container class to handle this.
Problem 2: Removing all labelling capability frompie 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) Keepinglabels 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 aboutpie - 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 ofpie I don’t think it’s too unintuitive that those would have the convenience in terms of labelling. The canonical example would bepie(x, inner_labels="{:.1%}"). Also sincepie 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 theText constructor will take care of converting them to strings.

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

Edit: I guess youcould 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 forinner_labels andouter_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 repurposinglabels to only apply to legend. If yes, this is the reasonable way forward. If no, only doinner_labels as a replacement ofautopct. I'm 0.5 on going all the way (but slowly, i.e. start with a pending deprecation).

I am in favour of makinglabels only for legend.

• API consistency: almost everywhere that you passlabel(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, usinglabels=list_of_strings, outer_labels=... is more intuitive to me (and simpler) thanlabels=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 bikeshedouter_labels,inner_labels to replace the "label" part; motivation: set it more clearly apart fromlabels; e.g. go forwedge_text or similar. However, we have ample precedence for*_label usages independent oflabels mapping to legend:bar_label,clabel (contour label),tick_labels,xlabel,ylabel. Thereforeouter_labels andinner_labels seem perfectly fine.

Edit: The only other alternative that may be worth considering is to make a singlewedge_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 functionpie_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 functionpie_label?

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

What would be the default forwedge_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 currentlabels and autolabels. So it is not as generalisable as I had assumed. Thelabels 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 whetherwedge_label_distance is greater or less than 1? Or is that too much magic?

Do we want to support therotatelabels 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 whetherwedge_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 therotatelabels 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, butrotatelabels 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 dedicatedinner_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 introducewedge_labels in v3.11 we do not deprecatelabeldistance not None until v3.12. I assume for the warning I do it as normal but setpending=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 withwedge_labels.

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

• The user can already override the fontsize for all labels using thetextprops parameter, though that will make them all the same size.
• TheText 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 themrcParams['xtick.labelsize'] if distance > 1, otherwisercParams['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 allrcParams['font.size']. Advantage: perhaps the least surprising for the user.
3. Just make them allrcParams['xtick.labelsize']. I'm not seeing an obvious advantage of this.

We could also maketextprops 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 allrcParams['font.size']. Advantage: perhaps the least surprising for the user.

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

Thinking again about thelabeldistance parameter, instead of

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

we could do

1. Now: behaviour change - in 2 releases timeNone becomes the default.
2. Later: deprecate parameter; direct to usewedge_lables instead

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

There is atest case that passeslabels="l" where "l" is a key for thedata dictionary. It also passesautopct. I have not tried, but I thinkwedge_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 toinner_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.