legend

Description

The legend function places a legend on various types of graphs (line plots, bar graphs, pie charts, etc.). For each line plotted, the legend shows a sample of the line type, marker symbol, and color beside the text label you specify. When plotting filled areas (patch or surface objects), the legend contains a sample of the face color next to the text label.

The font size and font name for the legend strings match the axes FontSize and FontName properties.

legend('string1','string2',...) displays a legend in the current axes using the specified strings to label each set of data.

legend(h,'string1','string2',...) displays a legend on the plot containing the objects identified by the handles in the vector h and uses the specified strings to label the corresponding graphics object (line, barseries, etc.).

legend(M) adds a legend containing the rows of the matrix or cell array of strings M as labels. For matrices, this is the same as legend(M(1,:),M(2,:),...).

legend(h,M) associates each row of the matrix or cell array of strings M with the corresponding graphics object (patch or line) in the vector of handles h.

legend(M,'parameter_name','parameter_value',...) and legend(h,M,'parameter_name','parameter_value',...) allow parameter/value pairs to be set when creating a legend (you can also assign them with set or with the Property Editor or Property Inspector). M must be a cell array of names. Legends inherit the properties of axes, although not all of them are relevant to legend objects.

legend(axes_handle,...) displays the legend for the axes specified by axes_handle.

legend('off'),legend(axes_handle,'off') removes the legend in the current axes or the axes specified by axes_handle.

legend('toggle'),legend(axes_handle,'toggle') toggles the legend on or off. If no legend exists for the current axes, one is created using default strings.

The default string for an object is the value of the object's DisplayName property, if you have defined a value for DisplayName (which you can do using the Property Editor or calling set). Otherwise, legend constructs a string of the form data1, data2, etc. Setting display names is useful when you are experimenting with legends and might forget how objects in a lineseries, for example, are ordered.

When you specify legend strings in a legend command, their respective DisplayNames are set to these strings. If you delete a legend and then create a new legend without specifying labels for it, the values of DisplayName are (re)used as label names. Naturally, the associated plot objects must have a DisplayName property for this to happen: all _series and _group plot objects have a DisplayName property; Handle Graphics primitives, such as line and patch, do not.

Legends for graphs that contain groups of objects such as lineseries, barseries, contourgroups, etc. created by high-level plotting commands such as plot, bar, contour, etc., by default display a single legend entry for the entire group, regardless of how many member objects it contains. However, you can customize such legends to show individual entries for all or selected member objects and assign a unique DisplayName to any of them. You control how groups appear in the legend by setting values for their Annotation and DisplayName properties with code. For information and examples about customizing legends in this manner, see Controlling Legends in the MATLAB Graphics documentation.

You can specify EdgeColor and TextColor as RGB triplets or as ColorSpecs. You cannot set these colors to 'none'. To hide the box surrounding a legend, set the Box property to 'off'. To allow the background to show through the legend box, set the legend's Color property to 'none', for example,

set(legend_handle, 'Box', 'off')
set(legend_handle, 'Color', 'none')

This is similar to the effect of the command legend boxoff, except that boxoff also hides the legend's border.

You can use a legend's handle to set text properties for all the strings in a legend at once with a cell array of strings, rather than looping through each of them. See the last line of the example below, which demonstrates setting a legend's Interpreter property. In that example, you could reset the String property of the legend as follows:

set(h,'String',{'cos(x)','sin(x)'})

See the documentation for Text Properties for additional details.

legend('hide'),legend(axes_handle,'hide') makes the legend in the current axes or the axes specified by axes_handle invisible.

legend('show'),legend(axes_handle,'show') makes the legend in the current axes or the axes specified by axes_handle visible. A legend is created if one did not exist previously. Legends created automatically are limited to depict only the first 20 lines in the plot; if you need more legend entries, you can manually create a legend for them all with legend('string1','string2',...) syntax.

legend('boxoff'),legend(axes_handle,'boxoff') removes the box from the legend in the current axes or the axes specified by axes_handle, and makes its background transparent.

legend('boxon'),legend(axes_handle,'boxon') adds a box with an opaque background to the legend in the current axes or the axes specified by axes_handle.

You can also type the above six commands using the syntax

legend keyword

If the keyword is not recognized, it is used as legend text, creating a legend or replacing the current legend.

legend_handle = legend(...) returns the handle to the legend on the current axes, or [] if no legend exists.

legend(...,'Location','location') uses location to determine where to place the legend. location can be either be a 1-by-4 position vector ([left,bottom,width,height]) or one of the following strings.

