custom legends example #9451

choldgraf · 2017-10-17T00:04:15Z

This is an example to demonstrate how to create legends from scratch using Matplotlib objects. This is often useful if you add a lot of elements to a plot but only want to point out a couple in your legend.

Some stuff that could be improved:

Link to other places in the docs that show how to do this. Right now I only know of one bit at the end of the legend tutorial.
Add other common elements to add to a legend in the way that it's done in this example.

QuLogic · 2017-10-17T00:40:12Z

At the moment, I'm not quite sure how this is different from the legend tutorial?

choldgraf · 2017-10-17T00:49:46Z

It's the same content in a concise, example format. I don't see a problem with having the same content spread across the examples and the tutorials...i think it makes the content more discoverable...

afvincent

A few remarks.

afvincent · 2017-10-17T00:20:34Z

examples/text_labels_and_annotations/custom_legends.py

+
+fig, ax = plt.subplots()
+lines = ax.plot(data)
+ax.legend(lines, loc=(1.05, .05), )


Isn't the rightest part of the legend cut out if one doesn't tweak the layout (and calling plt.tight_layout() is currently even worse if I am correct)?

ah yeah that's a good point - ugh that's such annoying behavior from matplotlib :-)`

~~Winter~~ Layout manager is coming (#9082)! This should help to get rid of this kind of issues if I understood correctly.

Well actually it can be gotten rid of with #9164 which is a two liner instead of 20-file fix :-).

afvincent · 2017-10-17T00:21:56Z

examples/text_labels_and_annotations/custom_legends.py

+
+fig, ax = plt.subplots()
+lines = ax.plot(data)
+ax.legend(lines, loc=(1.05, .05), )


Is the “tuple notation” really mandatory, or could the trailing coma be removed?

afvincent · 2017-10-17T00:23:59Z

examples/text_labels_and_annotations/custom_legends.py

+
+fig, ax = plt.subplots()
+lines = ax.plot(data)
+ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'], loc=(1.05, .8),)


Same remark as before about the legend being possibly cut out.

afvincent · 2017-10-17T00:31:10Z

examples/text_labels_and_annotations/custom_legends.py

+legend_elements = {'Line': Line2D([0], [0], color='b', lw=4),
+                   'Scatter': Line2D([0], [0], marker='o', color='w',
+                                     markerfacecolor='g', markersize=15),
+                   'Color Patch': Patch(facecolor='orange', edgecolor='r')}


More a note for the future: if #8292 is some day merged in (I hope so!), it would be nice to remember updating this example to include one case or two.

afvincent · 2017-10-17T00:32:31Z

examples/text_labels_and_annotations/custom_legends.py

+# is a list of common ones.
+
+from matplotlib.patches import Patch
+from matplotlib.lines import Line2D


Maybe a dumb comment, but Line2D has already been loaded, hasn't it?

yeah here I was loading it again just so that it's easier for people to trace the imports in case they wanna do it themselves. Think it should be removed? I agree it's not standard PEP style

Well I do not know what exactly are our guidelines about this kind of things. I am not particularly pushing for removing it, I just wanted to be sure it had been done on purpose.

About PEP8, there are other imports that are not done at the top of the file anyway, so I guess that it does not really matter anyway ^^.

=> my call would be to keep it this way except if somebody more involved in the docs than I am complains ;)

I think @choldgraf might be the one most involved in the docs. 😛

@QuLogic I know ^^, but some other core devs are also quite involved about the docs and do care about what are the relevant guidelines that the docs should follow (hint: from my perspective, you are counted in that group :P)

afvincent · 2017-10-17T00:33:53Z

examples/text_labels_and_annotations/custom_legends.py

+                                     markerfacecolor='g', markersize=15),
+                   'Color Patch': Patch(facecolor='orange', edgecolor='r')}
+fig, ax = plt.subplots()
+ax.legend(legend_elements.values(), legend_elements.keys(), loc=(1.05, .8),)


Again, when I am trying this locally, the right part of the legend is cut out (by the figure right border).

afvincent · 2017-10-17T00:38:45Z

examples/text_labels_and_annotations/custom_legends.py

+
+fig, ax = plt.subplots()
+lines = ax.plot(data)
+ax.legend(lines, loc=(1.05, .05), )


I may be wrong but I think that one tries to use the leading zeros wherever possible: (1.05, .05) <- (1.05, 0.05)?

afvincent · 2017-10-17T00:40:18Z

examples/text_labels_and_annotations/custom_legends.py

+
+fig, ax = plt.subplots()
+lines = ax.plot(data)
+ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'], loc=(1.05, .8),)


Similarly to previous plot:

is the trailing coma mandatory?

(1.05, .8) <- (1.05, 0.8)?

afvincent · 2017-10-17T00:40:45Z

examples/text_labels_and_annotations/custom_legends.py

+                                     markerfacecolor='g', markersize=15),
+                   'Color Patch': Patch(facecolor='orange', edgecolor='r')}
+fig, ax = plt.subplots()
+ax.legend(legend_elements.values(), legend_elements.keys(), loc=(1.05, .8),)


Similarly to previous plot:

is the trailing coma mandatory?

(1.05, .8) <- (1.05, 0.8)?

afvincent · 2017-10-17T00:48:24Z

examples/text_labels_and_annotations/custom_legends.py

+                   'Scatter': Line2D([0], [0], marker='o', color='w',
+                                     markerfacecolor='g', markersize=15),
+                   'Color Patch': Patch(facecolor='orange', edgecolor='r')}
+fig, ax = plt.subplots()


Purely cosmetic remark if it was not done on purpose: in the example above, there isn't a blank line after the imports but there is one before instantiating the figure, while in the current example it is the opposite

afvincent · 2017-10-17T00:58:09Z

Well, I would say that the current legend tutorial may be quite scary for beginners: it quickly becomes quite advanced (at least from my point of view). This example keep things rather simple and should already cover most of the usual "custom legend" needs (apart maybe from the "multiple legends on the same Axes instance" one). Maybe it could point toward the “advanced” legend tutorial with an hyperlink at the end: most of the end-users (, who I know ^^,) start scrolling the example gallery before even trying to look for a proper tutorial.

choldgraf · 2017-10-17T01:05:26Z

For sure the tutorial should be linked from the example. I'll include that w/ the next round of edits when I address your comments @afvincent ... thanks for the feedback!

anntzer · 2017-10-17T01:26:28Z

examples/text_labels_and_annotations/custom_legends.py

+                                     markerfacecolor='g', markersize=15),
+                   'Color Patch': Patch(facecolor='orange', edgecolor='r')}
+fig, ax = plt.subplots()
+ax.legend(legend_elements.values(), legend_elements.keys(), loc=(1.05, .8),)


Note that the order of iteration over values()/keys() is not guaranteed (in fact it will change between iterations on Py3.4/3.5), so please use lists.

Also I think it is much better style to set the label on the artist itself:

legend_elements = [ Line2D(..., label="foo"), Patch(..., label="bar) ] ax.legend(legend_elements)

The comments apply throughout the tutorial of course.

Good point re: lists

for setting the label on the artist, IIRC doing that didn't automatically add labels when I called ax.legend but I could be wrong...

ya, when I do

legend_elements = [Line2D([0], [0], color='b', lw=4, label='Line'), Line2D([0], [0], marker='o', color='w', label='Scatter', markerfacecolor='g', markersize=15), Patch(facecolor='orange', edgecolor='r', label='Color Patch')] fig, ax = plt.subplots() ax.legend(legend_elements)

the result is

is that a bug?

Of course :/, this has to be plt.legend(handles=[...]), otherwise it thinks you're passing labels for some nonexistent artists. Stupid API, refactoring it is somewhere on my (thick) todo.

Well we could do it here: #9324 I agree its a backwards API.

I would suggest having this on a separate PR. Basically, if only one positional argument is passed and it's a list of artists, then consider it as handles instead of labels.

in the meantime, I'll just use plt

hmmm, I actually just tried it w/ plt and had the same behavior...

ah nvm, I see what you mean about handles=. That works for ax.legend as well actually, but just giving it as a positional argument works for neither.

Right - the positional argument is for labels believe it or not. i.e. ax.legend({'a', 'b', 'c'}) will label the first three artists it finds on ax` 'a', 'b', and 'c'. I guess artists are stored in the order they are drawn, but it seems like a strange choice to me. Once #9324 gets merged it'll be easy to check for a list of handles instead and make the call you were trying to make work.

