Add functionality to label individual bars with Axes.bar() #23525

stefmolin · 2022-07-30T22:15:32Z

PR Summary

Currently, if you need to label each bar in a plot say for an animation, you have to loop over the bars in the bar container that Axes.bar() returns and call set_label() on each bar. I have an example here in a workshop I deliver. When compared with stackplot() (which has a labels argument for this) this can be a gotcha for newcomers. There is a label key shown in the docs as available on the Rectangle, but it doesn't have the expected effect of labeling the bars, rather it labels the BarContainer:

>>> import matplotlib.pyplot as plt
>>> x = ["a", "b", "c"]
>>> y = [10, 20, 15]
>>> fig, ax = plt.subplots()
>>> bar_container = ax.barh(x, y, label=x)
>>> print([bar.get_label() for bar in bar_container])
['_nolegend_', '_nolegend_', '_nolegend_']
>>> bar_container.get_label()
"['a', 'b', 'c']

This PR adds a labels argument to Axes.bar(), which makes it possible to easily label each bar and color them differently, making it possible to create a legend immediately after calling the bar()/barh() method.

x = ["a", "b", "c"]
y = [10, 20, 15]

fig, ax = plt.subplots()
_ = ax.barh(x, y, labels=x)
ax.legend()

Default color behavior is preserved when labels isn't passed in:

x = ["a", "b", "c"]
y = [10, 20, 15]

fig, ax = plt.subplots()
_ = ax.barh(x, y)

PR Checklist

Tests and Styling

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

New features are documented, with examples if plot related.
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
Documentation is sphinx and numpydoc compliant (the docs should build without error).

jklymak · 2022-07-30T22:39:38Z

Thanks for the PR. First there is already a colors kwarg for bars, so how does this interact with that? Secondly there is tick_label kwarg that seems to be what this pr is suggesting? Can you clarify how this is different?

https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.barh.html

stefmolin · 2022-07-30T22:51:03Z

This PR populates the label attribute on each of the bars in the bar container (i.e., to be able to call get_label() on the bar). The current behavior gives them all a label of _nolegend_:

>>> bar_container = ax.barh(x, y, label=x)
>>> print([bar.get_label() for bar in bar_container])
['_nolegend_', '_nolegend_', '_nolegend_']

When color isn't provided, passing in labels will now cycle through the colors:

x = ["a", "b", "c"]
y = [10, 20, 15]

fig, ax = plt.subplots()
_ = ax.barh(x, y, labels=["Apple", "Banana", "Cherry"])
ax.legend()

When labels isn't provided, the colors behave exactly as they did before:

x = ["a", "b", "c"]
y = [10, 20, 15]

fig, ax = plt.subplots()
_ = ax.barh(x, y)

If you pass in both:

fig, ax = plt.subplots()
bar_container = ax.barh(x, y, labels=["Apple", "Banana", "Cherry"], color=['blue', 'red', 'orange'])
ax.legend()

jklymak · 2022-07-30T22:55:45Z

Thanks I see. Do people want a legend if the bars are already labeled via the ticks?

stefmolin · 2022-07-30T22:57:40Z

My main use case was actually building animations. I use the get_label() to make sure I have the correct bar (e.g., this animation). The legend makes it easier to explain what is going on for the proposed changes.

tacaswell · 2022-07-30T23:12:26Z

I'm of two minds on this.

On one hand I see how much nicer this is that having to do the loop outside and I can totally see a use case for setting the legend and dropping the ticks / axis all together. I also see the analogy to stack plot (even if it is a bit rough because stackplots takes a sequence of sequences of scalars and bar only takes a sequence of scalars and a better analogy to stack plot would be extending bar to make stacked bar charts).

On the other hand I am worried about stacking yet more complexity into the public APIs!

I think in addition colors, labels will need to deconfilct with tick_labels (can you pass both? if you pass one is the other implied? do they have to match? do we need a way to ask for them to match?), the plain label (can you pass both labels and label? I can see arguments for both yes and no!), and the ax.bar_label method (which might need a way to ask the bars what their labels are now?).

Even if we do not take this, this is nice work. Thank you for a fully documented and tested PR out of the gate @stefmolin !

ignore the linting error #23527 will fix it.

stefmolin · 2022-07-30T23:38:12Z

