bubblecloud

Create bubble cloud chart

Since R2021a

• 

Syntax

bubblecloud(tbl,szvar)

bubblecloud(tbl,szvar,labelvar)

bubblecloud(tbl,szvar,labelvar,groupvar)

bubblecloud(sz)

bubblecloud(sz,labels)

bubblecloud(sz,labels,groups)

bubblecloud(___,Name,Value)

bubblecloud(parent,___)

b = bubblecloud(___)

Description

Table Data

bubblecloud(tbl,szvar) creates a bubble cloud chart using the data in the table tbl. Specify szvar as the table variable containing the bubble sizes. For example, you can specify the name of the variable or an index to the variable.

Bubble cloud charts are useful for illustrating the relationship between elements in your data set and the set as a whole. For example, you can visualize data collected from different cities, and represent each city as a bubble whose size is proportional to the value for that city.

bubblecloud(tbl,szvar,labelvar) displays labels on the bubbles. Specify labelvar as the table variable containing the bubble labels.

bubblecloud(tbl,szvar,labelvar,groupvar) specifies grouping data for the bubbles. Use groups to display multiple clouds with different colors. Specify groupvar as the variable that contains the grouping data.

Vector Data

bubblecloud(sz) creates a bubble cloud chart with the bubble sizes specified as a vector.

bubblecloud(sz,labels) displays labels on the bubbles. Specify labels as a cell array of character vectors or a string vector that is the same length as sz.

bubblecloud(sz,labels,groups) specifies grouping data for the bubbles. Use groups to display multiple clouds with different colors. Specify groups as a vector that is the same length as sz and labels.

Additional Options

bubblecloud(___,Name,Value) specifies additional bubble cloud properties using one or more name-value arguments. Specify the properties after all other input arguments. For a list of properties, see BubbleCloud Properties.

bubblecloud(parent,___) creates the bubble cloud in the figure, panel, or tab specified by parent.

b = bubblecloud(___) returns the BubbleCloud object. Use b to modify properties of the chart after creating it.

Examples

Create Bubble Cloud with Table Data

Create a table with three variables. For example, create a table that shows the number of mislabeled Halloween costumes in 10 states. Of the 10,000 princess kits sold, 1,000 had spooky monster labels by mistake.

n = [58 115 81 252 180 124 40 80 50 20]';
loc = ["NJ" "NY" "MA" "OH" "NH" "ME" "CT" "PA" "RI" "VT"]';
plant = ["Plant A" "Plant A" "Plant A" "Plant A" ...
       "Plant A" "Plant A" "Plant A" "Plant B" "Plant B" "Plant B"]';
tbl = table(n,loc,plant,'VariableNames',["Mislabeled" "State" "Manufacturing Plant"])

tbl=10×3 table
    Mislabeled    State    Manufacturing Plant
    __________    _____    ___________________

        58        "NJ"          "Plant A"     
       115        "NY"          "Plant A"     
        81        "MA"          "Plant A"     
       252        "OH"          "Plant A"     
       180        "NH"          "Plant A"     
       124        "ME"          "Plant A"     
        40        "CT"          "Plant A"     
        80        "PA"          "Plant B"     
        50        "RI"          "Plant B"     
        20        "VT"          "Plant B"     

Create a bubble cloud to visualize the mislabeled costumes by state.

bubblecloud(tbl,"Mislabeled","State")

Divide the bubbles into groups by specifying the groupvar argument. In this case, the groups are in the variable called "Manufacturing Plant".

bubblecloud(tbl,"Mislabeled","State","Manufacturing Plant")

Create Bubble Cloud with Vector Data

Define n as a vector of bubble sizes with the numbers from a survey of favorite ice cream flavors. Define flavs as a string vector containing the flavor names. Then create a bubble cloud that shows the distribution of favorite ice cream flavors.

n = [58 115 81 252 200 224 70 120 140];
flavs = ["Rum" "Pumpkin" "Mint" "Vanilla" "Chocolate" ...
    "Strawberry" "Twist" "Coffee" "Cookie"];
bubblecloud(n,flavs)

Define ages as a categorical vector containing the age group that prefers each flavor. Specify the order of the categories by calling the reordercats function. Then create a new bubble cloud with the bubbles grouped by age, and return the BubbleCloud object as b. When you specify group data, the chart displays a legend by default. Add a title to the legend by setting the LegendTitle property of b.

