Related Topics

This Page

Quick search

The legend module defines the Legend class, which is responsible for
drawing legends associated with axes and/or figures.

Important

It is unlikely that you would ever create a Legend instance manually.
Most users would normally create a legend via the
legend() function. For more details on legends
there is also a legend guide.

The Legend class can be considered as a container of legend handles
and legend texts. Creation of corresponding legend handles from the
plot elements in the axes or figures (e.g., lines, patches, etc.) are
specified by the handler map, which defines the mapping between the
plot elements and the legend handlers to be used (the default legend
handlers are defined in the legend_handler module).
Note that not all kinds of artist are supported by the legend yet by default
but it is possible to extend the legend handler’s capabilities to
support arbitrary objects. See the legend guide
for more information.

loc can be a tuple of the normalized coordinate values with
respect its parent.

parent: the artist that contains the legend

handles: a list of artists (lines, patches) to be added to the

legend

labels: a list of strings to label the legend

Optional keyword arguments:

Keyword

Description

loc

a location code

prop

the font property

fontsize

the font size (used only if prop is not specified)

markerscale

the relative size of legend markers vs. original

markerfirst

If true, place legend marker to left of label
If false, place legend marker to right of label

numpoints

the number of points in the legend for line

scatterpoints

the number of points in the legend for scatter plot

scatteryoffsets

a list of yoffsets for scatter symbols in legend

frameon

if True, draw a frame around the legend.
If None, use rc

fancybox

if True, draw a frame with a round fancybox.
If None, use rc

shadow

if True, draw a shadow behind legend

framealpha

If not None, alpha channel for the frame.

ncol

number of columns

borderpad

the fractional whitespace inside the legend border

labelspacing

the vertical space between the legend entries

handlelength

the length of the legend handles

handleheight

the height of the legend handles

handletextpad

the pad between the legend handle and text

borderaxespad

the pad between the axes and legend border

columnspacing

the spacing between columns

title

the legend title

bbox_to_anchor

the bbox that the legend will be anchored.

bbox_transform

the transform for the bbox. transAxes if None.

The pad and spacing parameters are measured in font-size units. e.g.,
a fontsize of 10 points and a handlelength=5 implies a handlelength of
50 points. Values from rcParams will be used if None.

Users can specify any arbitrary location for the legend using the
bbox_to_anchor keyword argument. bbox_to_anchor can be an instance
of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
See set_bbox_to_anchor() for more detail.

The legend location can be specified by setting loc with a tuple of
2 floats, which is interpreted as the lower-left corner of the legend
in the normalized axes coordinate.

return a legend handler from legend_handler_map that
corresponds to orig_handler.

legend_handler_map should be a dictionary object (that is
returned by the get_legend_handler_map method).

It first checks if the orig_handle itself is a key in the
legend_hanler_map and return the associated value.
Otherwise, it checks for each of the classes in its
method-resolution-order. If no matching key is found, it
returns None.

bbox can be a BboxBase instance, a tuple of [left, bottom,
width, height] in the given transform (normalized axes
coordinate if None), or a tuple of [left, bottom] where the
width and height will be assumed to be zero.

It is strongly encouraged to have read the legend guide before this documentation.

Legend handlers are expected to be a callable object with a following
signature.

legend_handler(legend,orig_handle,fontsize,handlebox)

Where legend is the legend itself, orig_handle is the original
plot, fontsize is the fontsize in pixles, and handlebox is a
OffsetBox instance. Within the call, you should 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).

This module includes definition of several legend handler classes
derived from the base class (HandlerBase) with the following method.