I think in addition colors, labels will need to deconfilct with tick_labels (can you pass both? if you pass one is the other implied? do they have to match? do we need a way to ask for them to match?), the plain label (can you pass both labels and label? I can see arguments for both yes and no!) and the ax.bar_label method (which might need a way to ask the bars what their labels are now?).

Initially, I was trying to match the API of stackplot, but I definitely understand the concerns of making the API more complicated. For my use case, it would be perfectly acceptable for tick_labels to be used to label the bars.

My change to the bar colors was to make the legend in my examples make sense. So if we are more comfortable with just using the tick_labels already going on the axis to label the bars and not touching anything else, I'm happy to simplify the logic here 😄

tacaswell · 2022-07-30T23:57:51Z

If we promote tick_label to also label the bars I think that would break cases like:

import matplotlib.pyplot as plt

x = [1, 2, 3]
y1 = [1, 5, 7]
y2 = [3, 1, 6]

fig, ax = plt.subplots()
ax.bar(x, y1, label='G1', tick_label=['a', 'b', 'c'])
ax.bar(x, y2, bottom=y1, label='G2', tick_label=['a', 'b', 'c'])
ax.legend()

Maybe only do it if the overall bar does not have a label? Maybe make it opt-in like ax.bar(..., use_tick_label_as_bar_label=True) (but with a better name)?

stefmolin · 2022-07-31T00:48:11Z

Good point. Another option would be to prefix the individual bar labels with _nolegend_ and use namespacing like these for the blue ones in your example:

