Show box/arrowstyle parameters in reference examples. #20538

anntzer · 2021-06-28T11:06:42Z

This will allow later removing the table of values in the annotation
tutorial.

Also, draw things each in their axes and in axes coordinates, to
simplify the code.

Split out of #20531.

Before:

After:

In #20531 (comment) @timhoffm has argued against the addition of all parameters; I think specifically for the example the effect may be neutral or indeed perhaps slightly negative, but the point is actually to remove the tables at

matplotlib/tutorials/text/annotations.py

Lines 139 to 151 in 60ff0d4

    
           #   ==========   ==============   ========================== 
        
           #   Class        Name             Attrs 
        
           #   ==========   ==============   ========================== 
        
           #   Circle       ``circle``       pad=0.3 
        
           #   DArrow       ``darrow``       pad=0.3 
        
           #   LArrow       ``larrow``       pad=0.3 
        
           #   RArrow       ``rarrow``       pad=0.3 
        
           #   Round        ``round``        pad=0.3,rounding_size=None 
        
           #   Round4       ``round4``       pad=0.3,rounding_size=None 
        
           #   Roundtooth   ``roundtooth``   pad=0.3,tooth_size=None 
        
           #   Sawtooth     ``sawtooth``     pad=0.3,tooth_size=None 
        
           #   Square       ``square``       pad=0.3 
        
           #   ==========   ==============   ==========================

and

matplotlib/tutorials/text/annotations.py

Lines 241 to 256 in 60ff0d4

    
           #     ==========   ============================================= 
        
           #     Name         Attrs 
        
           #     ==========   ============================================= 
        
           #     ``-``        None 
        
           #     ``->``       head_length=0.4,head_width=0.2 
        
           #     ``-[``       widthB=1.0,lengthB=0.2,angleB=None 
        
           #     ``|-|``      widthA=1.0,widthB=1.0 
        
           #     ``-|>``      head_length=0.4,head_width=0.2 
        
           #     ``<-``       head_length=0.4,head_width=0.2 
        
           #     ``<->``      head_length=0.4,head_width=0.2 
        
           #     ``<|-``      head_length=0.4,head_width=0.2 
        
           #     ``<|-|>``    head_length=0.4,head_width=0.2 
        
           #     ``fancy``    head_length=0.4,head_width=0.4,tail_width=0.4 
        
           #     ``simple``   head_length=0.5,head_width=0.5,tail_width=0.2 
        
           #     ``wedge``    tail_width=0.3,shrink_factor=0.5 
        
           #     ==========   =============================================

which can easily go out of sync and aren't particularly nice in the rendered docs either.

(Effectively, we have the problem that the example serves both as a standalone example and to generate a figure for the narrative tutorial, but I don't think it's worth duplicating the code to have two separate versions for the two tasks.)

Thoughts?

PR Summary

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

story645 · 2021-06-28T17:09:59Z

examples/shapes_and_collections/fancybox_demo.py

+    ax.text(.5, .5,
+            f"{stylename}\n{inspect.signature(stylecls)}",
+            transform=ax.transAxes, ha="center", va="center",
+            bbox=dict(boxstyle=stylename, fc="w", ec="k"))


anyway to make the boxes slightly bigger? especially for the sawtooth and round4, the styling gets a little lost in the smaller size.

Actually these are the default params, and I'd rather keep using the defaults for the reference docs?

Hmm, makes sense, but ugh so hard to differentiate :/ is it cause size is determined by pad? And then hmm, could changing the color help? maybe an inside gray to make the border pop?

It's proportional to the fontsize by default. I'll let you judge whether gray is better...

story645 · 2021-06-28T17:11:33Z

I like the idea of the parameters next to the images since it makes it very clear ~~these aren't defaults~~ what's controlled by parameters.

timhoffm · 2021-06-28T20:02:15Z

I like the idea of the parameters next to the images since it makes it very clear ~~these aren't defaults~~ [...].

🤣 SCNR, but this is part of my point.

I see the desire to provide the parameters, but as of now they are really cluttering the images. 1) It's hard to see what the main
distincting parameters are 2) It's not clear what these additional parameters mean.

