diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 35723b844c2a..e5846422b9f9 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -323,8 +323,8 @@ def legend(self, *args, **kwargs):
legend(labels)
legend(handles, labels)
- The call signatures correspond to three different ways how to use
- this method.
+ The call signatures correspond to these three different ways to use
+ this method:
**1. Automatic detection of elements to be shown in the legend**
@@ -335,7 +335,7 @@ def legend(self, *args, **kwargs):
them either at artist creation or by calling the
:meth:`~.Artist.set_label` method on the artist::
- line, = ax.plot([1, 2, 3], label='Inline label')
+ ax.plot([1, 2, 3], label='Inline label')
ax.legend()
or::
@@ -360,7 +360,7 @@ def legend(self, *args, **kwargs):
ax.plot([1, 2, 3])
ax.legend(['A simple line'])
- Note: This way of using is discouraged, because the relation between
+ Note: This call signature is discouraged, because the relation between
plot elements and labels is only implicit by their order and can
easily be mixed up.
@@ -371,7 +371,7 @@ def legend(self, *args, **kwargs):
to pass an iterable of legend artists followed by an iterable of
legend labels respectively::
- legend((line1, line2, line3), ('label1', 'label2', 'label3'))
+ ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
Parameters
----------
@@ -398,6 +398,10 @@ def legend(self, *args, **kwargs):
----------------
%(_legend_kw_doc)s
+ See Also
+ --------
+ .Figure.legend
+
Notes
-----
Some artists are not supported by this function. See
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 4ba402e08654..6a28a3747c49 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -1891,23 +1891,62 @@ def legend(self, *args, **kwargs):
"""
Place a legend on the figure.
- To make a legend from existing artists on every axes::
+ Call signatures::
+
+ legend()
+ legend(labels)
+ legend(handles, labels)
+
+ The call signatures correspond to these three different ways to use
+ this method:
+
+ **1. Automatic detection of elements to be shown in the legend**
+
+ The elements to be added to the legend are automatically determined,
+ when you do not pass in any extra arguments.
+
+ In this case, the labels are taken from the artist. You can specify
+ them either at artist creation or by calling the
+ :meth:`~.Artist.set_label` method on the artist::
+
+ ax.plot([1, 2, 3], label='Inline label')
+ fig.legend()
+
+ or::
+
+ line, = ax.plot([1, 2, 3])
+ line.set_label('Label via method')
+ fig.legend()
- legend()
+ Specific lines can be excluded from the automatic legend element
+ selection by defining a label starting with an underscore.
+ This is default for all artists, so calling `.Figure.legend` without
+ any arguments and without setting the labels manually will result in
+ no legend being drawn.
- To make a legend for a list of lines and labels::
- legend(
- (line1, line2, line3),
- ('label1', 'label2', 'label3'),
- loc='upper right')
+ **2. Labeling existing plot elements**
- These can also be specified by keyword::
+ To make a legend for all artists on all Axes, call this function with
+ an iterable of strings, one for each legend item. For example::
- legend(
- handles=(line1, line2, line3),
- labels=('label1', 'label2', 'label3'),
- loc='upper right')
+ fig, (ax1, ax2) = plt.subplots(1, 2)
+ ax1.plot([1, 3, 5], color='blue')
+ ax2.plot([2, 4, 6], color='red')
+ fig.legend(['the blues', 'the reds'])
+
+ Note: This call signature is discouraged, because the relation between
+ plot elements and labels is only implicit by their order and can
+ easily be mixed up.
+
+
+ **3. Explicitly defining the elements in the legend**
+
+ For full control of which artists have a legend entry, it is possible
+ to pass an iterable of legend artists followed by an iterable of
+ legend labels respectively::
+
+ fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
Parameters
----------
@@ -1934,6 +1973,10 @@ def legend(self, *args, **kwargs):
----------------
%(_legend_kw_doc)s
+ See Also
+ --------
+ .Axes.legend
+
Notes
-----
Some artists are not supported by this function. See
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy