matplotlib.github.com/1.2.1/users/legend_guide.html at main · matplotlib/matplotlib.github.com

History

542 lines (510 loc) · 44.6 KB

Raw

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

539

540

541

542

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Legend guide — Matplotlib 1.2.1 documentation</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '1.2.1',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true

};

</script>

title="Search within Matplotlib 1.2.1 documentation"

href="../_static/opensearch.xml"/>

</head>

<body>

<div id="unreleased-message"> You are reading an old version of the documentation (v1.2.1). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>

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>

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>

</map>

</div>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<a href="event_handling.html" title="Event handling and picking"

accesskey="N">next</a> |</li>

<a href="tight_layout_guide.html" title="Tight Layout guide"

accesskey="P">previous</a> |</li>

<li><a href="http://www.matplotlib.org/downloads.html">downloads</a>| </li>

<li><a href="../search.html">search</a>| </li>

<li><a href="../examples/index.html">examples</a>| </li>

<li><a href="../gallery.html">gallery</a>| </li>

<li><a href="../citing.html">citation</a>| </li>

<li><a href="index.html" accesskey="U">User’s Guide</a> »</li>

</ul>

</div>

<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>

<a href="tight_layout_guide.html"

title="previous chapter">Tight Layout guide</a>

<h4>Next topic</h4>

<a href="event_handling.html"

title="next chapter">Event handling and picking</a>

<li><a href="../_sources/users/legend_guide.txt"

rel="nofollow">Show Source</a></li>

</ul>

<h3>Quick search</h3>

</form>

Enter search terms or a module, class or function name.

</div>

</div>

<h1>Legend guide<a class="headerlink" href="#legend-guide" title="Permalink to this headline">¶</a></h1>

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">legend()</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">matplotlib.legend.Legend</tt></a>!

<h2>What to be displayed<a class="headerlink" href="#what-to-be-displayed" title="Permalink to this headline">¶</a></h2>

The legend command has a following call signature:

<div class="highlight-python"><div class="highlight"><pre>legend(*args, **kwargs)

</pre></div>

</div>

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">get_legend_handles_labels()</tt></a> method.

For example, ax.legend() is equivalent to:

<div class="highlight-python"><div class="highlight"><pre>handles, labels = ax.get_legend_handles_labels()

ax.legend(handles, labels)

</pre></div>

</div>

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">get_legend_handles_labels()</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.

For matplotlib v1.0 and earlier, the supported artists are as follows.

<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">Patch</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">LineCollection</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">RegularPolyCollection</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">CircleCollection</tt></a></li>

</ul>

</div></blockquote>

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">get_legend_handles_labels()</tt></a> returns

all artists in ax.lines, ax.patches and

artists in ax.collection 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">LineCollection</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">RegularPolyCollection</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.

Therefore, plots drawn by some pyplot 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">fill_between()</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">PolyCollection</tt></a> that is not

supported. Also support is limted for some commands that creat

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">errorbar()</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">Line2D</tt></a> instances.

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)

In newer version of matplotlib (v1.1 and later), the matplotlib

internals are revised to support

<li>complex plots that creates multiple artists (e.g., bar, errorbar, etc)</li>

<li>custom legend handles</li>

</ul>

</div></blockquote>

See below for details of new functionality.

<h3>Adjusting the Order of Legend items<a class="headerlink" href="#adjusting-the-order-of-legend-items" title="Permalink to this headline">¶</a></h3>

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.:

<div class="highlight-python"><div class="highlight"><pre>p1, = plot([1,2,3])

p2, = plot([3,2,1])

p3, = plot([2,3,1])

legend([p2, p1], ["line 2", "line 1"])

</pre></div>

</div>

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">get_legend_handles_labels()</tt></a>

to retrieve list of artist and labels and manipulate them before

feeding them to legend call.:

<div class="highlight-python"><div class="highlight"><pre>ax = subplot(1,1,1)

p1, = ax.plot([1,2,3], label="line 1")

p2, = ax.plot([3,2,1], label="line 2")

