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 of Artist, optional) – List of matplotlib artists, or a list of lists of artist instances (see the center keyword). If None, the artists are retrieved automatically. If the object is a Collection or a ContourSet, the legend_elements method is used to pair the collection or contour set label with the central element in the list (generally giving the central colormap color if the object is controlled with a colormap).

  • labels (list of str, optional) – A matching list of string labels or None placeholders, or a matching list of lists (see the center keyword). Wherever None appears in the list (or if no labels were passed at all), labels are retrieved by calling get_label on each Artist 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 (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 2-tuple of 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, and fig.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 or str, optional) – The fixed space between the legend and the subplot grid. Units are interpreted by units. When the tight layout algorithm is active for the figure, this is adjusted automatically using pad. Otherwise, a suitable default is selected.

  • pad (float or str, optional) – The tight layout padding between the subplot grid and the legend. Default is rc['subplots.innerpad'] = 1.0 for the first legend and rc['subplots.panelpad'] = 0.5 for subsequently stacked legends.

  • width (float or str, optional) – The space allocated for the legend box. This does nothing if the tight layout algorithm is active for the figure. Units are interpreted by units.

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 with subplots.

  • order ({'C', 'F'}, optional) – Whether legend handles are drawn in row-major ('C') or column-major ('F') order. Analagous to numpy.array ordering. Default is 'F'.

  • center (bool, optional) – Whether to center each legend row individually. If True, we draw successive single-row legends stacked on top of each other. If None, we infer this setting from handles. By default, center is set to True if handles 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 is False.

  • title, label (str, optional) – The legend title. The label keyword is also accepted, for consistency with colorbar.

  • fontsize, fontweight, fontcolor (optional) – The font size, weight, and color for the legend text. Font size is interpreted by units. The default font size is rc['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 is fontsize.

  • 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' and rc['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 use color='k'.

  • borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing (float or str, optional) – Native legend spacing arguments interpreted with units. The default units are still font size-relative.

  • **kwargs – Passed to legend.

See also

proplot.axes.Axes.legend, matplotlib.axes.Axes.legend