Axes.legend¶
- Axes.legend(handles=None, labels=None, loc=None, location=None, queue=False, **kwargs)[source]¶
Add an inset legend or outer legend along the edge of the axes.
- Parameters
handles (
list
ofartist
, optional) – List of matplotlib artists, or a list of lists of artist instances (see thecenter
keyword). IfNone
, artists with valid labels are retrieved automatically. If the object is aContourSet
, thelegend_elements
method is used to pair the collection or contour set label with the central artist in the list (generally giving the central colormap color if the object is controlled with a colormap).labels (
list
ofstr
, optional) – A matching list of string labels orNone
placeholders, or a matching list of lists (see thecenter
keyword). WhereverNone
appears in the list (or if no labels were passed at all), labels are retrieved by callingget_label
on eachArtist
in the handle list. If a handle consists of a tuple group of artists, labels are inferred from the artists in the tuple. If there are multiple unique labels in the tuple group of artists, the tuple group is expanded into unique legend entries. Otherwise, the tuple group elements are drawn on top of eachother. For details on matplotlib’s legend handlers, including tuple groups, see the matplotlib legend guide.loc, location (
int
orstr
, optional) – The legend location. Default isrc['legend.loc']
='best'
. Valid location keys are shown in the below table.Location
Valid keys
outer left
'left'
,'l'
outer right
'right'
,'r'
outer bottom
'bottom'
,'b'
outer top
'top'
,'t'
“best” inset
'best'
,'inset'
,'i'
,0
upper right inset
'upper right'
,'ur'
,1
upper left inset
'upper left'
,'ul'
,2
lower left inset
'lower left'
,'ll'
,3
lower right inset
'lower right'
,'lr'
,4
center left inset
'center left'
,'cl'
,5
center right inset
'center right'
,'cr'
,6
lower center inset
'lower center'
,'lc'
,7
upper center inset
'upper center'
,'uc'
,8
center inset
'center'
,'c'
,9
“filled”
'fill'
width (
unit-spec
, optional) – For outer legends only. The space allocated for the legend box. This does nothing if the tight layout algorithm is active for the figure. If float, units are inches. If string, interpreted byunits
.queue (
bool
, optional) – IfTrue
andloc
is the same as an existing legend, the input arguments are added to a queue and this function returnsNone
. This is used to “update” the same legend with successiveax.legend(...)
calls. IfFalse
(the default) andloc
is the same as an existing inset legend, the old legend is removed. IfFalse
andloc
is an outer legend, the legends are stacked.space (
unit-spec
, optional) – For outer legends only. The fixed space between the legend and the subplot edge. If float, units are em-widths. If string, interpreted byunits
. When the tight layout algorithm is active for the figure, this is adjusted automatically usingpad
. Otherwise, a suitable default is selected.pad (
unit-spec
, optional) – For outer legends, this is the tight layout padding between the legend and the subplot. Default isrc['subplots.panelpad']
=0.5
. For inset legends, this is the fixed space between the axes edge and the legend. Default isrc['legend.borderaxespad']
=0
. If float, units are em-widths. If string, interpreted byunits
.align (
{'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', 'r'}
, optional) – For outer legends only. How to align the legend against the subplot edge. Default is'center'
. The values'top'
and'bottom'
are valid for left and right legends and'left'
and'right'
are valid for top and bottom legends. The default is always'center'
.
- Other Parameters
frame, frameon (
bool
, optional) – Toggles the legend frame. For centered-row legends, a frame independent from matplotlib’s built-in legend frame is created.ncol, ncols (
int
, optional) – The number of columns.ncols
is an alias, added for consistency withsubplots
.order (
{'C', 'F'}
, optional) – Whether legend handles are drawn in row-major ('C'
) or column-major ('F'
) order. Analagous tonumpy.array
ordering. Default is'F'
.center (
bool
, optional) – Whether to center each legend row individually. IfTrue
, we draw successive single-row legends stacked on top of each other. IfNone
, we infer this setting fromhandles
. By default,center
is set toTrue
ifhandles
is a list of lists (each sublist is used as a row in the legend).alphabetize (
bool
, optional) – Whether to alphabetize the legend entries according to the legend labels. Default isFalse
.title, label (
str
, optional) – The legend title. Thelabel
keyword is also accepted, for consistency withcolorbar
.fontsize, fontweight, fontcolor (optional) – The font size, weight, and color for the legend text. Font size is interpreted by
units
. The default font size isrc['legend.fontsize']
.titlefontsize, titlefontweight, titlefontcolor (optional) – The font size, weight, and color for the legend title. Font size is interpreted by
units
. The default size isfontsize
.borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing (
unit-spec
, optional) – Various matplotliblegend
spacing arguments. If float, units are em-widths. If string, interpreted byunits
.a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth (optional) – The opacity, face color, edge color, and edge width for the legend frame. Defaults are
rc['legend.framealpha']
=0.8
,rc['legend.facecolor']
='white'
,rc['legend.edgecolor']
='black'
andrc['axes.linewidth']
=0.6
.c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize (optional) – Properties used to override the legend handles. For example, for a legend describing variations in line style ignoring variations in color, you might want to use
color='black'
.handle_kw (dict-like, optional) – Additional properties used to override legend handles, e.g.
handle_kw={'edgecolor': 'black'}
. Only line properties can be passed as keyword arguments.handler_map (dict-like, optional) – A dictionary mapping instances or types to a legend handler. This
handler_map
updates the default handler map found atmatplotlib.legend.Legend.get_legend_handler_map
.**kwargs – Passed to
legend
.