['_nolegend_:G1:a', '_nolegend_:G1:b', _nolegend_:G1:c']

so essentially naming everything in the case of stacked bars as _nolegend_:{label}:{tick_label}.

That way they don't show up in the legend, and at the same time, they have unique labels.

timhoffm · 2022-07-31T01:02:28Z

I feel that making bars indiviudally configurable was an overreach of the API of bar(), which we should not have done in the first place. That'd better been a seperate function.
But now that we are down the road, we can carefully expand - though I will not give a free-for-all ticket on individual customization.

The minimal (and possibly reasonable) extension is label supporting a list of labels (of matching length) that are assigned to the individual bars. Period.
I oppose auto-switching to color-cycling. bar() is primarily intended for same-style bars. Any bar-individual customiztation should be explicit.

I'm very sceptical on mixing with tick_labels. These are conecptually different things. Mixing them complicates things and I don't see a benefit. IMHO users rarely need tick_labels and a legend. And if they do, they can pass the list to both parameters.

timhoffm · 2022-07-31T07:23:37Z

Another option would be to prefix the individual bar labels with _nolegend_ and use namespacing

We guarantee that labels starting with an underscore are not drawn in the legend:

Specific lines can be excluded from the automatic legend element selection by defining a label starting with an underscore.

@stefmolin If your only conern is giving unique IDs to bars, you can define any label you want starting with an underscore for this. With the list-of-labels API suggested above, you can easily do that - and decide yourself how your IDs look like.
I'm not clear if you propose the namespacing as a concept or automatism in matplotlib, but just to clarify, I don't think we want or need that complexity.

stefmolin · 2022-07-31T13:35:06Z

@timhoffm - That logic was if we were going to use the tick_labels to automatically label the bars. I agree that there is no need to impose any such logic on Matplotlib if we pass a list to label. I'll update my implementation to do just do that.

stefmolin · 2022-07-31T16:36:16Z

Here are some examples of the new implementation. Note that colors are no longer altered.

Passing a list of labels:

>>> import matplotlib.pyplot as plt
>>>
>>> fig, ax = plt.subplots()
>>> bar_container = ax.barh(
...     ["a", "b", "c"],
...     [10, 20, 15],
...     label=["Apple", "Banana", "Cherry"]
... )
>>> [bar.get_label() for bar in bar_container]
['Apple', 'Banana', 'Cherry']

Plotting a single bar

>>> import matplotlib.pyplot as plt
>>>
>>> fig, ax = plt.subplots()
>>> bar_container = ax.barh(
...     "a",
...     10,
...     label="Apple"
... )
>>> [bar.get_label() for bar in bar_container]
['Apple']

Not passing in labels:

>>> import matplotlib.pyplot as plt
>>>
>>> fig, ax = plt.subplots()
>>> bar_container = ax.barh(
...     ["a", "b", "c"],
...     [10, 20, 15]
... )
>>> [bar.get_label() for bar in bar_container]
['_nolegend_', '_nolegend_', '_nolegend_']

Plotting a stacked bar plot

>>> import matplotlib.pyplot as plt
>>> import itertools
>>>
>>> x = [1, 2, 3]
>>> y1 = [1, 5, 7]
>>> y2 = [3, 1, 6]
>>> 
>>> fig, ax = plt.subplots()
>>> bar_container1 = ax.bar(
...     x, y1, label='G1', tick_label=['a', 'b', 'c']
... )
>>> bar_container2 = ax.bar(
...     x, y2, bottom=y1, label='G2', tick_label=['a', 'b', 'c']
... )
>>> [
...     bar.get_label()
...     for bar in itertools.chain(bar_container1, bar_container2)
... ]
['_nolegend_',
 '_nolegend_',
 '_nolegend_',
 '_nolegend_',
 '_nolegend_',
 '_nolegend_']

timhoffm

Since the label behavior grew more complex now, it deseves explicit mention
in the Other Parameters section of the docstring (preferably right below tick_label.

I suggest something like:

label : str or list of str, optional
    A single label is attached to the resulting BarContainer as a
    label for the whole dataset.
    If a list is given, it must be the same length as *x* and
    labels the individual bars. For example this may used with
    lists of *color*.

lib/matplotlib/axes/_axes.py

doc/api/next_api_changes/behavior/23525-SM.rst

story645 · 2022-08-18T01:16:15Z

Definitely support this feature, but curious about the behavior where multiple bars that are styled the same way share a label? My bias is that a feature like this could/would be used in conjunction w/ tick labels to do some sort of grouping

fig, ax = plt.subplots()

x = ['a', 'b', 'c']
y = [2, 1, 3]
l = ['A', 'B', 'A']
c = ['tab:orange', 'tab:blue', 'tab:orange']

ax.bar(x, y, label=l, color=c)

ax.legend()

I tried to pull this branch and test against it, but I could be wrong, and this is what I got:

and I think the optimal behavior would be something like:

but I wonder about implementation complexity - I think it's something like check which bars have the same label and the same vectorized properties (color, edgecolor, linewidth) and then only label the first bar? Would there be a problem w/ making the duplicates no-legend?

timhoffm · 2022-08-18T02:06:09Z

The fourth element (['A', 'B', 'A']) in @story645's first plot is indeed a bug. label should be mapped either to the individual patches or to the BarContainer itself, but not both.

I advise against trying to automatically filter duplicates. That's tedious due to normalization. It's also a bit magical, as the entries legend entries are associated with the bars, if you filter duplicates out, technically some bars don't have a label, e.g. 'a' would be associtated with 'A' but 'c' wouldn't - it just looks the same. You could even break that by re-styling 'a' now. Then the legend would follow, but 'c' would not.
Instead, you could explicitly use ['A', 'B', '_nolegend_'], and then you know what is happening.

story645 · 2022-08-18T02:14:08Z

I advise against trying to automatically filter duplicates.

I won't block if labels are repeated in the legend, but I think then this choice has to be clearly documented as I expect it to be a follow up feature request.

Instead, you could explicitly use ['A', 'B', '_nolegend_'], and then you know what is happening.

I'd be ok w/ this being the example of how to use this keyword to do grouping, but I think it'd be worth either expanding one of the gallery examples or adding a new one discussing this.

Also, it seems like at least one image test wouldn't hurt.

timhoffm · 2022-08-18T07:22:01Z

think then this choice has to be clearly documented as I expect it to be a follow up feature request.

I'm fine with documenting that the behavior for repeated labels is not defined and may change in the future.

Also, it seems like at least one image test wouldn't hurt.

For now, the expected behavior is exactly defined by testing the labels of the individual bars and the label of the BarContainer: "Where does the information go?". Every Artistvwith a label shows up in the legend. There's no additional magic here that needs testing as an image.

stefmolin · 2022-08-18T13:20:05Z

I addressed the comments and fixed that bug:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()

x = ['a', 'b', 'c']
y = [2, 1, 3]
l = ['A', 'B', 'A']
c = ['tab:orange', 'tab:blue', 'tab:orange']

ax.bar(x, y, label=l, color=c)

ax.legend()

Instead, you could explicitly use ['A', 'B', '_nolegend_'], and then you know what is happening.

I'd be ok w/ this being the example of how to use this keyword to do grouping, but I think it'd be worth either expanding one of the gallery examples or adding a new one discussing this.

Can you provide some additional information on this?

story645 · 2022-08-18T13:48:19Z

There's no additional magic here that needs testing as an image.

Yeah I didn't quite grok how to test the double labeling issue, but I like @stefmolin adding it to the code tests better than an image test.

Can you provide some additional information on this?

I think this new keyword argument could be more discoverable with an addition to the gallery in the lines-bars-and-markers section showing 1) the use of this keyword 2) the use of this keyword with a mix of labels and no legend. The latter could also show off the list of colors, which is another keyword we don't have an explicit example for. Granted I can also spin thus request off into a follow up issue so this is another non-blocking request.

