Add an inset legend or outer legend along the edge of the axes.

  • handles (list of artist, optional) – List of matplotlib artists, or a list of lists of artist instances (see the center keyword). If not passed, artists with valid labels (applied by passing label or labels to a plotting command or calling set_label) are retrieved automatically. If the object is a ContourSet, legend_elements is used to select the central artist in the list (generally useful for single-color contour plots). Note that proplot’s contour and contourf accept a legend label keyword argument.

  • 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 legend handlers and tuple groups, see the matplotlib legend guide.

  • loc, location (int or str, default: rc['legend.loc'] = 'best') – The legend location. Valid location keys are shown in the below table.


    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



  • 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 by units.

  • queue (bool, optional) – If True and loc is the same as an existing legend, the input arguments are added to a queue and this function returns None. This is used to “update” the same legend with successive ax.legend(...) calls. If False (the default) and loc is the same as an existing inset legend, the old legend is removed. If False and loc is an outer legend, the legends are “stacked”.

  • space (unit-spec, default: None) – For outer legends only. The fixed space between the legend and the subplot edge. If float, units are em-widths. If string, interpreted by units. When the tight layout algorithm is active for the figure, space is computed automatically (see pad). Otherwise, space is set to a suitable default.

  • pad (unit-spec, default: rc['subplots.panelpad'] = 0.5 or rc['legend.borderaxespad'] = 0.0) – For outer legends, this is the tight layout padding between the legend and the subplot (default is rc['subplots.panelpad']). For inset legends, this is the fixed space between the axes edge and the legend (default is rc['legend.borderaxespad']). If float, units are em-widths. If string, interpreted by units.

  • align ({'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional) – For outer legends only. How to align the legend against the subplot edge. 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 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. The matplotlib default was 'F' but proplot changes this to 'C'.

  • 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, default: False) – Whether to alphabetize the legend entries according to the legend labels.

  • 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.

  • borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing (unit-spec, optional) – Various matplotlib legend spacing arguments. If float, units are em-widths. If string, interpreted by units.

  • a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth (default: rc['legend.framealpha'] = 0.8, rc['legend.facecolor'] = 'white', rc['legend.edgecolor'] = 'black', rc['axes.linewidth'] = 0.6) – The opacity, face color, edge color, and edge width for the legend frame.

  • 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 at matplotlib.legend.Legend.get_legend_handler_map.

  • **kwargs – Passed to legend.