choldgraf · 2017-10-17T03:21:09Z

ok, comments addressed in latest push.

afvincent

Mainly an outdated comment to remove. But otherwise, my previous comments have indeed been addressed :).

Do not forget to include a link toward the legend tutorial somewhere.

afvincent · 2017-10-17T03:36:28Z

examples/text_labels_and_annotations/custom_legends.py

+# Create the figure
+# If you use `ax.legend`, you'll also need to give the labels manually.
+fig, ax = plt.subplots()
+ax.legend(handles=legend_elements, loc=(0.5, 0.5))


I understand that one kind of gave up on the idea on using out-of-axes legend before the aforementioned @jklymak's PRs are merged, but then is there a peculiar reason not to simply use loc="center" instead of loc=(0.5, 0.5). Except of course if one really want to align the lower left of the legend with the center of the axes.

nope, I'm just being dumb :-)

afvincent · 2017-10-17T03:38:43Z

examples/text_labels_and_annotations/custom_legends.py

+                         label='Color Patch')]
+
+# Create the figure
+# If you use `ax.legend`, you'll also need to give the labels manually.


I think that the line above should not be here anymore, should it?

nope, will remove

anntzer · 2017-10-17T03:57:35Z

I had a quick skim through the legend related examples.

Tutorial:

Legend guide: http://matplotlib.org/tutorials/intermediate/legend_guide.html#sphx-glr-tutorials-intermediate-legend-guide-py
quite advanced, probably can use some rewriting but OK.