p3, = ax.plot([2,3,1], label="line 3")

handles, labels = ax.get_legend_handles_labels()

# reverse the order

ax.legend(handles[::-1], labels[::-1])

# or sort them by labels

import operator

hl = sorted(zip(handles, labels),

key=operator.itemgetter(1))

handles2, labels2 = zip(*hl)

ax.legend(handles2, labels2)

</pre></div>

</div>

<h3>Using Proxy Artist<a class="headerlink" href="#using-proxy-artist" title="Permalink to this headline">¶</a></h3>

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.:

<div class="highlight-python"><div class="highlight"><pre>p = Rectangle((0, 0), 1, 1, fc="r")

legend([p], ["Red Rectangle"])

</pre></div>

</div>

<h2>Multicolumn Legend<a class="headerlink" href="#multicolumn-legend" title="Permalink to this headline">¶</a></h2>

By specifying the keyword argument ncol, 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.

</div>

<h2>Legend location<a class="headerlink" href="#legend-location" title="Permalink to this headline">¶</a></h2>

The location of the legend can be specified by the keyword argument

loc, either by string or a integer number.

</colgroup>

<tr class="row-odd"><th class="head">String</th>

<th class="head">Number</th>

</tr>

</thead>

<tr class="row-even"><td>upper right</td>

</tr>

<tr class="row-odd"><td>upper left</td>

</tr>

<tr class="row-even"><td>lower left</td>

</tr>

<tr class="row-odd"><td>lower right</td>

</tr>

<tr class="row-even"><td>right</td>

</tr>

<tr class="row-odd"><td>center left</td>

</tr>

<tr class="row-even"><td>center right</td>

</tr>

<tr class="row-odd"><td>lower center</td>

</tr>

<tr class="row-even"><td>upper center</td>

</tr>

<tr class="row-odd"><td>center</td>

</tr>

</tbody>

</table>

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 bbox_to_anchor argument. bbox_to_anchor 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">BboxBase</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 bbox_transform argument is given, the

coordinates (even for the bbox instance) are considered as normalized

axes coordinates.

For example, if you want your axes legend located at the figure corner

(instead of the axes corner):

<div class="highlight-python"><div class="highlight"><pre>l = legend(bbox_to_anchor=(0, 0, 1, 1), bbox_transform=gcf().transFigure)

</pre></div>

</div>

Also, you can place above or outer right-hand side of the axes,

<div class="highlight-python"><div class="highlight"><pre>from matplotlib.pyplot import *

subplot(211)

plot([1,2,3], label="test1")

plot([3,2,1], label="test2")

legend(bbox_to_anchor=(0., 1.02, 1., .102), loc=3,

ncol=2, mode="expand", borderaxespad=0.)

subplot(223)

legend(bbox_to_anchor=(1.05, 1), loc=2, borderaxespad=0.)

show()

</pre></div>

</div>

(<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>)

</div>

<h2>Multiple Legend<a class="headerlink" href="#multiple-legend" title="Permalink to this headline">¶</a></h2>

Sometime, you want to split the legend into multiple ones.:

legend([p1], ["Test1"], loc=1)

legend([p2], ["Test2"], loc=4)

</pre></div>

</div>

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.

<div class="highlight-python"><div class="highlight"><pre>from matplotlib.pyplot import *

p1, = plot([1,2,3], label="test1")

l1 = legend([p1], ["Label 1"], loc=1)

l2 = legend([p2], ["Label 2"], loc=4) # this removes l1 from the axes.

gca().add_artist(l1) # add l1 as a separate artist to the axes

show()

</pre></div>

</div>

(<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>)

</div>

<h2>Legend of Complex Plots<a class="headerlink" href="#legend-of-complex-plots" title="Permalink to this headline">¶</a></h2>

In matplotlib v1.1 and later, the legend is

improved to support more plot commands and ease the customization.

<h3>Artist Container<a class="headerlink" href="#artist-container" title="Permalink to this headline">¶</a></h3>

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.

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

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