Specifier	Location in Axes
North	Inside plot box near top
South	Inside bottom
East	Inside right
West	Inside left
NorthEast	Inside top right (default for 2-D plots)
NorthWest	Inside top left
SouthEast	Inside bottom right
SouthWest	Inside bottom left
NorthOutside	Outside plot box near top
SouthOutside	Outside bottom
EastOutside	Outside right
WestOutside	Outside left
NorthEastOutside	Outside top right (default for 3-D plots)
NorthWestOutside	Outside top left
SouthEastOutside	Outside bottom right
SouthWestOutside	Outside bottom left
Best	Least conflict with data in plot
BestOutside	Least unused space outside plot

Using one of the ...Outside values for ‘Location' ensures that the legend does not overlap the plot, whereas overlaps can occur when you specify any of the other cardinal values. The location property applies to colorbars and legends, but not to axes.

Note:   You can set the legend location by passing the 4-element position vector to the legend function using the ‘Location' option. To define the position of an existing legend, use the set function to assign the 4-element position vector to the ‘Position' property. You cannot use the Location option with the set function.

Obsolete Location Values

The first column of the following table shows the now-obsolete specifiers for legend locations that were in use prior to Version 7, along with a description of the locations and their current equivalent syntaxes:

Obsolete Specifier	Location in Axes	Current Specifier
-1	Outside axes on right side	NorthEastOutside
0	Inside axes	Best
1	Upper right corner of axes	NorthEast
2	Upper left corner of axes	NorthWest
3	Lower left corner of axes	SouthWest
4	Lower right corner of axes	SouthEast

legend(...,'Orientation','orientation') creates a legend with the legend items arranged in the specified orientation. orientation can be vertical (the default) or horizontal.

[legend_h,object_h,plot_h,text_strings] = legend(...) returns

• legend_h — Handle of the legend axes

• object_h — Handles of the line, patch, and text graphics objects used in the legend

• plot_h — Handles of the lines and other objects used in the plot

• text_strings — Cell array of the text strings used in the legend

Relationship to Axes

legend associates strings with the objects in the axes in the same order that they are listed in the axes Children property. By default, the legend annotates the current axes.

You can only display one legend per axes. legend positions the legend based on a variety of factors, such as what objects the legend obscures.

The properties that legends do not share with axes are

• Location

• Orientation

• EdgeColor

• TextColor

• Interpreter

• String

Tips

Using Keywords as Legend Labels

To use legend keywords like 'Location', ‘Orientation', ‘Off', 'Hide', or property names as legend labels, pass the string in a cell array to the legend function as,

l = legend({'Location'});

Examples

Add a legend to a graph showing a sine and cosine function. The default location is upper right, within the axes:

figure
x = -pi:pi/20:pi;
plot(x,cos(x),'-ro',x,sin(x),'-.b')
hleg1 = legend('cos_x','sin_x');

The legend reflects that plot specified a solid, red line ('-ro') for the cosine function and a dash-dot, blue line ('-.b') for the sine function.

Update the legend. Use the returned legend handle, hleg1, to move the legend to the upper left. Also turn off the TeX interpreter to render underscores in legend text literally rather than as subscripts:

    set(hleg1,'Location','NorthWest')
    set(hleg1,'Interpreter','none')

Setting the position of the legend at a particular position.

set(hleg1, 'Position', [.1,.2,.1,.2]);

Use besselj to plot Bessel functions for orders 1, 2, and 3. Add a legend for the lines at the upper right, outside the axes.

figure
x = 0:.2:12;
plot(x,besselj(1,x),x,besselj(2,x),x,besselj(3,x));
hleg = legend('First','Second','Third',...
              'Location','NorthEastOutside')
% Make the text of the legend italic and color it brown
set(hleg,'FontAngle','italic','TextColor',[.3,.2,.1])

Create a bar graph and overlay a line plot on it by setting hold on. Create a legend that reflects both graphs and locate it to the lower right, outside the axes:

figure
stream = RandStream('mrg32k3a','Seed',4);
y1 = rand(stream,10,5);
hb = bar(y1,'stacked'); colormap(summer); hold on
y2 = rand(stream,10,1);
hp = plot(1:10,y2,'marker','square','markersize',12,...
       'markeredgecolor','y','markerfacecolor',[.6,0,.6],...
       'linestyle','-','color','r','linewidth',2); hold off
legend([hb,hp],'Carrots','Peas','Peppers','Green Beans',...
        'Cucumbers','Eggplant','Location','SouthEastOutside')

Alternatives

Add a legend to a selected axes on a graph with the Insert Legend tool on the figure toolbar, or use Insert > Legend from the figure menu. Use the Property Editor to modify the position, font, and other properties of a legend. For details, see Using Plot Edit Mode.

Moving the Legend

Move the legend by pressing the left mouse button while the cursor is over the legend and dragging the legend to a new location. Double-clicking a label allows you to edit the label.