Consolidate style parameter handling for plotting methods that call other plotting methods #30808

rcomer · 2025-12-04T11:42:47Z

PR summary

hist, stackplot and grouped_bar all loop through datasets and call another plotting method repeatedly. This means they have a common requirement to support sequences for parameters such as facecolor and hatch.

hist already has handling for this, which I have factored out into a new helper function. I wasn't sure where to put the helper, so for now it is in its own new private module. I tried putting it in _axes, _api and cbook but all those options gave me circular import problems. The tests from #29719 are now reimagined as cheaper tests on the helper.

Using the helper in stackplot closes #30804.

Using the helper in grouped_bar closes #30673, so this would supersede #30726. I copied the grouped_bar test from there so added @ilakkmanoharan as a co-author. Note that, contrary to agreement in #30726, this does support a single hatch string for grouped_bar. I still don't think a single hatch makes sense for any of these methods, but it is already supported for both hist and stackplot and I do not feel strongly enough to deprecate the existing support or to throw a special case exception in grouped_bar.

grouped_bar example usage:

import matplotlib.pyplot as plt

categories = ['A', 'B']
datasets = {
    'dataset 0': [1, 11],
    'dataset 1': [3, 13],
    'dataset 2': [5, 15],
}

fig, ax = plt.subplots()
ax.grouped_bar(datasets, tick_labels=categories, hatch=['/','+', '.'], facecolor='gray', edgecolor=['r', 'b', 'g'])
ax.legend()
plt.show()

Note the helper does not handle color because the methods already have bespoke handling for colors. E.g. stackplot maps colors to facecolor, hist with "step" type maps colors to edgecolor. What should happen if color is in **kwargs probably needs individual consideration for each method.

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

rcomer · 2025-12-04T12:01:00Z

lib/matplotlib/stackplot.py

+    if colors is None:
+        colors = [axes._get_lines.get_next_color() for _ in y]
+
+    kwargs['hatch'] = hatch


Unsure whether to do this or to remove hatch from the named parameters.

Not really important, but I'm inclined to remove the explicit hatch parameter. The code is simpler without and there's no reason to name this explicitly, but not other style parameters.

lib/matplotlib/stackplot.py

lib/matplotlib/axes/_axes.py

timhoffm · 2025-12-06T10:07:49Z

doc/release/next_whats_new/stackplot_style_sequences.rst

+    ax.stackplot(x, y1, y2,
+                 facecolor=['tab:red', 'tab:blue'],
+                 edgecolor=['black', 'gray'],
+                 linestyle=[':', '--'],
+                 linewidth=[2, 3],
+                 hatch=['.', '*'])


While it is structurally reasonable to also iterate edge-related parameters, I don't see a practical use case because the horizontal edges overlap, so that you get no clear picture / artifacts if they are different.

I would only do an example if we can come up with an example that may be actually used in practice.
We also don't have to showcase every aspect of the feature, e.g. different line widths should be extermely rare.

I played around a bit, but didn't produce a plot I actually liked, so just removed it.

@rcomer FYI: There may be arcane use cases for line styling in stackplots, e.g. one could add small finite linewidths in #22393 to compensate antialiasing artifacts of adjacent polygon edges with the same color. So it is good to have these options. But this use case is too special to be mentioned as an example.

timhoffm

Looks good. Comments are small suggestions.

lib/matplotlib/axes/_axes.py

timhoffm · 2025-12-06T20:49:42Z

lib/matplotlib/axes/_axes.py

-                'edgecolor': next(edgecolors),
-                'facecolor': next(facecolors),
-            })
+            kwargs.update(next(style_gen))


This is the correct translation keeping existing behavior.

Semi-OT: I'm wondering whether the behavior is logically correct: If patches is empty, we do not advance the style. This means depending on data contents the assignment of styles to datasets may vary.

I tried removing the if not patch loop, and the only test that failed was this one

matplotlib/lib/matplotlib/tests/test_axes.py

Lines 5116 to 5122 in 89aa371

def test_hist_unused_labels():

# When a list with one dataset and N elements is provided and N labels, ensure

# that the first label is used for the dataset and all other labels are ignored

fig, ax = plt.subplots()

ax.hist([[1, 2, 3]], label=["values", "unused", "also unused"])

_, labels = ax.get_legend_handles_labels()

assert labels == ["values"]