We don't have rich-text do we? Otherwise we could use color/font weight/font size to highlight the main parameter compared to the other parameters.

timhoffm · 2021-06-28T21:06:09Z

I think, we'd rather want something like

import inspect

import matplotlib.pyplot as plt
import matplotlib.transforms as mtransforms
import matplotlib.patches as mpatch
from matplotlib.patches import FancyBboxPatch

styles = mpatch.BoxStyle.get_styles()
ax = plt.figure(figsize=(5, len(styles))).add_axes([0, 0, 1, 1])
ax.set_axis_off()
ax.set(xlim=(0, 1), ylim=(len(styles) + 0.5, -0.5))

ax.text(.15, 0, 'boxstyle', fontsize=18, ha="center", va="center")
ax.text(.45, 0, 'default parameters', fontsize=18, va="center")

for i, (stylename, stylecls) in enumerate(styles.items(), start=1):
    ax.text(.15, i, stylename, fontsize=15, color='tab:blue',
            ha="center", va="center",
            bbox=dict(boxstyle=stylename, fc="w", ec="k"))
    ax.text(.45, i, str(inspect.signature(stylecls))[1:-1].replace(', ', '\n'),
            va='center')

Similarly for the arrow style (e.g. move the parameters to the right, highlight the style name in blue, make the target marker grey).

anntzer · 2021-06-30T10:27:34Z

How do the ones below look to you?

I think specifically for arrows it's better to keep the arrowstyle on the left (because that's what "<-" means...), and then it seems natural to keep the parameters next to the arrowstyle...

timhoffm · 2021-06-30T12:29:16Z

These look good. Some minor improvements:

The style labels could be a bit larger
left-align the boxstyle parameters
Agreed that the arrows should stay as is, e.g.

Nevertheless the parameters could be on their right (parameters are less important than the style names, and english reading direction is left-to-right).
If you really want to keep the parameters on the left, still consider to left-align the text. I haven't tried but anticipate that this would look cleaner.

QuLogic · 2021-06-30T22:19:08Z

In #20546, I'm dropping the 50% scale of the figures in the tutorials, because they are generally too small to be useful. I'm not sure exactly how big the figure ends up here now, but in order to avoid scaling, it would be good if you can make the figure fit the text width of the new theme. That would be about 749.167 pixels, or just under 7.5 inches at 100 DPI (though I wonder if we could tweak the theme to be a rounder number.)

anntzer · 2021-06-30T22:21:04Z

Sure. Perhaps you can document that size somewhere?

timhoffm · 2021-06-30T22:51:32Z

Previously, the content width was 919px. Reducing that in the new theme is a broader issue that will cause many figures to be rescaled and thus look blurry. We have

