{{ message }}
-
Notifications
You must be signed in to change notification settings - Fork 62
Expand file tree
/
Copy pathlegend_guide.html
More file actions
538 lines (506 loc) · 44.4 KB
/
Copy pathlegend_guide.html
File metadata and controls
538 lines (506 loc) · 44.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Legend guide — Matplotlib 1.3.0 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 1.3.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Matplotlib 1.3.0 documentation" href="../index.html" />
<link rel="up" title="User’s Guide" href="index.html" />
<link rel="next" title="Event handling and picking" href="event_handling.html" />
<link rel="prev" title="Tight Layout guide" href="tight_layout_guide.html" />
<link rel="canonical" href="https://matplotlib.org/2.0.2/users/legend_guide.html" />
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
</head>
<body>
<div id="unreleased-message"> You are reading an old version of the documentation (v1.3.0). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>
<!-- Piwik -->
<script type="text/javascript">
if ("matplotlib.sourceforge.net" == document.location.hostname ||
"matplotlib.sf.net" == document.location.hostname) {
var pkBaseURL = (("https:" == document.location.protocol) ? "https://apps.sourceforge.net/piwik/matplotlib/" : "http://apps.sourceforge.net/piwik/matplotlib/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
}
</script>
<script type="text/javascript">
if ("matplotlib.sourceforge.net" == document.location.hostname ||
"matplotlib.sf.net" == document.location.hostname) {
piwik_action_name = '';
piwik_idsite = 1;
piwik_url = pkBaseURL + "piwik.php";
piwik_log(piwik_action_name, piwik_idsite, piwik_url);
document.write(unescape('%3Cobject%3E%3Cnoscript%3E%3Cp%3E%3Cimg src="http://apps.sourceforge.net/piwik/matplotlib/piwik.php?idsite=1" alt="piwik"/%3E%3C/p%3E%3C/noscript%3E%3C/object%3E'));
}
</script>
<!-- End Piwik Tag -->
<link rel="shortcut icon" href="_static/favicon.ico">
<!-- The "Fork me on github" ribbon -->
<img style="float: right; margin-bottom: -40px; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" usemap="#ribbonmap"/>
<map name="ribbonmap">
<area shape="poly" coords="15,0,148,-1,148,135" href="https://github.com/matplotlib/matplotlib" title="Fork me on GitHub" />
</map>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="../index.html"><img src="../_static/logo2.png" border="0" alt="matplotlib"/></a>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="event_handling.html" title="Event handling and picking"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tight_layout_guide.html" title="Tight Layout guide"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../examples/index.html">examples</a>| </li>
<li><a href="../gallery.html">gallery</a>| </li>
<li><a href="../api/pyplot_summary.html">pyplot</a>| </li>
<li><a href="../contents.html">docs</a> »</li>
<li><a href="index.html" accesskey="U">User’s Guide</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Legend guide</a><ul>
<li><a class="reference internal" href="#what-to-be-displayed">What to be displayed</a><ul>
<li><a class="reference internal" href="#adjusting-the-order-of-legend-items">Adjusting the Order of Legend items</a></li>
<li><a class="reference internal" href="#using-proxy-artist">Using Proxy Artist</a></li>
</ul>
</li>
<li><a class="reference internal" href="#multicolumn-legend">Multicolumn Legend</a></li>
<li><a class="reference internal" href="#legend-location">Legend location</a></li>
<li><a class="reference internal" href="#multiple-legend">Multiple Legend</a></li>
<li><a class="reference internal" href="#legend-of-complex-plots">Legend of Complex Plots</a><ul>
<li><a class="reference internal" href="#artist-container">Artist Container</a></li>
<li><a class="reference internal" href="#legend-handler">Legend Handler</a></li>
<li><a class="reference internal" href="#implement-a-custom-handler">Implement a Custom Handler</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="tight_layout_guide.html"
title="previous chapter">Tight Layout guide</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="event_handling.html"
title="next chapter">Event handling and picking</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users/legend_guide.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="legend-guide">
<span id="plotting-guide-legend"></span><h1>Legend guide<a class="headerlink" href="#legend-guide" title="Permalink to this headline">¶</a></h1>
<p>Do not proceed unless you already have read <a class="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><tt class="xref py py-func docutils literal"><span class="pre">legend()</span></tt></a>
and <a class="reference internal" href="../api/legend_api.html#matplotlib.legend.Legend" title="matplotlib.legend.Legend"><tt class="xref py py-class docutils literal"><span class="pre">matplotlib.legend.Legend</span></tt></a>!</p>
<div class="section" id="what-to-be-displayed">
<h2>What to be displayed<a class="headerlink" href="#what-to-be-displayed" title="Permalink to this headline">¶</a></h2>
<p>The legend command has a following call signature:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">legend</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
<p>If len(args) is 2, the first argument should be a list of artist to be
labeled, and the second argument should a list of string labels. If
len(args) is 0, it automatically generate the legend from label
properties of the child artists by calling
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_legend_handles_labels" title="matplotlib.axes.Axes.get_legend_handles_labels"><tt class="xref py py-meth docutils literal"><span class="pre">get_legend_handles_labels()</span></tt></a> method.
For example, <em>ax.legend()</em> is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">handles</span><span class="p">,</span> <span class="n">labels</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">get_legend_handles_labels</span><span class="p">()</span>
<span class="n">ax</span><span class="o">.</span><span class="n">legend</span><span class="p">(</span><span class="n">handles</span><span class="p">,</span> <span class="n">labels</span><span class="p">)</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_legend_handles_labels" title="matplotlib.axes.Axes.get_legend_handles_labels"><tt class="xref py py-meth docutils literal"><span class="pre">get_legend_handles_labels()</span></tt></a> method
returns a tuple of two lists, i.e., list of artists and list of labels
(python string). However, it does not return all of its child
artists. It returns artists that are currently supported by matplotlib.</p>
<p>For matplotlib v1.0 and earlier, the supported artists are as follows.</p>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><tt class="xref py py-class docutils literal"><span class="pre">Line2D</span></tt></a></li>
<li><a class="reference internal" href="../api/artist_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><tt class="xref py py-class docutils literal"><span class="pre">Patch</span></tt></a></li>
<li><a class="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><tt class="xref py py-class docutils literal"><span class="pre">LineCollection</span></tt></a></li>
<li><a class="reference internal" href="../api/collections_api.html#matplotlib.collections.RegularPolyCollection" title="matplotlib.collections.RegularPolyCollection"><tt class="xref py py-class docutils literal"><span class="pre">RegularPolyCollection</span></tt></a></li>
<li><a class="reference internal" href="../api/collections_api.html#matplotlib.collections.CircleCollection" title="matplotlib.collections.CircleCollection"><tt class="xref py py-class docutils literal"><span class="pre">CircleCollection</span></tt></a></li>
</ul>
</div></blockquote>
<p>And, <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_legend_handles_labels" title="matplotlib.axes.Axes.get_legend_handles_labels"><tt class="xref py py-meth docutils literal"><span class="pre">get_legend_handles_labels()</span></tt></a> returns
all artists in <em>ax.lines</em>, <em>ax.patches</em> and
artists in <em>ax.collection</em> which are instance of
<a class="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><tt class="xref py py-class docutils literal"><span class="pre">LineCollection</span></tt></a> or
<a class="reference internal" href="../api/collections_api.html#matplotlib.collections.RegularPolyCollection" title="matplotlib.collections.RegularPolyCollection"><tt class="xref py py-class docutils literal"><span class="pre">RegularPolyCollection</span></tt></a>. The label
attributes (returned by get_label() method) of collected artists are
used as text labels. If label attribute is empty string or starts with
“_”, those artists will be ignored.</p>
<p>Therefore, plots drawn by some <em>pyplot</em> commands are not supported by
legend. For example, <a class="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.fill_between" title="matplotlib.pyplot.fill_between"><tt class="xref py py-func docutils literal"><span class="pre">fill_between()</span></tt></a> creates
<a class="reference internal" href="../api/collections_api.html#matplotlib.collections.PolyCollection" title="matplotlib.collections.PolyCollection"><tt class="xref py py-class docutils literal"><span class="pre">PolyCollection</span></tt></a> that is not
supported. Also support is limited for some commands that create
multiple artists. For example, <a class="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.errorbar" title="matplotlib.pyplot.errorbar"><tt class="xref py py-func docutils literal"><span class="pre">errorbar()</span></tt></a>
creates multiples <a class="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><tt class="xref py py-class docutils literal"><span class="pre">Line2D</span></tt></a> instances.</p>
<p>Unfortunately, there is no easy workaround when you need legend for an
artist not supported by matplotlib (You may use one of the supported
artist as a proxy. See below)</p>
<p>In newer version of matplotlib (v1.1 and later), the matplotlib
internals are revised to support</p>
<blockquote>
<div><ul class="simple">
<li>complex plots that creates multiple artists (e.g., bar, errorbar, etc)</li>
<li>custom legend handles</li>
</ul>
</div></blockquote>
<p>See below for details of new functionality.</p>
<div class="section" id="adjusting-the-order-of-legend-items">
<h3>Adjusting the Order of Legend items<a class="headerlink" href="#adjusting-the-order-of-legend-items" title="Permalink to this headline">¶</a></h3>
<p>When you want to customize the list of artists to be displayed in the
legend, or their order of appearance. There are a two options. First,
you can keep lists of artists and labels, and explicitly use these for
the first two argument of the legend call.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">p1</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="n">p2</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])</span>
<span class="n">p3</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">])</span>
<span class="n">legend</span><span class="p">([</span><span class="n">p2</span><span class="p">,</span> <span class="n">p1</span><span class="p">],</span> <span class="p">[</span><span class="s">"line 2"</span><span class="p">,</span> <span class="s">"line 1"</span><span class="p">])</span>
</pre></div>
</div>
<p>Or you may use <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_legend_handles_labels" title="matplotlib.axes.Axes.get_legend_handles_labels"><tt class="xref py py-meth docutils literal"><span class="pre">get_legend_handles_labels()</span></tt></a>
to retrieve list of artist and labels and manipulate them before
feeding them to legend call.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">ax</span> <span class="o">=</span> <span class="n">subplot</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="n">p1</span><span class="p">,</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"line 1"</span><span class="p">)</span>
<span class="n">p2</span><span class="p">,</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"line 2"</span><span class="p">)</span>
<span class="n">p3</span><span class="p">,</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"line 3"</span><span class="p">)</span>
<span class="n">handles</span><span class="p">,</span> <span class="n">labels</span> <span class="o">=</span> <span class="n">ax</span><span class="o">.</span><span class="n">get_legend_handles_labels</span><span class="p">()</span>
<span class="c"># reverse the order</span>
<span class="n">ax</span><span class="o">.</span><span class="n">legend</span><span class="p">(</span><span class="n">handles</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">],</span> <span class="n">labels</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span>
<span class="c"># or sort them by labels</span>
<span class="kn">import</span> <span class="nn">operator</span>
<span class="n">hl</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="n">handles</span><span class="p">,</span> <span class="n">labels</span><span class="p">),</span>
<span class="n">key</span><span class="o">=</span><span class="n">operator</span><span class="o">.</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
<span class="n">handles2</span><span class="p">,</span> <span class="n">labels2</span> <span class="o">=</span> <span class="nb">zip</span><span class="p">(</span><span class="o">*</span><span class="n">hl</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">legend</span><span class="p">(</span><span class="n">handles2</span><span class="p">,</span> <span class="n">labels2</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="using-proxy-artist">
<h3>Using Proxy Artist<a class="headerlink" href="#using-proxy-artist" title="Permalink to this headline">¶</a></h3>
<p>When you want to display legend for an artist not supported by
matplotlib, you may use another artist as a proxy. For
example, you may create a proxy artist without adding it to the axes
(so the proxy artist will not be drawn in the main axes) and feed it
to the legend function.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">p</span> <span class="o">=</span> <span class="n">Rectangle</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">fc</span><span class="o">=</span><span class="s">"r"</span><span class="p">)</span>
<span class="n">legend</span><span class="p">([</span><span class="n">p</span><span class="p">],</span> <span class="p">[</span><span class="s">"Red Rectangle"</span><span class="p">])</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="multicolumn-legend">
<h2>Multicolumn Legend<a class="headerlink" href="#multicolumn-legend" title="Permalink to this headline">¶</a></h2>
<p>By specifying the keyword argument <em>ncol</em>, you can have a multi-column
legend. Also, mode=”expand” horizontally expand the legend to fill the
axes area. See <a class="reference external" href="http://matplotlib.org/examples/pylab_examples/legend_demo3.html">legend_demo3.py</a>
for example.</p>
</div>
<div class="section" id="legend-location">
<h2>Legend location<a class="headerlink" href="#legend-location" title="Permalink to this headline">¶</a></h2>
<p>The location of the legend can be specified by the keyword argument
<em>loc</em>, either by string or a integer number.</p>
<table border="1" class="docutils">
<colgroup>
<col width="68%" />
<col width="32%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">String</th>
<th class="head">Number</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>upper right</td>
<td>1</td>
</tr>
<tr class="row-odd"><td>upper left</td>
<td>2</td>
</tr>
<tr class="row-even"><td>lower left</td>
<td>3</td>
</tr>
<tr class="row-odd"><td>lower right</td>
<td>4</td>
</tr>
<tr class="row-even"><td>right</td>
<td>5</td>
</tr>
<tr class="row-odd"><td>center left</td>
<td>6</td>
</tr>
<tr class="row-even"><td>center right</td>
<td>7</td>
</tr>
<tr class="row-odd"><td>lower center</td>
<td>8</td>
</tr>
<tr class="row-even"><td>upper center</td>
<td>9</td>
</tr>
<tr class="row-odd"><td>center</td>
<td>10</td>
</tr>
</tbody>
</table>
<p>By default, the legend will anchor to the bbox of the axes
(for legend) or the bbox of the figure (figlegend). You can specify
your own bbox using <em>bbox_to_anchor</em> argument. <em>bbox_to_anchor</em> can be an
instance of <a class="reference internal" href="../devel/transformations.html#matplotlib.transforms.BboxBase" title="matplotlib.transforms.BboxBase"><tt class="xref py py-class docutils literal"><span class="pre">BboxBase</span></tt></a>, a tuple of 4
floats (x, y, width, height of the bbox), or a tuple of 2 floats (x, y
with width=height=0). Unless <em>bbox_transform</em> argument is given, the
coordinates (even for the bbox instance) are considered as normalized
axes coordinates.</p>
<p>For example, if you want your axes legend located at the figure corner
(instead of the axes corner):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">l</span> <span class="o">=</span> <span class="n">legend</span><span class="p">(</span><span class="n">bbox_to_anchor</span><span class="o">=</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="n">bbox_transform</span><span class="o">=</span><span class="n">gcf</span><span class="p">()</span><span class="o">.</span><span class="n">transFigure</span><span class="p">)</span>
</pre></div>
</div>
<p>Also, you can place above or outer right-hand side of the axes,</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">import</span> <span class="o">*</span>
<span class="n">subplot</span><span class="p">(</span><span class="mi">211</span><span class="p">)</span>
<span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test1"</span><span class="p">)</span>
<span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test2"</span><span class="p">)</span>
<span class="n">legend</span><span class="p">(</span><span class="n">bbox_to_anchor</span><span class="o">=</span><span class="p">(</span><span class="mf">0.</span><span class="p">,</span> <span class="mf">1.02</span><span class="p">,</span> <span class="mf">1.</span><span class="p">,</span> <span class="o">.</span><span class="mi">102</span><span class="p">),</span> <span class="n">loc</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span>
<span class="n">ncol</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s">"expand"</span><span class="p">,</span> <span class="n">borderaxespad</span><span class="o">=</span><span class="mf">0.</span><span class="p">)</span>
<span class="n">subplot</span><span class="p">(</span><span class="mi">223</span><span class="p">)</span>
<span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test1"</span><span class="p">)</span>
<span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test2"</span><span class="p">)</span>
<span class="n">legend</span><span class="p">(</span><span class="n">bbox_to_anchor</span><span class="o">=</span><span class="p">(</span><span class="mf">1.05</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="n">loc</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">borderaxespad</span><span class="o">=</span><span class="mf">0.</span><span class="p">)</span>
<span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/plotting/examples/simple_legend01.py">Source code</a>, <a class="reference external" href="../users/plotting/examples/simple_legend01.png">png</a>, <a class="reference external" href="../users/plotting/examples/simple_legend01.hires.png">hires.png</a>, <a class="reference external" href="../users/plotting/examples/simple_legend01.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/simple_legend01.png" src="../_images/simple_legend01.png" />
</div>
</div>
<div class="section" id="multiple-legend">
<h2>Multiple Legend<a class="headerlink" href="#multiple-legend" title="Permalink to this headline">¶</a></h2>
<p>Sometime, you want to split the legend into multiple ones.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">p1</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="n">p2</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])</span>
<span class="n">legend</span><span class="p">([</span><span class="n">p1</span><span class="p">],</span> <span class="p">[</span><span class="s">"Test1"</span><span class="p">],</span> <span class="n">loc</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">legend</span><span class="p">([</span><span class="n">p2</span><span class="p">],</span> <span class="p">[</span><span class="s">"Test2"</span><span class="p">],</span> <span class="n">loc</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
</pre></div>
</div>
<p>However, the above code only shows the second legend. When the legend
command is called, a new legend instance is created and old ones are
removed from the axes. Thus, you need to manually add the removed
legend.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">import</span> <span class="o">*</span>
<span class="n">p1</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test1"</span><span class="p">)</span>
<span class="n">p2</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="n">label</span><span class="o">=</span><span class="s">"test2"</span><span class="p">)</span>
<span class="n">l1</span> <span class="o">=</span> <span class="n">legend</span><span class="p">([</span><span class="n">p1</span><span class="p">],</span> <span class="p">[</span><span class="s">"Label 1"</span><span class="p">],</span> <span class="n">loc</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">l2</span> <span class="o">=</span> <span class="n">legend</span><span class="p">([</span><span class="n">p2</span><span class="p">],</span> <span class="p">[</span><span class="s">"Label 2"</span><span class="p">],</span> <span class="n">loc</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="c"># this removes l1 from the axes.</span>
<span class="n">gca</span><span class="p">()</span><span class="o">.</span><span class="n">add_artist</span><span class="p">(</span><span class="n">l1</span><span class="p">)</span> <span class="c"># add l1 as a separate artist to the axes</span>
<span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/plotting/examples/simple_legend02.py">Source code</a>, <a class="reference external" href="../users/plotting/examples/simple_legend02.png">png</a>, <a class="reference external" href="../users/plotting/examples/simple_legend02.hires.png">hires.png</a>, <a class="reference external" href="../users/plotting/examples/simple_legend02.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/simple_legend02.png" src="../_images/simple_legend02.png" />
</div>
</div>
<div class="section" id="legend-of-complex-plots">
<span id="legend-complex-plots"></span><h2>Legend of Complex Plots<a class="headerlink" href="#legend-of-complex-plots" title="Permalink to this headline">¶</a></h2>
<p>In matplotlib v1.1 and later, the legend is
improved to support more plot commands and ease the customization.</p>
<div class="section" id="artist-container">
<h3>Artist Container<a class="headerlink" href="#artist-container" title="Permalink to this headline">¶</a></h3>
<p>The Artist Container is simple class (derived from tuple) that
contains multiple artists. This is introduced primarily to support
legends for complex plot commands that create multiple artists.</p>
<p>Axes instances now have a “containers” attribute (which is a list, and
this is only intended to be used for generating a legend). The items
in this attribute are also returned by
<a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.get_legend_handles_labels" title="matplotlib.axes.Axes.get_legend_handles_labels"><tt class="xref py py-meth docutils literal"><span class="pre">get_legend_handles_labels()</span></tt></a>.</p>
<p>For example, “bar” command creates a series of Rectangle
patches. Previously, it returned a list of these patches. With the
current change, it creates a container object of these rectangle
patches (and these patches are added to Axes.patches attribute as
before) and return it instead. As the container class is derived from
a tuple, it should be backward-compatible. Furthermore, the container
object is added to the Axes.containers attributes so that legend
command can properly create a legend for the bar. Thus, you may do</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">b1</span> <span class="o">=</span> <span class="n">bar</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mf">0.2</span><span class="p">,</span> <span class="mf">0.3</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">],</span> <span class="n">width</span><span class="o">=</span><span class="mf">0.4</span><span class="p">,</span>
<span class="n">label</span><span class="o">=</span><span class="s">"Bar 1"</span><span class="p">,</span> <span class="n">align</span><span class="o">=</span><span class="s">"center"</span><span class="p">)</span>
<span class="n">legend</span><span class="p">()</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">b1</span> <span class="o">=</span> <span class="n">bar</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mf">0.2</span><span class="p">,</span> <span class="mf">0.3</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">],</span> <span class="n">width</span><span class="o">=</span><span class="mf">0.4</span><span class="p">,</span> <span class="n">align</span><span class="o">=</span><span class="s">"center"</span><span class="p">)</span>
<span class="n">legend</span><span class="p">([</span><span class="n">b1</span><span class="p">],</span> <span class="p">[</span><span class="s">"Bar 1"</span><span class="p">])</span>
</pre></div>
</div>
<p>At this time of writing, however, only “bar”, “errorbar”, and “stem” are
supported (hopefully the list will increase). Here is an example.</p>
<p>(<a class="reference external" href="../mpl_examples/pylab_examples/legend_demo4.py">Source code</a>, <a class="reference external" href="../mpl_examples/pylab_examples/legend_demo4.png">png</a>, <a class="reference external" href="../mpl_examples/pylab_examples/legend_demo4.hires.png">hires.png</a>, <a class="reference external" href="../mpl_examples/pylab_examples/legend_demo4.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/legend_demo41.png" src="../_images/legend_demo41.png" />
</div>
</div>
<div class="section" id="legend-handler">
<h3>Legend Handler<a class="headerlink" href="#legend-handler" title="Permalink to this headline">¶</a></h3>
<p>One of the changes is that drawing of legend handles has been delegated to
legend handlers. For example, <a class="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><tt class="xref py py-class docutils literal"><span class="pre">Line2D</span></tt></a>
instances are handled by
<tt class="xref py py-class docutils literal"><span class="pre">HandlerLine2D</span></tt>. The mapping
between the artists and their corresponding handlers are defined in a
handler_map of the legend. The handler_map is a dictionary of
key-handler pair, where key can be an artist instance or its
class. And the handler is a Handler instance.</p>
<p>Let’s consider the following sample code,</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">legend</span><span class="p">([</span><span class="n">p_1</span><span class="p">,</span> <span class="n">p_2</span><span class="p">,</span><span class="o">...</span><span class="p">,</span> <span class="n">p_i</span><span class="p">,</span> <span class="o">...</span><span class="p">],</span> <span class="p">[</span><span class="s">"Test 1"</span><span class="p">,</span> <span class="s">"Test 2"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="s">"Test i"</span><span class="p">,</span><span class="o">...</span><span class="p">])</span>
</pre></div>
</div>
<p>For each <em>p_i</em>, matplotlib</p>
<blockquote>
<div><ol class="arabic simple">
<li>check if <em>p_i</em> is in the handler_map</li>
<li>if not, iterate over type(p_i).mro() until a matching key is found
in the handler_map</li>
</ol>
</div></blockquote>
<p>Unless specified, the default handler_map is used. Below is a partial
list of key-handler pairs included in the default handler map.</p>
<blockquote>
<div><ul class="simple">
<li>Line2D : legend_handler.HandlerLine2D()</li>
<li>Patch : legend_handler.HandlerPatch()</li>
<li>LineCollection : legend_handler.HandlerLineCollection()</li>
<li>...</li>
</ul>
</div></blockquote>
<p>The legend() command takes an optional argument of “handler_map”. When
provided, the default handler map will be updated (using dict.update
method) with the provided one.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">p1</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="s">"ro"</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s">"test1"</span><span class="p">)</span>
<span class="n">p2</span><span class="p">,</span> <span class="o">=</span> <span class="n">plot</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="s">"b+"</span><span class="p">,</span> <span class="n">ms</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s">"test2"</span><span class="p">)</span>
<span class="n">my_handler</span> <span class="o">=</span> <span class="n">HandlerLine2D</span><span class="p">(</span><span class="n">numpoints</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">legend</span><span class="p">(</span><span class="n">handler_map</span><span class="o">=</span><span class="p">{</span><span class="n">Line2D</span><span class="p">:</span><span class="n">my_handler</span><span class="p">})</span>
</pre></div>
</div>
<p>The above example will use <em>my_handler</em> for any Line2D
instances (p1 and p2).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">legend</span><span class="p">(</span><span class="n">handler_map</span><span class="o">=</span><span class="p">{</span><span class="n">p1</span><span class="p">:</span><span class="n">HandlerLine2D</span><span class="p">(</span><span class="n">numpoints</span><span class="o">=</span><span class="mi">1</span><span class="p">)})</span>
</pre></div>
</div>
<p>In the above example, only <em>p1</em> will be handled by <em>my_handler</em>, while
others will be handled by default handlers.</p>
<p>The current default handler_map has handlers for errorbar and bar
plots. Also, it includes an entry for <tt class="xref py py-obj docutils literal"><span class="pre">tuple</span></tt> which is mapped to
<tt class="xref py py-obj docutils literal"><span class="pre">HandlerTuple</span></tt>. It simply plots over all the handles for items in the
given tuple. For example,</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">z</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="n">p1a</span><span class="p">,</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">z</span><span class="p">,</span> <span class="s">"ro"</span><span class="p">,</span> <span class="n">ms</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mfc</span><span class="o">=</span><span class="s">"r"</span><span class="p">,</span> <span class="n">mew</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">mec</span><span class="o">=</span><span class="s">"r"</span><span class="p">)</span> <span class="c"># red filled circle</span>
<span class="n">p1b</span><span class="p">,</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">z</span><span class="p">[:</span><span class="mi">5</span><span class="p">],</span> <span class="s">"w+"</span><span class="p">,</span> <span class="n">ms</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">mec</span><span class="o">=</span><span class="s">"w"</span><span class="p">,</span> <span class="n">mew</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span> <span class="c"># white cross</span>
<span class="n">plt</span><span class="o">.</span><span class="n">legend</span><span class="p">([</span><span class="n">p1a</span><span class="p">,</span> <span class="p">(</span><span class="n">p1a</span><span class="p">,</span> <span class="n">p1b</span><span class="p">)],</span> <span class="p">[</span><span class="s">"Attr A"</span><span class="p">,</span> <span class="s">"Attr A+B"</span><span class="p">])</span>
</pre></div>
</div>
<p>(<a class="reference external" href="../users/legend_guide-1.py">Source code</a>, <a class="reference external" href="../users/legend_guide-1.png">png</a>, <a class="reference external" href="../users/legend_guide-1.hires.png">hires.png</a>, <a class="reference external" href="../users/legend_guide-1.pdf">pdf</a>)</p>
<div class="figure">
<img alt="../_images/legend_guide-1.png" src="../_images/legend_guide-1.png" />
</div>
</div>
<div class="section" id="implement-a-custom-handler">
<h3>Implement a Custom Handler<a class="headerlink" href="#implement-a-custom-handler" title="Permalink to this headline">¶</a></h3>
<p>Handler can be any callable object with following signature.</p>
<div class="highlight-python"><pre>def __call__(self, legend, orig_handle,
fontsize,
handlebox):</pre>
</div>
<p>Where <em>legend</em> is the legend itself, <em>orig_handle</em> is the original
plot (<em>p_i</em> in the above example), <em>fontsize</em> is the fontsize in
pixels, and <em>handlebox</em> is a OffsetBox instance. Within the call, you
create relevant artists (using relevant properties from the <em>legend</em>
and/or <em>orig_handle</em>) and add them into the handlebox. The artists
needs to be scaled according to the fontsize (note that the size is in
pixel, i.e., this is dpi-scaled value). See <tt class="xref py py-mod docutils literal"><span class="pre">legend_handler</span></tt>
for more details.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="event_handling.html" title="Event handling and picking"
>next</a> |</li>
<li class="right" >
<a href="tight_layout_guide.html" title="Tight Layout guide"
>previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../examples/index.html">examples</a>| </li>
<li><a href="../gallery.html">gallery</a>| </li>
<li><a href="../api/pyplot_summary.html">pyplot</a>| </li>
<li><a href="../contents.html">docs</a> »</li>
<li><a href="index.html" >User’s Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the matplotlib development team; 2012 - 2013 The matplotlib development team.
Last updated on Jul 31, 2013.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div>
</body>
</html>
You can’t perform that action at this time.