Closes#27792. Boxplots now get legend entries.
This was previously attempted on#27711 and then reverted#27780 because it used the same parameter for tick labels and didn't generalize well. These 2 issues have been addressed in this PR.

A newlabel parameter has been added toAxes.boxplot andAxes.bxp. If called viaax.boxplot(), label is passed to the bxp function, otherwise bxp can be directly called with the label parameter.

The label is passed to theboxes object ifshowbox=True, otherwise it will be passed to themedians object isshowbox=False. Attaching the label to the boxes makes sure that the legend handles will get a patch which will be displayed on the legend.
If the box is turned off, the legend handles will get a Line2D object from the median line which will be displayed as a line in the legend. This has 2 advantages:

It suits the aesthetics of a boxless plot
Unlike thebox,caps,flyers andmeans, themedians cannot be turned off so they're a good vehicle for the legend label and will ensure that the labels always get set.

Click to old test cases

PR checklist

"closes #0000" is in the body of the PR description tolink the related issue
new and changed code istested
Plotting related features are demonstrated in anexample
New Features andAPI Changes are noted with adirective and release note
Documentation complies withgeneral anddocstring guidelines

github-actionsbot added topic: pyplot API status: needs rebase labels

Mar 1, 2024

saranti force-pushed thebox_legend_support branch from3cfd4ab to68edfcbCompare

March 2, 2024 02:58

github-actionsbot removed the status: needs rebase label

Mar 2, 2024

Copy link

ContributorAuthor

saranti commentedMar 2, 2024•
edited
Loading

Other things that need to be done at some stage:

Add an example. 3 possible options are:
- Adding a legend tohttps://matplotlib.org/devdocs/gallery/statistics/boxplot_color.html
- Replacing the basic legend in the second example inhttps://matplotlib.org/devdocs/gallery/statistics/boxplot_demo.html
- Add a whole new example plot

saranti marked this pull request as draft

March 3, 2024 04:30

saranti force-pushed thebox_legend_support branch fromb03b849 to9c033d2Compare

March 3, 2024 11:55

github-actionsbot added status: needs rebase and removed status: needs rebase labels

Mar 3, 2024

saranti marked this pull request as ready for review

March 3, 2024 12:09

rcomer reviewed

Mar 3, 2024

View reviewed changes

Copy link

Member

rcomer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thanks for your work on this@saranti. It looks like you've done some good work pulling a variety of strands together.

One thing I'm a bit confused about is how the legend label is passed fromboxplot tobxp. It is passed both as part of theboxprops dictionary and by itself. Why not just pass with thelabel parameter?

doc/api/next_api_changes/deprecations/27840-TS.rst Outdated

		@@ -0,0 +1,5 @@
		``boxplot`` legend labels
		~~~~~~~~~~~~~~~~~~~~~~~~~
		The tick labels on `~.Axes.boxplot` were previously set with the `labels` parameter.

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

	The tick labels on `~.Axes.boxplot` were previously set with the`labels` parameter.
	The tick labels on `~.Axes.boxplot` were previously set with thelabels parameter.

When you use backticks, Sphinx tries to turn the word into a link. We have a convention to useemphasis for parameters.

Copy link

ContributorAuthor

sarantiMar 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

You're right, theboxprops label is redundant. When i first implemented this, I used it as the only check to see iflabels has been set but then I realized that it should've been set at the bxp function. Everything in the 'if boxprops' condition is no longer needed.

doc/users/next_whats_new/boxplot_legend_support.rst Outdated

		Legend support for Boxplot
		~~~~~~~~~~~~~~~~~~~~~~~~~~
		Boxplots now generate legend entries and can be labelled with the
		new `label` parameter. If a patch is passed to the box with `show_patch=True`,

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

	new`label` parameter. If a patch is passed to the box with `show_patch=True`,
	newlabel parameter. If a patch is passed to the box with ``show_patch=True``,

Double backtick gets you code formatting.

lib/matplotlib/axes/_axes.py Outdated

		@@ -3884,10 +3885,12 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
		If `False` produces boxes with the Line2D artist. Otherwise,
		boxes are drawn with Patch artists.

		labels : sequence, optional
		tick_labels : sequence, optional
		Labels for each dataset (one per dataset). These are used for
		x-tick labels; not for legend entries.

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Since the parameter now has a more specific name, I think we no longer need the note about them not being for the legend.

lib/matplotlib/axes/_axes.py

		label : sequence, optional
		Legend labels for each boxplot.

		.. versionadded:: 3.9

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

IIRC thedata parameter is special and should always come last.

lib/matplotlib/axes/_axes.py Outdated

		box_or_whis = boxes if showbox else whiskers
		for index, element in enumerate(box_or_whis):
		try:
		if isinstance(boxprops['label'], list):

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I thinkis_scalar_or_string may be useful here.