<div class="highlight-python"><div class="highlight"><pre>b1 = bar([0, 1, 2], [0.2, 0.3, 0.1], width=0.4,

label="Bar 1", align="center")

legend()

</pre></div>

</div>

or

legend([b1], ["Bar 1"])

</pre></div>

</div>

At this time of writing, however, only “bar”, “errorbar”, and “stem” are

supported (hopefully the list will increase). Here is an example.

(<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>)

</div>

<h3>Legend Handler<a class="headerlink" href="#legend-handler" title="Permalink to this headline">¶</a></h3>

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">Line2D</tt></a>

instances are handled by

<tt class="xref py py-class docutils literal">HandlerLine2D</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.

Let’s consider the following sample code,

<div class="highlight-python"><div class="highlight"><pre>legend([p_1, p_2,..., p_i, ...], ["Test 1", "Test 2", ..., "Test i",...])

</pre></div>

</div>

For each p_i, matplotlib

<li>check if p_i 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>

Unless specified, the defaul handler_map is used. Below is a partial

list of key-handler pairs included in the default handler map.

<li>Line2D : legend_handler.HandlerLine2D()</li>

<li>Patch : legend_handler.HandlerPatch()</li>

<li>LineCollection : legend_handler.HandlerLineCollection()</li>

</ul>

</div></blockquote>

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.

<div class="highlight-python"><div class="highlight"><pre>p1, = plot(x, "ro", label="test1")

p2, = plot(y, "b+", ms=10, label="test2")

my_handler = HandlerLine2D(numpoints=1)

legend(handler_map={Line2D:my_handler})

</pre></div>

</div>

The above example will use my_handler for any Line2D

instances (p1 and p2).

<div class="highlight-python"><div class="highlight"><pre>legend(handler_map={p1:HandlerLine2D(numpoints=1)})

</pre></div>

</div>

In the above example, only p1 will be handled by my_handler, while

others will be handled by default handlers.

The curent default handler_map has handlers for errorbar and bar

plots. Also, it includes an entry for <tt class="xref py py-obj docutils literal">tuple</tt> which is mapped to

<tt class="xref py py-obj docutils literal">HandlerTuple</tt>. It simply plots over all the handles for items in the

given tuple. For example,

<div class="highlight-python"><div class="highlight"><pre>z = np.random.randn(10)

p1a, = plt.plot(z, "ro", ms=10, mfc="r", mew=2, mec="r") # red filled circle

p1b, = plt.plot(z[:5], "w+", ms=10, mec="w", mew=2) # white cross

plt.legend([p1a, (p1a, p1b)], ["Attr A", "Attr A+B"])

</pre></div>

</div>

(<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>)

</div>

<h3>Implement a Custom Handler<a class="headerlink" href="#implement-a-custom-handler" title="Permalink to this headline">¶</a></h3>

Handler can be any callable object with following signature.

<div class="highlight-python"><pre>def __call__(self, legend, orig_handle,

fontsize,

handlebox):</pre>

</div>

Where legend is the legend itself, orig_handle is the original

plot (p_i in the above example), fontsize is the fontsize in

pixles, and handlebox is a OffsetBox instance. Within the call, you

create relevant artists (using relevant properties from the legend

and/or orig_handle) 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">legend_handler</tt>

for more details.

</div>

</div>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

>index</a></li>

<a href="../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<a href="event_handling.html" title="Event handling and picking"

>next</a> |</li>

<a href="tight_layout_guide.html" title="Tight Layout guide"

>previous</a> |</li>

<li><a href="http://www.matplotlib.org/downloads.html">downloads</a>| </li>

<li><a href="../search.html">search</a>| </li>

<li><a href="../examples/index.html">examples</a>| </li>

<li><a href="../gallery.html">gallery</a>| </li>

<li><a href="../citing.html">citation</a>| </li>

<li><a href="index.html" >User’s Guide</a> »</li>

</ul>

</div>

Last updated on May 29, 2013.

Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

legend_guide.html

Latest commit

History

legend_guide.html

File metadata and controls