Main Content

bubblelegend

Create legend for bubble chart

Since R2020b

    Description

    bubblelegend creates a bubble legend in the current axes. Bubble legends are useful for showing the relationship between the bubbles and the size data for charts you create with the bubblechart, bubblechart3, and polarbubblechart functions.

    example

    bubblelegend(titletext) specifies a title for the legend. Specify titletext as a character vector, cell array of character vectors, or a string array.

    example

    bubblelegend(___,Name,Value) sets bubble legend properties using one or more name-value pair arguments. Specify the properties after all other input arguments.

    bubblelegend(ax,___) creates the legend in the specified target axes ax. Specify the axes before all other input arguments.

    example

    blgd = bubblelegend(___) returns the BubbleLegend object. Use blgd to modify properties of the legend after creating it. For a list of properties, see BubbleLegend Properties.

    Examples

    collapse all

    Create a bubble chart and add a bubble legend.

    x = 1:10;
    y = exp(-0.5*x) +  .05 * randn(1,10);
    sz = randi([20 500],[1,10]);
    bubblechart(x,y,sz)
    bubblelegend('Population')

    Create a bubble chart and add a bubble legend. Specify the 'telescopic' style for a more compact presentation.

    x = 1:15;
    y = exp(-0.5*x) +  .1 * randn(1,15);
    sz = randi([20 500],[1,15]);
    bubblechart(x,y,sz)
    bubblelegend('Population','Style','telescopic');

    Create a bubble chart. Then call the bubblelegend function with a return argument to store the BubbleLegend object as blgd. Move the legend outside the plot box by setting the Location property on the object to 'northeastoutside'. Display two bubbles instead of three by setting the NumBubbles property to 2.

    x = 1:50;
    y = rand(1,50);
    sz = randi([20 500],[1,50]);
    bubblechart(x,y,sz)
    
    % Create bubble legend and set properties
    blgd = bubblelegend('Population');
    blgd.Location = 'northeastoutside';
    blgd.NumBubbles = 2;

    When you display multiple data sets with different colors or different types of plot objects, you can include multiple legends. To manage the alignment of the legends, create your chart in a tiled chart layout.

    Create two sets of data, and plot them together in the same axes object within a tiled chart layout.

    x = 1:20;
    y1 = rand(1,20);
    y2 = rand(1,20);
    sz1 = randi([20 500],[1,20]);
    sz2 = randi([20 500],[1,20]);
    
    % Plot data in a tiled chart layout
    t = tiledlayout(1,1);
    nexttile
    bubblechart(x,y1,sz1)
    hold on
    bubblechart(x,y2,sz1)
    hold off

    Add a bubble legend for illustrating the bubble sizes, and add another legend for illustrating the colors. Call the bubblelegend and legend functions using a return argument to store the legend objects. Move the legends to the east tile by setting the Layout.Tile property on each object to 'east'. Placing the legends together in a tile keeps them aligned.

    blgd = bubblelegend('Population');
    lgd = legend('Springfield','Fairview');
    blgd.Layout.Tile = 'east';
    lgd.Layout.Tile = 'east';

    Input Arguments

    collapse all

    Title text, specified as a character vector, cell array of character vectors, or string array. To create a multiline title, specify a cell array of character vectors or a string array.

    Example: bubblelegend('My Legend')

    Target axes, specified as an Axes, PolarAxes, or GeographicAxes object. If you do not specify the axes, MATLAB® plots into the current axes, or it creates an Axes object if one does not exist.

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: bubblelegend('Style','telescopic') creates a telescopic legend.

    Note

    The properties listed here are only a subset. For a complete list, see BubbleLegend Properties.

    Location with respect to the axes, specified as one of the location values listed in this table.

    ValueDescription
    'north'Inside top edge of the axes.
    'south'Inside bottom edge of the axes.
    'east'Inside right edge of the axes.
    'west'Inside left edge of the axes.
    'northeast'Inside top-right corner of the axes.
    'northwest'Inside top-left corner of the axes.
    'southeast'Inside bottom-right corner of the axes.
    'southwest'Inside bottom-left corner of the axes.
    'northoutside'Above the axes.
    'southoutside'Below the axes.
    'eastoutside'To the right of the axes.
    'westoutside'To the left of the axes.
    'northeastoutside'Outside top-right corner of the axes.
    'northwestoutside'Outside top-left corner of the axes.
    'southeastoutside'Outside bottom-right corner of the axes.
    'southwestoutside'Outside bottom-left corner of the axes
    'layout'A tile in a tiled chart layout. To move the legend to a different tile, set the Layout property.
    'none'A location determined by the Position property. Use the Position property to specify a custom location.

    Legend style, specified as one of the values from the table. The images in the table show how a legend with three bubbles looks with the different styles.

    Style ValueAppearance
    'vertical'

    Vertical style legend with three bubbles.

    'horizontal'

    Horizontal style legend with three bubbles.

    'telescopic'

    Telescopic style legend with three bubbles.

    Number of bubbles to display in the legend, specified as 2 or 3. This table shows how a vertical bubble legend looks with 2 and 3 bubbles.

    NumBubbles ValueAppearance
    2

    Vertical style legend with two bubbles.

    3

    Vertical style legend with three bubbles.

    Limit labels, specified as a two- or three-element cell array of character vectors or string array. The first label appears next to the smallest bubble in the legend, and the last label appears next to the largest bubble. If you specify three labels, the second label does not display when the legend is horizontal or if the legend only has two bubbles. This table shows some common scenarios.

    ExampleResult

    Create a vertical legend with three bubbles, and specify three limit labels.

    blgd = bubblelegend;
    blgd.LimitLabels = {'Shortage','Abundance','Surplus'};

    Vertical legend displaying all three labels.

    Create a telescopic legend with three bubbles, and specify three limit labels.

    blgd = bubblelegend('Style','telescopic');
    blgd.LimitLabels = {'Shortage','Abundance','Surplus'};

    Telescopic legend displaying all three labels.

    Create a vertical legend with two bubbles, and specify three limit labels.

    blgd = bubblelegend('NumBubbles',2);
    blgd.LimitLabels = {'Shortage','Abundance','Surplus'};

    Legend with two bubbles displaying two of the three labels.

    Create a horizontal legend with three bubbles, and specify three limit labels.

    blgd = bubblelegend('Style','horizontal');
    blgd.LimitLabels = {'Shortage','Abundance','Surplus'};

    Horizontal legend displaying two of the three labels.

    Order of the bubble sizes, specified as one of the values from the table. The table shows the effect of the different values on a vertical legend that has three bubbles.

    BubbleSizeOrder ValueAppearance
    'descending'

    Vertical legend with descending order.

    'ascending'

    Vertical legend with ascending order.

    Version History

    Introduced in R2020b