DOC: AnnotationBbox keyword descriptions #24444

rcomer · 2022-11-13T12:28:27Z

PR Summary

Closes #24390.

Add a description of the bboxprops keyword for AnnotationBbox instantiation. At [Doc]: alpha setting for annotation TextArea #24390 (comment) @oscargus noted that arrowprops and fontsize are also missing from the docstring, but possibly they are covered by "Other parameters are identical to Annotation"? I note that the arrowprops description in Annotation is quite extensive, so am not sure of the wisdom of copying it across to related docstrings.
Modify the AnnotationBbox demo to include some examples using the bboxprops keyword. ~~While I was in there I also changed all double quotes to single quotes, as there is currently a mixture and I think it should be consistent within the example.~~

PR Checklist

Tests and Styling

[N/A] Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

Documentation is sphinx and numpydoc compliant (the docs should build without error).
[N/A] New plotting related features are documented with examples.

Release Notes

[N/A] New features are marked with a .. versionadded:: directive in the docstring and documented in doc/users/next_whats_new/
[N/A] API changes are marked with a .. versionchanged:: directive in the docstring and documented in doc/api/next_api_changes/
[N/A] Release notes conform with instructions in next_whats_new/README.rst or next_api_changes/README.rst

oscargus · 2022-11-13T15:56:17Z

I agree that one should probably not copy the arrowprops part, but maybe something like

arrowprops: dict, optional
    Arrow properties, see `.Annotation` for description.

fontsize: float or str, optional
    Font size, see `~Text.set_fontsize`.

?

