Figure.legend¶
- Figure.legend(handles=None, labels=None, *, loc=None, location=None, row=None, col=None, rows=None, cols=None, span=None, space=None, pad=None, width=None, **kwargs)[source]¶
Draw a legend along the left, right, bottom, or top side of the figure, centered between the leftmost and rightmost (or topmost and bottommost) main subplots.
- Parameters
handles (
list
ofArtist
, optional) – List of matplotlib artists, or a list of lists of artist instances (see thecenter
keyword). IfNone
, the artists are retrieved withget_legend_handles_labels
.labels (
list
ofstr
, optional) – 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. For details on matplotlib legend handlers, see the matplotlib legend guide.loc (
str
, optional) – The legend location. Valid location keys are as follows.Location
Valid keys
left edge
'l'
,'left'
right edge
'r'
,'right'
bottom edge
'b'
,'bottom'
top edge
't'
,'top'
row, rows – Aliases for
span
for legends on the left or right side.col, cols – Aliases for
span
for legends on the top or bottom side.span (
int
or(int
,int)
, optional) – Describes how the legend spans rows and columns of subplots. For example,fig.legend(loc='b', col=1)
draws a legend beneath the leftmost column of subplots, andfig.legend(loc='b', cols=(1,2))
draws a legend beneath the left two columns of subplots. By default, the legend will span all rows and columns.space (
float
orstr
, optional) – The fixed space between the legend and the subplot grid. Units are interpreted byunits
. When the tight layout algorithm is active for the figure, this is adjusted automatically usingpad
. Otherwise, a suitable default is selected.pad (
float
orstr
, optional) – The tight layout padding between the subplot grid and the legend. Default isrc['subplots.innerpad']
=1.0
for the first legend andrc['subplots.panelpad']
=0.5
for subsequently stacked legend.width (
float
orstr
, optional) – The space allocated for the legend box. This does nothing if the tight layout algorithm is active for the figure. Units are interpreted byunits
.
- 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
.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
.color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize (
property-spec
, 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 usecolor='k'
.borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing (
float
orstr
, optional) – Nativelegend
spacing arguments interpreted withunits
. The default units are still font size-relative.**kwargs – Passed to
legend
.