For now, only categorical labels are supported as x. Should we also support numbers as with bar?

Am thinking of a bunch of situations (date times, coded data, machine learning labels) where the numbers are really categoricals but the dtype isn't string and I think folks will expect it to just work. Also the categorical remapping mechanism isn't terribly robust 😓 so I could see folks wanting to just use numbers + formatter if they're trying to do something like animated/interactive sorting of bars (something like bar chart race) where the position of the bar is actually independent of its label as categorical will maintain the same cat->int mapping as stuff is added to the chart. Which tldr, yes numbers b/c that allows for a lot of fine tuning of bar position.

Added numeric values support for x. I've required that x ist equidistant, becuause otherwise positioning will be quite messy.

if they're trying to do something like animated/interactive sorting of bars (something like bar chart race) where the position of the bar is actually independent of its label as categorical will maintain the same cat->int mapping as stuff is added to the chart.

I've not thought this case though, but remember that grouped_bar() is just a convenience interface for positioning multiple sets of data. One boundary condition is that each group (=bars at one category/tick position) has the same datasets in the same order. If you need something exotic, you'll have to go back to drawing individual bars.

If you need something exotic, you'll have to go back to drawing individual bars

I don't think this is technically feasible, but this has me thinking it'd be nice if the return object was a 2D bar container that supported slicing out all the segments at a given X or all the segments of a group for easier consistent updates.

The API proposal is complete. Please check whether it is reasonable. You can get an overview the preliminary overview example
and in the API docs for grouped_bar. Design decisions and background are listed in the first comment of this PR. Feedback is welcome!

A couple of quick comments:

• thoughts on how this could be extended if (when) we implement hierarchical tick labels?
• for the return did you consider a dict? It might be worth considering a minimal custom class (__getitem__ by the labels and obj.remove()) as well? The two things I think are important are the by-label access (particularly when user passed us a dict to begin with) and the ability to remove the whole lot in one shot. Do we want to return a new compound artist (that legit lives in the tree)?
• is there a way to control styling by label (e.g. put a different hatch on each group)? I'm not sure this is useful, but also not sure it is not useful. "grab the returned object and do it your self" is also a good answer for now.
• the first example in the docs should be turned into an figure comparison test to get at least some coverage?

thoughts on how this could be extended if (when) we implement hierarchical tick labels?

Not thought about it. But the fundamental API grouped_bar(x, heights) should be able to bear this. Likely with a hierarchial x and with or without substructuring in heights.

Side note: There is one aspect, I've been pondering: We could revese the positional argument order to groupde_bar(heights, x). We have kinda precendence for that in stairs. This would allow to (i) leave out x entirely for a quick look (use range() as default) and (ii) more importantly make it possible to pass a complex object grouped_bar(dataframe), which contains all the labelling information; this could then also be hierarchial. I've refrained from it to keep more analogy to bar. After all, our API is mostly low-level component-based. I believe to change that, it would be better to add a data preprocessing decorator that takes complex objects and decomposes them into the data components.

for the return did you consider a dict? It might be worth considering a minimal custom class (__getitem__ by the labels and obj.remove()) as well? The two things I think are important are the by-label access (particularly when user passed us a dict to begin with) and the ability to remove the whole lot in one shot. Do we want to return a new compound artist (that legit lives in the tree)?

We have no precedence that plotting functions return dicts. Additionally, one can plot without passing labels, which would us require to invent keys. So dict is not an option to me. Mid-term, I'd like to have better return objects, but his is a larger topic, which I don't want to figure out in this PR. I see the list of Container as a temporary approach - one of the main reasons to make this provisonal. It is certainly not the most elegant approach, but it's consistent (c.f. stackplot()), simple and gives users a grip on the underlying artists. Given that re-using the Artists is quite rare, that's good enough for now. Mid-term, I'd like to have better return objects. I will add an explicit note that this is likely to change.

is there a way to control styling by label (e.g. put a different hatch on each group)? I'm not sure this is useful, but also not sure it is not useful. "grab the returned object and do it your self" is also a good answer for now.

No. I've never seen this. Generally, groups are distinguished by location (and identified by x tick labels), and there's a point in that the bars of one dataset look the same over all groups to help make the connection. Per-group settings is not something I would want to encourage through API (though we could later introduce a parameter dict group_props if you convince me that's really a valid use case 😃). For now: Do it yourself.

the first example in the docs should be turned into an figure comparison test to get at least some coverage?

Yes, as the todo in the intial PR shows, tests are still open. I'm collecting feedback before so that I don't have to rewrite all tests in case I would have to overhaul the design.

We could revese the positional argument order to groupde_bar(heights, x). We have kinda precendence for that in stairs.

I agree that is interesting, but as you point out could be solved by layers on top of this.

Additionally, one can plot without passing labels, which would us require to invent keys.

We could fallback to range() or [f"dataset_{i}" for in range()] but I agree that is less than great. That would probably mean we would also force those invented labels into the legend which is not great. I'm convinced we should not return a dict (but a bit sad about it).

Rather than a list could we do a custom object like:

class GroupedBarReturn:
    def __init__(self, bars):
        self.bars = bars
    def remove(self):
        [b.remove() for b in self.bars]

? This would also give us a reasonable expansion path if this API grew to add errorbars or annotations to the bars. Also a path to obj.by_labels[key]

Even though it is provisional, I'm a bit worried about returning an object with an API that would be annoying to replicate (e.g. not fall into the trap of ax.errorbar).

This may be a bigger discussion, but I think we should try to make everything we return from plotting methods to have a .remove method so "make it go away" is always the same.

That said, I'm not going to push this further and returning a list is acceptable to merge.

No. I've never seen this....For now: Do it yourself.

sounds reasonable.

Edit: I think I've reasonbly addressed the doc build failure.

Technical topic: I don't understand the doc failure:

/home/circleci/project/doc/api/axes_api.rst:294:<autosummary>:1: WARNING: py:obj reference target not found: Axes.dataLim [ref.obj]
/home/circleci/project/doc/api/axes_api.rst:449:<autosummary>:1: WARNING: py:obj reference target not found: AxesBase [ref.obj]

The call stacks goes through the .. autosummary:: sections axes_api.rst ending with the stated line numbers. They try to autogenerate the doc pages for update_datalim and add_child_axes but fail to resolve the following object references:

What's funny is that this PR does not touch the respective docstrings or targeted objects. Also, the only modification of axes_api.rst itself is the addition of grouped_bar (in another autosummary).

It seems that the failure is not related to the PR but some external influence (change of sphinx?). The failure may even be expected, because both references use AxesBase, which is not in our documentation, and the stable/devedocs render them as unresolved references. But why does it happen here and now? Other PRs do not see the problem. Do we have caching of the doc builds, and I'm the first to touch axes_api.rst to trigger regeneration?

more importantly make it possible to pass a complex object grouped_bar(dataframe), which contains all the labelling information

Also would make it trivial to transpose, which honestly is one of the best parts of the pandas API.

Which also, I think my request for an BarContainerArray and Tom's for a dict based return are both pointing towards a data frame type artist container - which yes I can see being out of scope here and also I think you proposed something like this once for Axes so you could do both mosaic label based and index based

Changed to a provisional custom return object as proposed in #28560 (comment) to ease possible future migration.

@story645 A big thank you for a though round of review 🎉.

I've either changed the commented positions or replied why I think they should be kept as is. Please mark the comments as resolved on which you are ok with my reply so that only the open topics remain visible.