Examples:

Legend demo: http://matplotlib.org/gallery/text_labels_and_annotations/legend_demo.html#sphx-glr-gallery-text-labels-and-annotations-legend-demo-py
Looks somewhere between what this PR proposes and the legend guide. I think this PR is a nice piece of work but I would suggest trying not to spread the same information too thinly across many examples; perhaps the three "narrative" legend examples/tutorials could be merged into two?
What's new in 0.98.4 legend: http://matplotlib.org/gallery/pyplots/whats_new_98_4_legend.html#sphx-glr-gallery-pyplots-whats-new-98-4-legend-py
Can probably be deleted and the relevant features split across other examples.
Polar legend: http://matplotlib.org/gallery/pie_and_polar_charts/polar_legend.html#sphx-glr-gallery-pie-and-polar-charts-polar-legend-py
Can probably deleted, there's nothing special about legends in polar plots.
Simple legend 1 and 2: http://matplotlib.org/gallery/userdemo/simple_legend01.html#sphx-glr-gallery-userdemo-simple-legend01-py http://matplotlib.org/gallery/userdemo/simple_legend02.html#sphx-glr-gallery-userdemo-simple-legend02-py
Should probably be unified.
Legend picking: http://matplotlib.org/gallery/event_handling/legend_picking.html#sphx-glr-gallery-event-handling-legend-picking-py
Is really about event handling so can stand by itself.
Figure legend: http://matplotlib.org/gallery/text_labels_and_annotations/figlegend_demo.html#sphx-glr-gallery-text-labels-and-annotations-figlegend-demo-py
Should probably be rewritten to use a single legend for the whole figure...
Transparent, fancy legends: http://matplotlib.org/gallery/recipes/transparent_legends.html#sphx-glr-gallery-recipes-transparent-legends-py
Is basically the default now... probably doesn't need to exist by itself.
Scatter legend: http://matplotlib.org/gallery/lines_bars_and_markers/scatter_with_legend.html#sphx-glr-gallery-lines-bars-and-markers-scatter-with-legend-py
Heh, why not.
Legend using predefined labels: http://matplotlib.org/gallery/api/legend.html#sphx-glr-gallery-api-legend-py
Obviously I prefer the style demonstrated in it...

jklymak · 2017-10-17T04:54:28Z

Just to "me too" @anntzer's comment. It'd be great if this new tutorial could find a nice home in one of the other tutorials.

choldgraf · 2017-10-17T05:58:24Z

