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.

rcomer · 2025-12-04T14:39:40Z

lib/matplotlib/stackplot.py

-    else:
-        colors = (axes._get_lines.get_next_color() for _ in y)
+    if colors is None:
+        colors = [axes._get_lines.get_next_color() for _ in y]


Changed this from a generator to a list because to_rgba_array needs something with a __len__.

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

timhoffm · 2025-12-06T09:59:36Z

lib/matplotlib/axes/_axes.py

        for i, (hs, label, color) in enumerate(zip(heights, labels, colors)):
            lefts = (group_centers - 0.5 * group_distance + margin_abs
                     + i * (bar_width + bar_spacing_abs))
            if orientation == "vertical":
                bc = self.bar(lefts, hs, width=bar_width, align="edge",
-                              label=label, color=color, **kwargs)
+                              label=label, color=color, **next(kwargs_gen))


This pattern is not ideal. It splits the iteration. Part of the advancement is done in for ... in ..., part is done through the next(). The kwargs_gen should go into the zip.

Also: Slight concern but probably ok for now: iterate_styles() is a bit invasive in that it handles also the non-style kwargs. After calling iterate_styles() the kwargs are folded into to generator and kwargs should likely not be used any further. In particular this means (1) all kwarg prepocessing has to be done before iterate_styles(), (2) we could not have another iterate_something() in the future.

The alternative would be something like

style_kwargs, kwargs = _style_helpers.extract_style_kwargs(kwargs) ... for i, (hs, label, color, style_kw) in enumerate(zip(heights, labels, colors, style_kwargs)): ... bar(..., color=color, **style_kw, **kwargs)

where we could still decide whether we extract constant style parameters and turn them into an iterator or leave them in kwargs.

So more like what I did in my first commit? 🙃

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.

This reverts commit ab39326.

timhoffm

Looks good. Comments are small suggestions.

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

lib/matplotlib/axes/_axes.py

+            The following properties additionally accept a sequence of values
+            corresponding to the datasets in *heights*:
+            *edgecolor*, *facecolor*, *linewidth*, *linestyle*, *hatch*.


Should we make this a bit more prominent?

Suggested change

The following properties additionally accept a sequence of values

corresponding to the datasets in *heights*:

*edgecolor*, *facecolor*, *linewidth*, *linestyle*, *hatch*.

Properties applied to all bars. The following properties additionally

accept a sequence of values corresponding to the datasets in

*heights*:

- *edgecolor*

- *facecolor*

- *linewidth*

- *linestyle*

- *hatch*

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.

timhoffm · 2025-12-06T20:55:21Z

lib/matplotlib/tests/test__style_helpers.py

+                                        ('hatch', ["/", "\\", "."]),
+                                        ('linestyle', ["-", "--", ":"]),
+                                        ('linewidth', [1, 1.5, 2])])
+def test_style_generator_list(key, value):


Suggested change

def test_style_generator_list(key, value):

def test_style_generator_list(key, value):

"""Test that style parameter lists are distributed to the generator."""

or as similar wording.

timhoffm · 2025-12-06T20:56:21Z

lib/matplotlib/tests/test__style_helpers.py

+                                        ('hatch', "/"),
+                                        ('linestyle', "-"),
+                                        ('linewidth', 1)])
+def test_style_generator_single(key, value):


Suggested change

def test_style_generator_single(key, value):

def test_style_generator_single(key, value):

"""Test that single-value style parameters are distributed to the generator."""

timhoffm · 2025-12-06T20:58:09Z

lib/matplotlib/tests/test__style_helpers.py

+
+
+@pytest.mark.parametrize('key', ['facecolor', 'hatch', 'linestyle'])
+def test_style_generator_empty(key):


Suggested change

def test_style_generator_empty(key):

def test_style_generator_raises_on_empty_style_parameter_list(key):

quite verbose, but now exactly telling what we test :)

timhoffm · 2025-12-06T21:00:39Z

lib/matplotlib/tests/test__style_helpers.py

+
+
+def test_style_generator_sequence_type_styles():
+    kw = {'facecolor':  ('r', 0.5),


Suggested change

kw = {'facecolor': ('r', 0.5),

"""

Test that sequence type style values are detected as single value

and passed to a all elements of the generator.

"""

kw = {'facecolor': ('r', 0.5),

timhoffm · 2025-12-06T21:06:53Z

lib/matplotlib/tests/test_axes.py

+    fcols = ['r', 'b']
+
+    fig, ax = plt.subplots()
+
+    colls = ax.stackplot(x, y1, y2, facecolor=fcols, colors=['c', 'm'])
+    for coll, fcol in zip(colls, fcols):
+        assert mcolors.same_color(coll.get_facecolor(), fcol)
+
+    # Plural alias should also work
+    colls = ax.stackplot(x, y1, y2, facecolors=fcols, colors=['c', 'm'])
+    for coll, fcol in zip(colls, fcols):
+        assert mcolors.same_color(coll.get_facecolor(), fcol)


Suggested change

fcols = ['r', 'b']

fig, ax = plt.subplots()

colls = ax.stackplot(x, y1, y2, facecolor=fcols, colors=['c', 'm'])

for coll, fcol in zip(colls, fcols):

assert mcolors.same_color(coll.get_facecolor(), fcol)

# Plural alias should also work

colls = ax.stackplot(x, y1, y2, facecolors=fcols, colors=['c', 'm'])

for coll, fcol in zip(colls, fcols):

assert mcolors.same_color(coll.get_facecolor(), fcol)

facecolors = ['r', 'b']

fig, ax = plt.subplots()

colls = ax.stackplot(x, y1, y2, facecolor=facecolors, colors=['c', 'm'])

for coll, fcol in zip(colls, facecolors):

assert mcolors.same_color(coll.get_facecolor(), facecolors)

# Plural alias should also work

colls = ax.stackplot(x, y1, y2, facecolors=facecolors, colors=['c', 'm'])

for coll, fcol in zip(colls, facecolors):

assert mcolors.same_color(coll.get_facecolor(), facecolors)

We can affort the additional letters, which IMHO makes this easier to read (In particular, fcols is prone to misinterpretation because (1) we have colls here and (2) col(s) is typically used as abbreviation for columns.

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

Consolidate style parameter handling for plotting methods that call o…

db8bfba

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

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

simplify

ab39326

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

rcomer added 2 commits December 6, 2025 11:26

Revert "simplify"

4ac0486

This reverts commit ab39326.

remove plot from whatsnew

27f7b40

timhoffm reviewed Dec 6, 2025

View reviewed changes

	def test_style_generator_list(key, value):
	def test_style_generator_list(key, value):
	"""Test that style parameter lists are distributed to the generator."""

	def test_style_generator_single(key, value):
	def test_style_generator_single(key, value):
	"""Test that single-value style parameters are distributed to the generator."""



		@pytest.mark.parametrize('key', ['facecolor', 'hatch', 'linestyle'])
		def test_style_generator_empty(key):

	def test_style_generator_empty(key):
	def test_style_generator_raises_on_empty_style_parameter_list(key):



		def test_style_generator_sequence_type_styles():
		kw = {'facecolor': ('r', 0.5),

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!

rcomer Dec 4, 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 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!

timhoffm left a comment

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rcomer commented Dec 4, 2025 •

edited

Loading

rcomer Dec 4, 2025 •

edited

Loading

timhoffm Dec 6, 2025 •

edited

Loading