As these properties are explicit in the constructor. (fontsize is documented as part of **kwargs in Annotation as "Additional kwargs are passed to Text" and not directly documented in Text either... One may wonder why it is explicitly mentioned in AnnotationBbox.

Turns out that annotation_clip is also missing...

Anyway, no strong opinions as such (I can always add those later), but I'll leave it for a while to see if someone has stronger opinions.

rcomer · 2022-11-13T16:45:18Z

Now I look deeper, I think having "Other parameters are identical to Annotation" next to **kwargs here is also wrong, or at least misleading. It implies that this **kwargs would include Annotation's **kwargs, which are passed to Text, as you say. But AnnotationBbox's **kwargs are passed to self._internal_update. So maybe the **kwargs description here should reference e.g. the set method?

examples/text_labels_and_annotations/demo_annotation_box.py

rcomer · 2022-11-13T19:52:15Z

I think I have addressed all the comments, but...

What text does this fontsize keyword apply to? If I put e.g. fontsize="xx-large" in the call to AnnotationBbox in my example at #24390, it doesn't seem to make a difference. That makes sense, as you would set the fontsize for the text in the box using the TextArea object instead. Is there some other text associated with the AnnotationBbox?

timhoffm · 2022-11-13T22:02:45Z

What text does this fontsize keyword apply to?

Looking into the code, the fontsize parameter is stored in a FontPropertiesobject at AnnotationBbox.prop and its only use is to define the mutation_scale parameter of the FancyBboxPatch, i.e. affecting attributes of the box style like padding and rounding of corners (if defined).

AFAICS we should rename fontsize to mutation_scale and deprecate prop. But ping @anntzer, who wrote this code in 2009.

anntzer · 2022-11-13T22:38:16Z

I didn't really look at what piece of code you're talking about (can you point out the line?) but I was certainly not involved with matplotlib development yet in 2009...

rcomer · 2022-11-14T09:39:52Z

I think mutation_scale can be passed as part of bboxprops, so we could just deprecate fontsize and direct the user to use bboxprops=dict(mutation_scale=x) instead? It would seem odd to me to have mutation_scale accessible at the top level when the other FancyBboxPatch parameters (like boxstyle) are passed within the dictionary.

matplotlib/lib/matplotlib/offsetbox.py

Lines 1296 to 1305 in 1fa7467

    
           self.patch = FancyBboxPatch(  # frame 
        
               xy=(0.0, 0.0), width=1., height=1., 
        
               facecolor='w', edgecolor='k', 
        
               mutation_scale=self.prop.get_size_in_points(), 
        
               snap=True, 
        
               visible=frameon, 
        
           ) 
        
           self.patch.set_boxstyle("square", pad=pad) 
        
           if bboxprops: 
        
               self.patch.set(**bboxprops)

timhoffm · 2022-11-14T12:00:22Z

I didn't really look at what piece of code you're talking about (can you point out the line?) but I was certainly not involved with matplotlib development yet in 2009...

Sorry, mixed up users. - Just read the short version "09.08.09 Lee", but it was @leejjoon. @leejjoon do you rember the motivation in AnnotationBbox to pass fontsize -> self.prop -> FancyBboxPatch(..., mutation_scale=...)?

matplotlib/lib/matplotlib/offsetbox.py

Line 1235 in 1fa7467

fontsize=None,

matplotlib/lib/matplotlib/offsetbox.py

Lines 1348 to 1358 in 1fa7467

    
               def set_fontsize(self, s=None): 
        
                   """ 
        
                   Set the fontsize in points. 
        
                   If *s* is not given, reset to :rc:`legend.fontsize`. 
        
                   """ 
        
                   if s is None: 
        
                       s = mpl.rcParams["legend.fontsize"] 
        
                   self.prop = FontProperties(size=s) 
        
                   self.stale = True

matplotlib/lib/matplotlib/offsetbox.py

Lines 1296 to 1302 in 1fa7467

    
           self.patch = FancyBboxPatch(  # frame 
        
               xy=(0.0, 0.0), width=1., height=1., 
        
               facecolor='w', edgecolor='k', 
        
               mutation_scale=self.prop.get_size_in_points(), 
        
               snap=True, 
        
               visible=frameon, 
        
           )

it indeed seems that mutation_scale can be passed already via bboxprops and the fontsize parameter is not needed at all.

rcomer · 2022-11-14T13:40:30Z

I guess using fontsize gives the user the convenience of passing a string, rather than points. Also it currently defaults to rcParams["legend.fontsize"]. If we left it to the FancyBBoxPatch default of 1, it would presumably look quite cramped.

So perhaps using fontsize is the most practical way to get a nice looking pad, etc., even though we are not dealing with any actual fonts.

Edit: AnchoredOffsetbox does something similar with the prop parameter.

leejjoon · 2022-11-14T18:21:34Z

My vague recollection is that I wanted to copy the behavior from annotation (and text) that the mutation scale is set to their fontsize. As @rcomer commented in his post, I think this was a sensible thing to do. The parameter name of fontsize could be misleading and may need to be replaced. It would be good if we can keep the current behavior, though.

rcomer · 2022-11-15T08:51:57Z

@timhoffm I have updated the fontsize description to explain how it is used. Do you think this is enough? Once we understand the reasoning, the name does not seem wrong to me. Perhaps a little unintuitive, but I wonder if that matters enough to go through the breaking change procedure.

timhoffm

@timhoffm I have updated the fontsize description to explain how it is used. Do you think this is enough? Once we understand the reasoning, the name does not seem wrong to me. Perhaps a little unintuitive, but I wonder if that matters enough to go through the breaking change procedure.

I still think the name is misleading because it does not affect any font. It only happens to be that mutation_scale is defined in such a way that setting mutation_scale to the used fontsize gives a reasonable scaling (e.g. for pad). That could also be done with an explicit name mutation_scale, including supporting string values.

That said, I would not name it like this again, but I'm not dogmatic about changing the name. When we have at least documented what the parameter is about that's already a big improvement. But if we keep the name AnnotationBbox.set_fontsize needs a similar description.

timhoffm · 2022-11-15T16:37:34Z

lib/matplotlib/offsetbox.py

@@ -1262,6 +1262,11 @@ def __init__(self, offsetbox, xy,
            (accessible as the ``patch`` attribute of the `.AnnotationBbox`).
            If *frameon* is set to False, this patch is made invisible.

+        annotation_clip: bool or None, default: None
+            Whether to clip (i.e. not draw) the annotation when the annotation
+            point *xy* is outside the axes area.  see `.Annotation` for


I think it's better to copy the whole description from Annotation. It's not likely to change, and there is value in having the explicit value description here. Not least because the docstring of Annotation is long and it's a bit cumbersome to find the relevant section.

timhoffm · 2022-11-15T16:42:37Z

lib/matplotlib/offsetbox.py

+            `.FancyBboxPatch` to scale attributes of the box style (e.g. pad
+            or rounding_size).  Passed here as *fontsize* for the convenience
+            of using the named sizes.  If not given, :rc:`legend.fontsize` is
+            used.  See `~.Text.set_fontsize` for valid values.


Suggested change

used. See `~.Text.set_fontsize` for valid values.

used. See `.Text.set_fontsize` for valid values.

so that it renders as Text.set_fontsize and not set_fontsize and by that make it very clear that its not AnnotationBbox.set_fontsize`.

timhoffm · 2022-11-15T17:09:21Z

lib/matplotlib/offsetbox.py

+            or rounding_size).  Passed here as *fontsize* for the convenience
+            of using the named sizes.  If not given, :rc:`legend.fontsize` is


Suggested change

or rounding_size). Passed here as *fontsize* for the convenience

of using the named sizes. If not given, :rc:`legend.fontsize` is

or rounding_size). If not given, :rc:`legend.fontsize` is

I'd leave this out. I think it's not really helpful for understanding (or even technically necessary to provide the convenience).

If you want to comment on the name, it should be more in the direction

the name is chosen in analogy to [...*] where fontsize defines the mutation scale as well.

* To be checked what exactly: Text/Annotation/Legend/FancyBboxPatch.

Looks like it's in Text

matplotlib/lib/matplotlib/text.py

Line 582 in 57710db

self._bbox_patch.set_mutation_scale(fontsize_in_pixel)

timhoffm · 2022-11-15T17:10:21Z

lib/matplotlib/offsetbox.py

        **kwargs
-            Other parameters are identical to `.Annotation`.
+            Other `AnnotationBbox` properties.  See `~.AnnotationBbox.set` for


Suggested change

Other `AnnotationBbox` properties. See `~.AnnotationBbox.set` for

Other `AnnotationBbox` properties. See `.AnnotationBbox.set` for

Minor, but I think it's slightly better to display the class here as well.

timhoffm · 2022-11-16T20:34:15Z

Thanks @rcomer! I appreciate this work. It's often more cumbersome than initially expected, but it really makes our docs much better.

…444-on-v3.6.x Backport PR #24444 on branch v3.6.x (DOC: AnnotationBbox keyword descriptions)

oscargus approved these changes Nov 13, 2022

View reviewed changes

oscargus added this to the v3.6.3 milestone Nov 13, 2022

timhoffm reviewed Nov 13, 2022

View reviewed changes

examples/text_labels_and_annotations/demo_annotation_box.py Outdated Show resolved Hide resolved

rcomer force-pushed the annotation-doc branch from 78307ab to 59abe41 Compare November 13, 2022 19:52

rcomer changed the title ~~DOC: describe bboxprops for AnnotationBbox~~ DOC: AnnotationBbox keyword descriptions Nov 13, 2022

rcomer force-pushed the annotation-doc branch from 59abe41 to 426b189 Compare November 14, 2022 15:08

timhoffm reviewed Nov 15, 2022

View reviewed changes

DOC: AnnotationBbox keyword descriptions

390b277

rcomer force-pushed the annotation-doc branch from 426b189 to 390b277 Compare November 16, 2022 14:45

story645 added the Documentation label Nov 16, 2022

timhoffm approved these changes Nov 16, 2022

View reviewed changes

timhoffm merged commit a9c9620 into matplotlib:main Nov 16, 2022

meeseeksmachine mentioned this pull request Nov 16, 2022

Backport PR #24444 on branch v3.6.x (DOC: AnnotationBbox keyword descriptions) #24478

Merged

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Nov 16, 2022

Backport PR matplotlib#24444: DOC: AnnotationBbox keyword descriptions

2d3e45f

rcomer deleted the annotation-doc branch November 16, 2022 20:51

ksunden added a commit that referenced this pull request Nov 16, 2022

Merge pull request #24478 from meeseeksmachine/auto-backport-of-pr-24…

4d06715

…444-on-v3.6.x Backport PR #24444 on branch v3.6.x (DOC: AnnotationBbox keyword descriptions)

ksunden mentioned this pull request Feb 20, 2023

merge up 3.7.0 #25270

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: AnnotationBbox keyword descriptions #24444

DOC: AnnotationBbox keyword descriptions #24444

rcomer commented Nov 13, 2022 •

edited

Loading

oscargus commented Nov 13, 2022

rcomer commented Nov 13, 2022

rcomer commented Nov 13, 2022

timhoffm commented Nov 13, 2022

anntzer commented Nov 13, 2022

rcomer commented Nov 14, 2022

timhoffm commented Nov 14, 2022 •

edited

Loading

rcomer commented Nov 14, 2022 •

edited

Loading

leejjoon commented Nov 14, 2022

rcomer commented Nov 15, 2022

timhoffm left a comment •

edited

Loading

timhoffm Nov 15, 2022

timhoffm Nov 15, 2022

timhoffm Nov 15, 2022

rcomer Nov 16, 2022

timhoffm Nov 15, 2022

timhoffm commented Nov 16, 2022

	used. See `~.Text.set_fontsize` for valid values.
	used. See `.Text.set_fontsize` for valid values.

		or rounding_size). Passed here as fontsize for the convenience
		of using the named sizes. If not given, :rc:`legend.fontsize` is

	or rounding_size). Passed here as fontsize for the convenience
	of using the named sizes. If not given, :rc:`legend.fontsize` is
	or rounding_size). If not given, :rc:`legend.fontsize` is

	Other `AnnotationBbox` properties. See `~.AnnotationBbox.set` for
	Other `AnnotationBbox` properties. See `.AnnotationBbox.set` for

DOC: AnnotationBbox keyword descriptions #24444

DOC: AnnotationBbox keyword descriptions #24444

Conversation

rcomer commented Nov 13, 2022 • edited Loading

PR Summary

PR Checklist

oscargus commented Nov 13, 2022

rcomer commented Nov 13, 2022

rcomer commented Nov 13, 2022

timhoffm commented Nov 13, 2022

anntzer commented Nov 13, 2022

rcomer commented Nov 14, 2022

timhoffm commented Nov 14, 2022 • edited Loading

rcomer commented Nov 14, 2022 • edited Loading

leejjoon commented Nov 14, 2022

rcomer commented Nov 15, 2022

timhoffm left a comment • edited Loading

Choose a reason for hiding this comment

timhoffm Nov 15, 2022

Choose a reason for hiding this comment

timhoffm Nov 15, 2022

Choose a reason for hiding this comment

timhoffm Nov 15, 2022

Choose a reason for hiding this comment

rcomer Nov 16, 2022

Choose a reason for hiding this comment

timhoffm Nov 15, 2022

Choose a reason for hiding this comment

timhoffm commented Nov 16, 2022

rcomer commented Nov 13, 2022 •

edited

Loading

timhoffm commented Nov 14, 2022 •

edited

Loading

rcomer commented Nov 14, 2022 •

edited

Loading

timhoffm left a comment •

edited

Loading