So I think we are not checking for an empty patch sequence, but rather a None that was created by zip_longest if there are more labels than datasets. I also tried creating histograms where the data is outside the bin range for 'bar', 'step' and 'stepfilled' types, and they all gave my an artist back, so I think there is always a patch for a dataset.

This could all be a bit more obvious though, and I wondering why we don't just enforce that the number of labels is the same as the number of datasets (or perhaps n_labels <= n_datasets).

bar() and grouped_bar() require the same length:

matplotlib/lib/matplotlib/axes/_axes.py

Lines 2601 to 2603 in 4aeb773

if len(patch_labels) != len(x):

raise ValueError(f'number of labels ({len(patch_labels)}) '

f'does not match number of bars ({len(x)}).')

matplotlib/lib/matplotlib/axes/_axes.py

Line 3331 in 89aa371

assert len(labels) == num_datasets

We should do the same for stackplot. If people do not want to label selected elements they should mark this explicitly in the list of labels.

Having said the above, the "unused labels" test came in at #28073, whereas the if patch check goes all the way back to 30fddc3. So there may be reasons that are not covered by tests 🫣

We should do the labels check and possible logic changes in patches as a follow-up.

lib/matplotlib/tests/test__style_helpers.py

lib/matplotlib/tests/test_axes.py

lib/matplotlib/stackplot.py

…ther plotting methods Co-authored-by: Ilakkuvaselvi Manoharan <ilakkmanoharan@gmail.com>

This reverts commit ab39326.

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

rcomer added the API: consistency label Dec 4, 2025

rcomer commented Dec 4, 2025

View reviewed changes

rcomer added the topic: plotting methods label Dec 4, 2025

rcomer added this to the v3.11.0 milestone Dec 4, 2025

rcomer commented Dec 4, 2025

View reviewed changes

lib/matplotlib/stackplot.py Show resolved Hide resolved

rcomer force-pushed the style-iterator branch from cf5016c to db8bfba Compare December 5, 2025 11:10

rcomer marked this pull request as draft December 5, 2025 11:49

rcomer marked this pull request as ready for review December 5, 2025 13:53

rcomer force-pushed the style-iterator branch from 478264e to ab39326 Compare December 5, 2025 14:39

timhoffm reviewed Dec 6, 2025

View reviewed changes

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

timhoffm reviewed Dec 6, 2025

View reviewed changes

timhoffm mentioned this pull request Dec 7, 2025

[Bug]: stackplot creates artifacts when height of input is zero #22393

Closed

rcomer force-pushed the style-iterator branch from 27dd4d3 to e2adeed Compare December 7, 2025 11:40

timhoffm approved these changes Dec 7, 2025

View reviewed changes

lib/matplotlib/stackplot.py Outdated Show resolved Hide resolved

github-actions bot added the topic: pyplot API label Dec 7, 2025

rcomer and others added 10 commits December 7, 2025 15:29

Consolidate style parameter handling for plotting methods that call o…

c624ca4

…ther plotting methods Co-authored-by: Ilakkuvaselvi Manoharan <ilakkmanoharan@gmail.com>

simplify

292b3e5

Revert "simplify"

9de925e

This reverts commit ab39326.

remove plot from whatsnew

9d77726

take hatch out of stackplot named parameters

2b5ee9a

Apply suggestions from timhoffm code review

55d1a5e

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

fix linting and stackplot test

ea8ac82

punctuation

c49771d

group versionadded info

c3f1633

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

remove named hatch param from pyplot.stackplot

11f44ee

rcomer force-pushed the style-iterator branch from 9b1838e to 11f44ee Compare December 7, 2025 15:29

	def test_hist_unused_labels():
	# When a list with one dataset and N elements is provided and N labels, ensure
	# that the first label is used for the dataset and all other labels are ignored
	fig, ax = plt.subplots()
	ax.hist([[1, 2, 3]], label=["values", "unused", "also unused"])
	_, labels = ax.get_legend_handles_labels()
	assert labels == ["values"]

	if len(patch_labels) != len(x):
	raise ValueError(f'number of labels ({len(patch_labels)}) '
	f'does not match number of bars ({len(x)}).')

Uh oh!

Consolidate style parameter handling for plotting methods that call other plotting methods #30808

Are you sure you want to change the base?

Consolidate style parameter handling for plotting methods that call other plotting methods #30808

Conversation

rcomer commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

PR checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

timhoffm Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rcomer commented Dec 4, 2025 •

edited

Loading

timhoffm Dec 6, 2025 •

edited

Loading