Add a new orientation parameter to Violinplot and deprecate vert

[saranti]

PR summary

Partially closes #13435. Replace the vert: bool parameter with orientation : {'vertical', 'horizontal'}.
Also changed the Violin plot basics gallery example to reflect the changes.

The other half of issue #13435 is to do the same to boxplots

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

[QuLogic]

orientation can't be inserted in the middle here to prevent breaking passing all arguments positionally. I believe that will be fixed by #27786.

[saranti]

Since #27786 is now merged, should we put orientation in the place where vert was?

[timhoffm]

It would also be nice to make this a pending deprecation at first. Otherwise users of downstream libraries like seaborn (attn @mwaskom) will see our deprecation warning, but cannot do anything about it because it's in the seaborn code base. During the pending period, downstream libraries can already switch to the new API.

[mwaskom]

Thoughtful but no need specifically for seaborn — seaborn's violinplots predate matplotlib's by several years :D

[timhoffm]

Thanks for the feedback. I’ve only checked boxplot, which will get the same change ( #13435).

[mwaskom]

Oh actually boxplot is relevant to me. But I don’t think this is right:

It would also be nice to make this a pending deprecation at first. Otherwise users of downstream libraries like seaborn (attn @mwaskom) will see our deprecation warning

The DeprecationWarning class is fine; by default it only shows up in tests or when raised in “main”. The issue is when libraries jump straight to FutureWarning, which is always visible.

[saranti]

Edit: This block of code is going to be copied verbatim for the boxplots. Would it be better to turn it into a function and add it to _axes.py or cbook?
It's only needed during the deprecation period. Once it's over, the whole thing will be removed.

matplotlib/lib/matplotlib/axes/_axes.py

Lines 8553 to 8566 in 78ac503

	if vert is not None:
	_api.warn_deprecated(
	"3.10",
	name="vert: bool",
	alternative="orientation: {'vertical', 'horizontal'}"
	)
	# vert and orientation parameters are linked until vert's
	# deprecation period expires. If both are selected,
	# vert takes precedence.
	if vert or vert is None and orientation is None:
	orientation = 'vertical'
	elif vert is False:
	orientation = 'horizontal'

[timhoffm]

I'm not following the logic here completely. After whatever mangling vert and orientation, shouldn't we have a normalized orientation that must be 'horizontal' or 'vertical'? In other words

• Why do we allow orientation to be None in 8617 and would that even work for the following code?

Can't we simply

if vert is not None:
    _api.warn_deprecated(...)
    orientation = 'vertical' if vert else 'horizontal'
_api.check_in_list(['horizontal', 'vertical'], orientation=orientation)

and default orientation='vertical' instead of defaulting it to None?

[saranti]

Yes it should default to vertical instead of None (it even says so in the docstring) so there was no reason for it other than making it more convoluted. That code change is great, I'll add it to the next commit

[rcomer]

This seems much simpler than the boxplot one!

This block of code is going to be copied verbatim for the boxplots. Would it be better to turn it into a function and add it to _axes.py or cbook?
It's only needed during the deprecation period. Once it's over, the whole thing will be removed.

This is a good point. I think my inclination is to leave it duplicated in the two functions. It's pretty simple (more simple now than when you asked the question!) so I don't think the duplication does much harm.

[rcomer]

Suggested change

	vert : bool, default: True.
	vert : bool, optional

(optional is synonymous with default: None)