re: creating a new example vs. merging it with pre-existing examples, I'm of two minds on this one. On one hand, I agree that we don't want content to be spread too thinly. On the other hand, I think that appending this content to the currently-existing legend examples isn't a great idea, because

A. those examples are already long enough that they should be in the legend tutorial, not as examples,
and
B. the content in those examples is complex enough that many people will probably just not read it (e.g. the legend example involves subclassing HandlerLineCollection and has a really low SNR in general)

I think most people treat the examples gallery by quickly scanning the page of ctrl+fing for the thing that they want to do. To that extent, IMO, examples should be short and demonstrate a single kind of functionality or show off a single more complex viz, which is why I was keeping this as its separate file rather than glomming it on to something already there.

That said, I totally agree w/ you that we the way legends are handled in the docs should be improved, and I agree some should be removed. We should open an issue on streamlining the legend content using the list that you put together.

choldgraf · 2017-10-17T06:14:04Z

latest push addresses @afvincent 's comments

anntzer · 2017-10-17T06:23:30Z

We should open an issue on streamlining the legend content using the list that you put together.

you get to do it :-)

choldgraf · 2017-10-17T21:18:43Z

ok, #9458 created

@afvincent you're currently blocking on requested changes...anything else I need to do?

afvincent · 2017-10-17T21:33:02Z

LGTM.

A remaining comment, but non-blocking from my side, is the following: should one add a fixed seed to make the random traces reproducible (like @NelleV did a while ago for all the examples that were drawing random data), or are this kind of things now directly handled by SG?

choldgraf · 2017-10-17T21:55:50Z

good call, just added randomness fixer

choldgraf force-pushed the custom_legend branch from 29fdcae to 6f77d8e Compare October 17, 2017 00:05

afvincent reviewed Oct 17, 2017

View reviewed changes

afvincent added the Documentation label Oct 17, 2017

anntzer reviewed Oct 17, 2017

View reviewed changes

choldgraf force-pushed the custom_legend branch from 6f77d8e to c3bd838 Compare October 17, 2017 03:20

afvincent requested changes Oct 17, 2017

View reviewed changes

choldgraf force-pushed the custom_legend branch from c3bd838 to 1097a48 Compare October 17, 2017 06:13

choldgraf mentioned this pull request Oct 17, 2017

Refactor legend documentation #9458

Closed

choldgraf force-pushed the custom_legend branch 2 times, most recently from d991533 to 0c6fca9 Compare October 17, 2017 16:44

choldgraf force-pushed the custom_legend branch from 0c6fca9 to 058dda7 Compare October 17, 2017 21:29

afvincent approved these changes Oct 17, 2017

View reviewed changes

custom legends example

561180a

choldgraf force-pushed the custom_legend branch from 058dda7 to 561180a Compare October 17, 2017 21:41

NelleV merged commit 6657fe1 into matplotlib:master Oct 17, 2017

QuLogic added this to the v2.2 milestone Oct 17, 2017

QuLogic removed this from the needs sorting milestone Feb 12, 2018

QuLogic added this to the v2.2.0 milestone Feb 12, 2018

custom legends example #9451

custom legends example #9451

Conversation

choldgraf commented Oct 17, 2017

QuLogic commented Oct 17, 2017

choldgraf commented Oct 17, 2017

afvincent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuLogic Oct 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

afvincent commented Oct 17, 2017 • edited Loading

choldgraf commented Oct 17, 2017

anntzer Oct 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf Oct 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Oct 17, 2017

afvincent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer commented Oct 17, 2017

jklymak commented Oct 17, 2017

choldgraf commented Oct 17, 2017 • edited Loading

choldgraf commented Oct 17, 2017

anntzer commented Oct 17, 2017

choldgraf commented Oct 17, 2017

afvincent commented Oct 17, 2017

choldgraf commented Oct 17, 2017

QuLogic Oct 17, 2017 •

edited

Loading

afvincent commented Oct 17, 2017 •

edited

Loading

anntzer Oct 17, 2017 •

edited

Loading

choldgraf Oct 17, 2017 •

edited

Loading

choldgraf commented Oct 17, 2017 •

edited

Loading