If you set a float alpha on your patch then including alphas in your face/edgecolor will have no effect. I expect there are other docstrings that would benefit from spelling this out, but here is a start.

cc@pawjast

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

Copy link

Member

timhoffm commentedAug 12, 2024

I've been thinking about this the other day. We are not properly explaining the alpha mechanism.

This concerns mostalpha kwargs andset_alpha() functions (e.g. **Artist.set_alpha

I'd like to see

a constistent mention of either "transparent" or "opaque" (can't decice which one - technically "opaque" is more correct because it has the right sign - alpha is a measure of opaqueness not transparency. OTOH transparency may be easier to understand.)
a separate description of the alpha blending concept that all the docstrings could link to.
- This description could possibly link outhttps://en.wikipedia.org/wiki/Alpha_compositing.
- This should also explain the differences between the "global" Artist alpha (set throughalpha kwargs orset_alpha()) and alpha values in colors: If set, the Artist alpha overwrites any color-specific alphas. By default the Artist alpha is not set (i.e.None).

timhoffm reviewed

Aug 12, 2024

View reviewed changes

lib/matplotlib/patches.py Outdated

Comment on lines 383 to 384

		Note that any alpha value included in this color will be ignored
		unless the patch's alpha is set to ``None``.

Copy link

Member

timhoffmAug 12, 2024

Choose a reason for hiding this comment

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

I suggest not to add this note to all color parameters (of which we have plenty), but instead go for a centralized description as mentioned above (either in the target of:mpltyle:`color` or linked from there.

story645 reviewed

Aug 12, 2024

View reviewed changes

lib/matplotlib/axes/_axes.py

		@@ -452,8 +452,10 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
		edgecolor : :mpltype:`color`, default: '0.5'
		Color of the rectangle and color of the connecting lines.

		alpha : float, default: 0.5
		Transparency of the rectangle and connector lines.
		alpha : float or None, default: 0.5

Copy link

Member

story645Aug 12, 2024•
edited
Loading

Choose a reason for hiding this comment

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

we should maybe change the default? The use case for alpha taking precedence was user passed in alpha trumping color tuple alpha.#24691 (comment)

Uh@timhoffm? (wrote this before I saw Tim's comment 😓 )

Copy link

Member

timhoffmAug 12, 2024

Choose a reason for hiding this comment

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

Agree that this is not ideal, because you cannot set face and edge transparencies independently without first resetting alpha.

In general, this seems not too useful by default: I would have expected the edgecolors to be solid (=frame should be above the plot). There is no facecolor by default. The only thing this serves is that you can get a semi-transparent face by specifying a simple solid color - OTOH that's confusing.

I suggest to change this toNone by default. Optionally, change edgecolor to be the solid-equivalent color of('0.5', 0.5) against a white background. But I'm inclined to see both the grey "0.5" and the alpha=0.5 as uncoordinated ways to lighten the frame and suspect using both is not intentional. So possibly, just keep edgecolor as is.

Overall I'd just do it and call it a bug fix.

Copy link

Member

jklymakAug 12, 2024

Choose a reason for hiding this comment

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

alpha = 0.5 was originally for the lines that indicate the inset which often cross data, and hence its nice to have some indication of the data underneath. It was not meant to apply to the facecolor of the inset indicator patch.

Copy link

MemberAuthor

rcomerAug 13, 2024

Choose a reason for hiding this comment

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

The current defaults make sense to me. The point of these patches is to point to some other features we areindicating, so they should interfere as little as possible with our view of those things. I think most of the time a user would not want a facecolor because that would make it harder to see the colours of the thing they areindicating. With this PR we will have documented how to change the alpha for the rarer occasions when a facecolor is wanted and the face/edge alpha should be different.

Copy link

Member

story645Aug 13, 2024•
edited
Loading

Choose a reason for hiding this comment

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

Thanks@rcomer, was thinking of it in very general artists terms and not the specific use case 🤦‍♀️
I think you make a good point so now agree that doc solution is better here.