ages = categorical(["40-90+" "5-15" "16-39" "40-90+" ...
   "5-15" "16-39" "5-15" "16-39" "40-90+"]);
ages = reordercats(ages,["5-15" "16-39" "40-90+"] );
b = bubblecloud(n,flavs,ages);
b.LegendTitle = 'Age Range';

Customize Bubble Color

Load the patients data set, and create a bubble cloud of 20 patient weight measurements with the corresponding self-assessed health status values ('poor', 'fair', 'good', or 'excellent'). Customize the color of the bubbles by specifying the FaceColor name-value argument. Return the BubbleCloud object as b, so you can set properties on the object later.

load patients
b = bubblecloud(Weight(1:20),SelfAssessedHealthStatus(1:20), ...
    'FaceColor',[0.3 0.6 0.4]);

Group the bubbles according to whether the patients are smokers. When you group the data, a legend automatically appears in the figure. Specify a title for the legend. Then, retain the visibility of the bubble labels by increasing the size of the figure and setting the font size to 9 points.

b.GroupData = Smoker(1:20);
b.LegendTitle = "Smoker";
f = gcf;
f.Position([3 4]) = [655 395];
b.FontSize = 9;

To visualize the groups with different colors, set the FaceColor property back to the default value of 'flat'. To make the edges of the bubbles use those same colors, set the EdgeColor property to 'flat'.

b.FaceColor = 'flat';
b.EdgeColor = 'flat';

To customize the group colors, set the ColorOrder property to a matrix containing the RGB triplets for the new colors.

b.ColorOrder = [0.3 0.6 0.4; 0.4 0.3 0.6];

Alternatively, you can pass the BubbleCloud object to the colororder function to set this property. When you use this function, you can specify the colors as RGB triplets, hexadecimal color codes, or predefined color names. For example, specify the hexadecimal color codes for two colors.

colororder(b,["#E6CC1A"; "#4D9966"])

Visualize Categorical Data with Bubble Cloud

Define c as a categorical array. Use the histounts function to bin the categorical data and return the bubble sizes and the labels. Then pass the bubble sizes and labels to the bubblecloud function.

c = categorical(["Pumpkin" "Princess" "Princess" "Princess" "Spooky Monster" ...
    "Spooky Monster" "Spooky Monster" "Spooky Monster" "Spooky Monster"]);
[sz,labels] = histcounts(c);
bubblecloud(sz,labels)

Input Arguments

tbl — Table containing bubble data

table | timetable

Table containing bubble data. The table must have at least one variable that specifies the bubble sizes. The bubble sizes can include nonnegative numeric, NaN, and Inf values. Only bubbles with positive sizes appear in the chart. Zero, NaN, and Inf values are ignored.

The table can optionally include variables containing the following data:

• Bubble labels — Create this variable using a cell array of character vectors or a string vector.

• Grouping data — Create this variable using a cell array of character vectors, string vector, categorical vector, numeric vector, or logical vector.

Grouping data is useful for displaying multiple clouds with different colors. For example, you can display car data grouped by manufacturer.

szvar — Table variable for bubble sizes

variable name | variable index | logical vector

Table variable for the bubble sizes, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the size data.

• Variable index — Index of the table variable containing the size data. Specify the index as a number between 1 and the number of variables in the table.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

labelvar — Table variable for bubble labels

variable name | variable index | logical vector

Table variable for the bubble labels, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the labels.

• Variable index — Index of the table variable containing the labels. Specify the index as a number between 1 and the number of variables in the table.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

groupvar — Table variable for bubble groups

variable name | variable index | logical vector

Table variable for the bubble groups, specified as one of the following values:

• Variable name — Character vector or string scalar with the name of the table variable containing the grouping data.

• Variable index — Index of the table variable containing the grouping data. Specify the index as a number between 1 and the number of variables in the table.

• Logical vector — Vector of logical values that has the same number of elements as there are variables in the table. The vector must contain only one true value.

When you specify bubble groups, bubblecloud divides your data into separate bubble clouds with different colors, and it displays a legend. The colors are determined by the ColorOrder property, and the title of the legend is name of the groupvar variable in the table.