figsize=(8: 43
figsize=(9: 16
figsize=(1x: 22

It's worth discussing if we want to increase the width of the theme. Going to 800px would at least save the 43 figures with 8inch width.

Once decided, the width should be documented in Writing examples and tutorials.

anntzer · 2021-07-01T19:39:34Z

[Agreed that I should just pick a size and go with it for now.]

This will allow later removing the table of values in the annotation tutorial. Also, draw things each in their axes and in axes coordinates, to simplify the code.

timhoffm

I'm not 100% happy with using a grid of Axes instead of positioning the elements in a single Axes. This makes the example more complicated IMHO. In particular, you need a lot of transform=ax.transAxes, which is a non-trivial concept.

That is okish, because the main purpose of the example is the overview image, not how you generated it. Conceptually simpler code would still be better, but I'll merge as an improvement. We can always have further changes in a followup OR.

anntzer added the Documentation label Jun 28, 2021

story645 reviewed Jun 28, 2021

View reviewed changes

QuLogic mentioned this pull request Jun 29, 2021

Improve tutorial figures in the new theme #20546

Merged

3 tasks

jklymak added the status: needs rebase label Jul 1, 2021

jklymak marked this pull request as draft July 1, 2021 19:53

anntzer marked this pull request as ready for review July 4, 2021 16:38

anntzer force-pushed the styleref branch from 46d5a24 to d9219ff Compare July 4, 2021 16:38

Show box/arrowstyle parameters in reference examples.

9c596ab

This will allow later removing the table of values in the annotation tutorial. Also, draw things each in their axes and in axes coordinates, to simplify the code.

anntzer force-pushed the styleref branch from d9219ff to 9c596ab Compare July 4, 2021 16:41

anntzer removed the status: needs rebase label Jul 4, 2021

timhoffm approved these changes Jul 4, 2021

View reviewed changes

timhoffm added this to the v3.5.0 milestone Jul 4, 2021

timhoffm merged commit 20b13ff into matplotlib:master Jul 4, 2021

anntzer deleted the styleref branch July 4, 2021 21:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Show box/arrowstyle parameters in reference examples. #20538

Show box/arrowstyle parameters in reference examples. #20538

anntzer commented Jun 28, 2021

story645 Jun 28, 2021 •

edited

Loading

anntzer Jun 28, 2021

story645 Jun 28, 2021

anntzer Jun 28, 2021

story645 commented Jun 28, 2021 •

edited

Loading

timhoffm commented Jun 28, 2021

timhoffm commented Jun 28, 2021 •

edited

Loading

anntzer commented Jun 30, 2021

timhoffm commented Jun 30, 2021

QuLogic commented Jun 30, 2021

anntzer commented Jun 30, 2021

timhoffm commented Jun 30, 2021

anntzer commented Jul 1, 2021

timhoffm left a comment

	# ========== ============== ==========================
	# Class Name Attrs
	# ========== ============== ==========================
	# Circle ``circle`` pad=0.3
	# DArrow ``darrow`` pad=0.3
	# LArrow ``larrow`` pad=0.3
	# RArrow ``rarrow`` pad=0.3
	# Round ``round`` pad=0.3,rounding_size=None
	# Round4 ``round4`` pad=0.3,rounding_size=None
	# Roundtooth ``roundtooth`` pad=0.3,tooth_size=None
	# Sawtooth ``sawtooth`` pad=0.3,tooth_size=None
	# Square ``square`` pad=0.3
	# ========== ============== ==========================

	# ========== =============================================
	# Name Attrs
	# ========== =============================================
	# ``-`` None
	# ``->`` head_length=0.4,head_width=0.2
	# ``-[`` widthB=1.0,lengthB=0.2,angleB=None
	# ``\|-\|`` widthA=1.0,widthB=1.0
	# ``-\|>`` head_length=0.4,head_width=0.2
	# ``<-`` head_length=0.4,head_width=0.2
	# ``<->`` head_length=0.4,head_width=0.2
	# ``<\|-`` head_length=0.4,head_width=0.2
	# ``<\|-\|>`` head_length=0.4,head_width=0.2
	# ``fancy`` head_length=0.4,head_width=0.4,tail_width=0.4
	# ``simple`` head_length=0.5,head_width=0.5,tail_width=0.2
	# ``wedge`` tail_width=0.3,shrink_factor=0.5
	# ========== =============================================

Show box/arrowstyle parameters in reference examples. #20538

Show box/arrowstyle parameters in reference examples. #20538

Conversation

anntzer commented Jun 28, 2021

PR Summary

PR Checklist

story645 Jun 28, 2021 • edited Loading

Choose a reason for hiding this comment

anntzer Jun 28, 2021

Choose a reason for hiding this comment

story645 Jun 28, 2021

Choose a reason for hiding this comment

anntzer Jun 28, 2021

Choose a reason for hiding this comment

story645 commented Jun 28, 2021 • edited Loading

timhoffm commented Jun 28, 2021

timhoffm commented Jun 28, 2021 • edited Loading

anntzer commented Jun 30, 2021

timhoffm commented Jun 30, 2021

QuLogic commented Jun 30, 2021

anntzer commented Jun 30, 2021

timhoffm commented Jun 30, 2021

anntzer commented Jul 1, 2021

timhoffm left a comment

Choose a reason for hiding this comment

story645 Jun 28, 2021 •

edited

Loading

story645 commented Jun 28, 2021 •

edited

Loading

timhoffm commented Jun 28, 2021 •

edited

Loading