lib/matplotlib/axes/_axes.py

tacaswell · 2022-08-18T18:36:35Z

@stefmolin could you rebase this to squash out the adding / removed API change note?

QuLogic

Minus the remaining comments.

lib/matplotlib/axes/_axes.py

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

stefmolin · 2022-08-18T22:01:13Z

@tacaswell - I rebased to remove those changes.

I also incorporated the change to the docstring as suggested. Linting is failing from the latest changes on master after the rebase.

I think this new keyword argument could be more discoverable with an addition to the gallery in the lines-bars-and-markers section showing 1) the use of this keyword 2) the use of this keyword with a mix of labels and no legend. The latter could also show off the list of colors, which is another keyword we don't have an explicit example for. Granted I can also spin thus request off into a follow up issue so this is another non-blocking request.

@story645 - Should I move forward with this in a separate PR?

story645 · 2022-08-18T22:02:38Z

@story645 - Should I move forward with this in a separate PR?

Yes, that would be awesome!

QuLogic · 2022-08-18T23:04:46Z

I squash-merged, as I don't think we need the history of no-longer-implemented functionality.

jklymak added the status: needs clarification Issues that need more information to resolve. label Jul 30, 2022

QuLogic added the New feature label Aug 3, 2022

timhoffm removed the status: needs clarification Issues that need more information to resolve. label Aug 17, 2022

timhoffm reviewed Aug 18, 2022

View reviewed changes

lib/matplotlib/axes/_axes.py Outdated Show resolved Hide resolved

doc/api/next_api_changes/behavior/23525-SM.rst Outdated Show resolved Hide resolved

story645 approved these changes Aug 18, 2022

View reviewed changes

lib/matplotlib/axes/_axes.py Outdated Show resolved Hide resolved

story645 mentioned this pull request Aug 18, 2022

[ENH]: Suppress duplicate labels in legend #23664

Closed

tacaswell added this to the v3.6.0 milestone Aug 18, 2022

QuLogic approved these changes Aug 18, 2022

View reviewed changes

timhoffm approved these changes Aug 18, 2022

View reviewed changes

QuLogic reviewed Aug 18, 2022

View reviewed changes

lib/matplotlib/axes/_axes.py Outdated Show resolved Hide resolved

Add labels argument to bar().

716f0a7

stefmolin added 9 commits August 18, 2022 17:30

Add what's new users entry.

03b6524

Fix doc entry.

3dbe540

Add test for mismatch in label length and data length.

b975db2

Switch to 'label' argument.

a0ed196

Handle duplicate bar labels in legend; address PR comments.

bc5b1a1

Add tests.

72fd2b4

Update label description in docstring.

8a5ab0e

Remove duplicate label filtering.

f71dc0c

Add note on repeated labels.

6ad5dcf

stefmolin force-pushed the bar-labels branch from 3abf906 to 6ad5dcf Compare August 18, 2022 21:38

Update docstring per PR.

9f55a01

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

QuLogic merged commit e68c1e8 into matplotlib:main Aug 18, 2022

stefmolin deleted the bar-labels branch August 18, 2022 23:08

stefmolin mentioned this pull request Aug 19, 2022

Add bar color demo. #23670

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add functionality to label individual bars with Axes.bar() #23525

Add functionality to label individual bars with Axes.bar() #23525

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add functionality to label individual bars with Axes.bar() #23525

Add functionality to label individual bars with Axes.bar() #23525

Uh oh!

Conversation

Uh oh!

PR Summary

PR Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!