sz — Bubble size vector

numeric vector

Bubble sizes, specified as a numeric vector containing nonnegative values. Zero, NaN, and Inf values are ignored. For example bubblecloud(1:10) creates ten bubbles with sizes 1 through 10.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

labels — Bubble labels vector

cell array of character vectors | string vector

Bubble labels, specified as a cell array of character vectors or a string vector. The number of elements in the cell array or string vector must match the number of elements in the sz vector. For example bubblecloud(1:3,["one" "two" "three"]) creates three bubbles with the labels "one","two", and "three".

Data Types: cell | string

groups — Bubble groups vector

cell array of character vectors | string vector | categorical vector | logical vector

Bubble groups, specified as a cell array of character vectors, string vector, categorical vector, or logical vector. The number of elements must match the number of elements in the sz vector. For example bubblecloud(1:3,["one" "two" "three"],["Group1" "Group2" "Group2"]) creates three bubbles that are divided into two groups.

When you specify bubble groups, bubblecloud divides your data into separate bubble clouds with different colors, and it displays a legend without a title. The colors are determined by the ColorOrder property.

Data Types: cell | string | categorical | logical

parent — Parent container

Figure object | Panel object | Tab object | TiledChartLayout object | GridLayout object

Parent container, specified as a Figure, Panel, Tab, TiledChartLayout, or GridLayout object.

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: bubblecloud(1:10,'FaceColor','red') creates a red bubble cloud.

Note

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

Title — Chart title

character vector | cell array of character vectors | string array | categorical array

Chart title, specified as a character vector, cell array of character vectors, string array, or categorical array. To create a mutliline title, specify a cell array of character vectors or a string array. Each element in the array is a separate line of text.

Alternatively, you can call the title function to add a title to the chart.

bubblecloud(rand(1,20))
title("Random Bubbles")

LegendTitle — Legend title

character vector | cell array of character vectors | string array | categorical array

Legend title, specified as a character vector, cell array of character vectors, string array, or categorical array. To create a mutliline title, specify a cell array of character vectors or a string array. Each element in the array is a separate line of text.

If you specify your data in a table, then the default legend title is the name of the variable that specifies the groups.

FaceColor — Bubble fill color

'flat' (default) | RGB triplet | hexadecimal color code | color name | short name | 'none'

Bubble fill color, specified as a value from this table.

FaceColor Value	Description
'flat'	Let MATLAB® assign a different color to each group of bubbles. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom color to all the groups of bubbles: RGB triplet — A three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one predefined color to all the groups of bubbles using a color name such as 'red', or a short name such as 'r'. The table below lists the available color names and short names.
'none'	Display all groups of bubbles without any color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

EdgeColor — Bubble edge color

'flat' | RGB triplet | hexadecimal color code | color name | short name | 'none'

Bubble edge color, specified as a value from this table.

EdgeColor Value	Description
'flat'	Let MATLAB assign a different edge color to each group of bubbles. The colors are defined in the ColorOrder property of the chart.
RGB triplet or hexadecimal color code	Assign one custom edge color to all the groups of bubbles: RGB triplet — A three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. Hexadecimal color code — A character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent. The two tables below provide the RGB triplets and hexadecimal color codes for some common colors.
Color name or short name	Assign one predefined edge color to all the groups of bubbles using a color name such as 'red', or a short name such as 'r'. The table below lists the available color names and short names.
'none'	Display all groups of bubbles without any edge color.

This table lists the available color names and short names with corresponding RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Output Arguments

b — Bubble cloud object

BubbleCloud object

BubbleCloud object, which is a standalone visualization. Use b to set properties on the chart after creating it.

More About

Standalone Visualization

A standalone visualization is a chart designed for a special purpose that works independently from other charts. Unlike other charts such as plot and surf, a standalone visualization has a preconfigured axes object built into it, and some customizations are not available. A standalone visualization also has these characteristics:

• It cannot be combined with other graphics elements, such as lines, patches, or surfaces. Thus, the hold command is not supported.

• The gca function can return the chart object as the current axes.

• You can pass the chart object to many MATLAB functions that accept an axes object as an input argument. For example, you can pass the chart object to the title function.

Version History

Introduced in R2021a