lib/matplotlib/tests/test_legend.py Outdated

		with pytest.warns(mpl.MatplotlibDeprecationWarning,
		match='has been renamed \'tick_labels\''):
		first = axs[0, 0].boxplot(data,
		labels=labels, # `tick_labels`

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Maybe usetick_labels here rather than the deprecated name?

Copy link

ContributorAuthor

sarantiMar 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

If I don't use the deprecated name then this pytest will fail.

lib/matplotlib/tests/test_legend.py Outdated


		# This plot will not generate a legend.
		with pytest.warns(UserWarning, match='No artists with labels found'):
		warnings.warn('No artists with labels found.', UserWarning)

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I think this might be a stray debugging line?

Copy link

ContributorAuthor

sarantiMar 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Yes it is. I'm having trouble trying to get pytest to catch the UserWarning whenlegend is called without the labels being set. The list of emitted warnings is always null even though the warning is clearly raised in

matplotlib/lib/matplotlib/legend.py

Lines 1364 to 1370 in013757e

	eliflen(args)==0:# 0 args: automatically detect labels and handles.
	handles,labels=_get_legend_handles_labels(axs,handlers)
	ifnothandles:
	_api.warn_external(
	"No artists with labels found to put in legend. Note that "
	"artists whose label start with an underscore are ignored "
	"when legend() is called with no argument.")

lib/matplotlib/tests/test_legend.py Outdated

		showmeans=True,
		patch_artist=True)
		axs[0, 1].set_title('Tick labels, no legend')
		axs[0, 1].legend()

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

It might be good for this test toget hold of the legend handles and labels and assert that these lists are empty.

lib/matplotlib/tests/test_legend.py OutdatedShow resolvedHide resolved

lib/matplotlib/axes/_axes.py Outdated

		@@ -3956,6 +3959,10 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
		The style of the mean.
		data : indexable object, optional
		DATA_PARAMETER_PLACEHOLDER
		label : sequence, optional

Copy link

Member

rcomerMar 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I think this could be a single string or a sequence?

Copy link

ContributorAuthor

sarantiMar 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This might actually need to bestr or list of str

rcomer added topic: ticks axis labels topic: legend labels

Mar 3, 2024

github-actionsbot removed topic: ticks axis labels topic: legend labels

Mar 4, 2024

Copy link

Member

rcomer commentedMar 4, 2024

The tests failed because of a problem with a new version of pytest which has now been yanked. I’m going to close and re-open to restart the CI.

rcomer closed this

Mar 4, 2024

rcomer reopened this

Mar 4, 2024

Copy link

Member

timhoffm commentedMar 4, 2024•
edited
Loading

AFAICT, this needs a rebase to pick up the pytest pinning.

saranti force-pushed thebox_legend_support branch from008c0a5 todd84a56Compare

March 5, 2024 13:16

github-actionsbot added the Documentation: examplesfiles in galleries/examples label

Mar 5, 2024

saranti marked this pull request as draft

March 5, 2024 13:17

saranti force-pushed thebox_legend_support branch fromdd84a56 to0b5d5d6Compare

March 6, 2024 03:18

Copy link

ContributorAuthor

saranti commentedMar 6, 2024

@melissawm Thanks for the help yesterday, the rebase seems to have gone fine. The only problem I see now is that all the code having to do with the violin plot shouldn't be there and belongs to#27815

Copy link

Member

rcomer commentedMar 8, 2024

@saranti your branch is still 60 commits behindmain. I think you just need

git fetch upstreamgit rebase upstream/main

to get it up to date. That should also get rid of the violinplot changes.

saranti force-pushed thebox_legend_support branch from0b5d5d6 toe1bb638Compare

March 8, 2024 08:34

github-actionsbot removed the Documentation: examplesfiles in galleries/examples label

Mar 8, 2024

saranti marked this pull request as ready for review

March 8, 2024 08:47

timhoffm reviewed

Mar 8, 2024

View reviewed changes

Copy link

Member

timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I feel uncomfortable with the scope of the PR - which has prevented me from looking more closely. It mixes the two independent topics legend support and parameter rename. I would I encourage separate PRs or at least separate commits to make it clear which feature is responsible for which code changes, and to ease review.

doc/api/next_api_changes/deprecations/27840-TS.rst OutdatedShow resolvedHide resolved

saranti marked this pull request as draft

March 9, 2024 03:42

github-actionsbot removed the status: needs rebase label

Mar 15, 2024

saranti force-pushed thebox_legend_support branch from9fcf0c0 to73f2933Compare

March 15, 2024 05:14

github-actionsbot added the status: needs rebase label

Mar 15, 2024

saranti force-pushed thebox_legend_support branch from73f2933 tocae8a5dCompare

March 15, 2024 05:17

github-actionsbot removed the status: needs rebase label

Mar 15, 2024

saranti force-pushed thebox_legend_support branch 2 times, most recently from9fcf0c0 toc17906fCompare

March 15, 2024 05:50

Copy link

ContributorAuthor

saranti commentedMar 15, 2024

The old tick label test was still there after doinggit pull upstream. I removed it as part of the conflict resolution but it's showing up in the diff 🤔

Copy link

Member

rcomer commentedMar 15, 2024

I’ve never usedgit pull upstream so not really sure what that does. To get up to date with changes that have been merged tomain, it is recommended to userebase.
https://matplotlib.org/devdocs/devel/development_workflow.html#rebase-onto-upstream-main